Skip to content

README.md

Latest commit

 

History

History
305 lines (222 loc) · 6.95 KB

README.md

File metadata and controls

305 lines (222 loc) · 6.95 KB

Python DevContainer Environment

A ready-to-use Python 3.13 development environment using VS Code DevContainers. This project demonstrates best practices for Python package development with modern tooling, testing, and dependency management.

📋 Table of Contents

✨ Features

  • Python 3.13 development environment
  • Isolated Virtual Environment (.venv) automatically configured
  • Pre-installed VS Code Extensions:
    • Python & Pylance for IntelliSense
    • Ruff for fast linting and formatting
    • GitHub Pull Request integration
    • Error Lens for inline error highlighting
  • Modern Package Management with pyproject.toml
  • Testing Infrastructure with pytest and coverage
  • Version Management with setuptools-scm
  • Sample CLI Application demonstrating package structure

🔧 Prerequisites

🚀 Getting Started

1. Open in DevContainer

Option A: Using VS Code

  1. Clone this repository
  2. Open the folder in VS Code
  3. When prompted, click "Reopen in Container"
    • Or press F1 → "Dev Containers: Reopen in Container"

Option B: Using GitHub Codespaces

  1. Click "Code" → "Create codespace on main"
  2. Wait for the environment to build

2. Verify Installation

Once the container builds, the postCreateCommand automatically:

  • Creates a Python virtual environment in .venv
  • Installs the helloworld package in editable mode with dev dependencies

Verify the setup:

# Check Python version
python --version  # Should show Python 3.13.x

# Check that the virtual environment is active
which python  # Should point to .venv/bin/python

# Test the example CLI
helloworld

3. Explore the Sample Application

# Run the CLI with default greeting
helloworld
# Enter your name: World
# Output: Hello, World!

# Run with a name option
helloworld --name Alice
# Output: Hello, Alice!

# Run tests
cd helloworld
pytest

# Run tests with coverage
pytest --cov=helloworld --cov-report=term-missing

# Lint the code
ruff check .

# Format the code
ruff format .

📁 Project Structure

.
├── .devcontainer/
│   └── devcontainer.json          # DevContainer configuration
├── helloworld/                    # Example Python package
│   ├── pyproject.toml             # Package metadata and dependencies
│   ├── helloworld/                # Source code
│   │   ├── __init__.py
│   │   ├── __main__.py            # CLI entry point
│   │   └── hello.py               # Core functionality
│   └── tests/                     # Test suite
│       ├── test_hello.py
│       └── test_entrypoints.py
├── freeze_version.py              # Version management helper
├── LICENSE
└── README.md                      # This file

🛠️ Development Workflow

Running Tests

cd helloworld

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_hello.py

# Run with coverage
pytest --cov=helloworld --cov-report=html

Linting and Formatting

cd helloworld

# Check for linting issues
ruff check .

# Auto-fix linting issues
ruff check --fix .

# Format code
ruff format .

Installing Additional Dependencies

# Activate virtual environment (if not already active)
source .venv/bin/activate

# Install a new package
pip install package-name

# Add to pyproject.toml dependencies
# Then reinstall in editable mode
pip install -e helloworld[dev]

Version Management

This project uses setuptools-scm for automatic version management based on Git tags:

# Check current version
python -c "from setuptools_scm import get_version; print(get_version())"

# Freeze version to JSON file
python freeze_version.py

📦 Example Package: helloworld

The included helloworld package demonstrates:

  • Package Structure: Modern pyproject.toml configuration
  • CLI Tool: Built with Click framework
  • Logging: Using Loguru for structured logging
  • Testing: Pytest setup with test coverage
  • Entry Points: Console script registration
  • Dependencies:
    • aiohttp - Async HTTP client
    • click - CLI framework
    • loguru - Logging
    • pydantic - Data validation
    • rich - Terminal formatting

CLI Usage

# Interactive mode
helloworld

# With arguments
helloworld --name "Python Developer"

# Get help
helloworld --help

Importing as Library

from helloworld.hello import hello

message = hello("Developer")
print(message)  # Output: Hello, Developer!

🎨 Customizing for Your Project

1. Replace the Example Package

# Remove the example package
rm -rf helloworld/

# Create your own package structure
mkdir -p myproject
cd myproject

2. Create Your pyproject.toml

[project]
name = "myproject"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.13"
dependencies = [
    # Add your dependencies here
]

[project.optional-dependencies]
dev = [
    "pytest",
    "ruff",
]

3. Update DevContainer Configuration

Edit .devcontainer/devcontainer.json:

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/python:3.13",
  "postCreateCommand": "python -m venv .venv && .venv/bin/pip install -e myproject[dev]",
  ...
}

4. Rebuild Container

  • Press F1 → "Dev Containers: Rebuild Container"

🐛 Troubleshooting

Virtual Environment Not Active

source .venv/bin/activate

Package Not Found After Changes

pip install -e helloworld[dev]

Container Build Fails

  1. Check Docker is running
  2. Try rebuilding: F1 → "Dev Containers: Rebuild Container Without Cache"
  3. Check .devcontainer/devcontainer.json syntax

Import Errors

Ensure you're in the virtual environment and the package is installed in editable mode:

which python  # Should show .venv/bin/python
pip list | grep helloworld

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

This is a template project. Feel free to fork and customize for your needs!

📚 Additional Resources