A skeleton Python project with best practices for development, code quality, and tooling.

This project provides a structured and opinionated setup, including:

• Virtual Environment management
• Linting, formatting, static type checking
• Testing and coverage
• VS Code integration
• Pre-commit hooks

Follow the documentation to configure your environment and tools.

This is an example Python repository that can be adapted to any project. To adapt your project, you can follow the project migration notes.

• Introduction
• Prerequisites
• Setting up a Virtual Environment
• Running the application
• Development
• Code Quality
• Visual Studio Code
• License
• Contact
• Appendix

• Linux OS or WSL2 on Windows
• VS Code
• Python 3.7+

Virtual environments isolate project dependencies. Use venv or the experimental Rust-based uv. See the Appendix for more info on uv.

python3 -m venv .venv  # using venv
# or
uv venv  # using uv (if installed)
source .venv/bin/activate

Use pyproject.toml for modern dependency management.

pip install -r pyproject.toml
# or
uv pip install -r pyproject.toml  # using uv

Lock dependencies:

pip freeze > requirements.txt

Activate the virtual environment and run:

export PYTHONPATH="$PWD:$PYTHONPATH"
python3 -m src.main  # Adjust 'src.main' to your module's entry point

Install development dependencies:

pip install -r requirements-dev.txt
# or
uv pip install -r requirements-dev.txt  # using uv

Maintain code quality with the following tools.

Code standards are upheld by using the following packages: ruff, flake8, pylint, and mypy. The first three are linters, and perform similar, overlapping, linting functions, while mypy focuses on static type checking. Their configurations are predefined but can be tailored to meet the application's specific requirements.

ruff check [file]  # to list issues
ruff check --fix [file]  # to auto-fix issues
flake8 **/*.py
pylint **/*.py
mypy **/*.py

Use ruff for consistent code style.

ruff format [file]  # to format all files, or a single one
ruff format --diff [file]  # to print the proposed changes

Run tests and check coverage with pytest and coverage.

pytest  # to run the whole suite of tests
coverage run -m pytest  # to generate a coverage report
coverage report -m  # to see the report

Automate checks with pre-commit. pre-commit integrates with git, running specified hooks before certain git commands. This setup ensures that tests, linting, and formatting are automatically performed, promoting consistent code quality.

pre-commit install
pre-commit run --all-files
pre-commit autoupdate

To bypass a hook temporarily, for instance, to address a failed test in a subsequent commit:

SKIP pytest-check git commit -m "Commit message.."

To run the hooks outside of git commands, use pre-commit run. To update the hooks, use pre-commit autoupdate, and then commit the changes.

Specific information about using VS Code for development are given here.

The project is operating under an MIT license.

For questions or suggestions, please contact us at email or open an issue.

Install uv via official documentation. Update uv with:

uv self update

uv venv
source .venv/bin/activate
uv pip install -r pyproject.toml
uv pip install -r requirements-dev.txt