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
• Prerequisites
• Getting Started
• Project Structure
• Development Workflow
• Example Package: helloworld
• Customizing for Your Project
• Troubleshooting

✨ 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

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

🚀 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 testscd 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

fromhelloworld.helloimporthellomessage=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

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