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.

• Features
• Prerequisites
• Getting Started
• Project Structure
• Development Workflow
• Example Package: helloworld
• Customizing for Your Project
• Troubleshooting

• 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

• VS Code with the Dev Containers extension
• Docker Desktop or compatible container runtime
• Git (for version control)

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

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

# 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 .

.
├── .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

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

cd helloworld

# Check for linting issues
ruff check .

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

# Format code
ruff format .

# 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]

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

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

# Interactive mode
helloworld

# With arguments
helloworld --name "Python Developer"

# Get help
helloworld --help

from helloworld.hello import hello

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

# Remove the example package
rm -rf helloworld/

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

[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",
]

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]",
  ...
}

• Press F1 → "Dev Containers: Rebuild Container"

source .venv/bin/activate

pip install -e helloworld[dev]

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

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

MIT License - see LICENSE file for details.

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

• VS Code DevContainers Documentation
• Python Packaging Guide
• pytest Documentation
• Ruff Documentation
• Click Documentation