Python project template

What is Python project template?

Python project template is a starter repository for any Python project, pre-configured with modern development tools. It includes ruff and black for linting and formatting, pytest with coverage for testing, and GitHub Actions to run checks automatically on every pull request and merge. It also provides a devcontainer for a consistent, containerized development environment.

How to use Python project template?

Use the template by creating a new repository from it. You can open it in GitHub Codespaces to automatically initialize the devcontainer, or open it locally in VS Code with the Dev Containers extension. Without a devcontainer, create a virtual environment, install the required packages from requirements-dev.txt, and run pre-commit install. Replace the sample main.py and tests/main_test.py with your own code. Run tests with python3 -m pytest.

Key features of Python project template

• Pre-installed linting with ruff (includes flake8, isort, pyupgrade)
• Code formatting with black
• Testing with pytest and coverage plugin pytest-cov
• Pre-commit hooks for automatic checks
• GitHub Actions CI triggered on pull requests and merges
• Devcontainer configuration for reproducible environments
• Default setup for Python 3.11, easily changeable

Use cases of Python project template

• Starting a new Python project with best practices for code quality
• Ensuring consistent linting, formatting, and testing across a team
• Setting up continuous integration without manual configuration
• Using a containerized development environment for reproducibility
• Learning how to structure a modern Python project with dev tools

FAQ from Python project template

What development tools are included in the template?

The template includes ruff (linting), black (formatting), pre-commit hooks, pytest, and the pytest-cov plugin. Checks and tests are run via GitHub Actions.

How do I change the default Python version from 3.11?

To change the Python version, update the image argument in .devcontainer/devcontainer.json, adjust the config options in .precommit-config.yaml, and change the version number in .github/workflows/python.yaml.

How can I run the tests?

Run python3 -m pytest from the root of the repository. The template includes a sample test in tests/main_test.py.

Where can I find a detailed explanation of the template files?

The README includes a file breakdown section explaining each file and folder. A longer blog post is linked at the bottom of the README.

Does the template include production dependencies?

Yes, requirements.txt lists production dependencies, while requirements-dev.txt lists packages needed only for development (e.g., tools and test libraries).