Python Project Template

A template repo that enables quickly setting up an end-to-end CI/CD pipeline that tests and deploys a containerized Python application. The placeholder Python logic computes a Fibonacci number.

Features ✅

• Seamless environment management via Hatch
• Lightning-fast dependency resolution via uv
• Primary dependencies and tooling configuration in the PEP-recommended pyproject.toml file
• (Sub-)dependency locking in requirements.txt files via hatch-pip-compile
• Linting and formatting using ruff
• Static type checking using mypy
• pytest for unit tests with coverage-based reporting
• ./src layout to separate application logic from tests and project metadata
• Sane logging configured in a single logging.conf file
• Optional quality-of-life add-ons:
  • pre-commit hooks installable via the hooks script of the lint Hatch environment
  • (further) enforcing of uniform formatting via an .editorconfig
  • recommended VS Code settings and extensions through a .vscode subdirectory
  • a Dev Container-based development environment

GitHub Actions CI/CD

On any pull request, do the following while targeting a stg staging environment:

• run ruff-based linting and formatting, mypy- based static type checking, and pytest-based unit testing;
• perform a CodeQL vulnerability scan;
• build and push a well-labeled container image to a Google Cloud Artifact Registry;
• execute a simple integration test on Google Cloud Run.

On merge (or push) into the main branch, additionally do the following while targeting a prd production environment:

• deploy a Cloud Run job,
• promote the container image by adding tags such as latest, main and the SemVer tag (if any).

Requirements

Ensure Hatch is installed on your system.

Development

Running the Code

Run the main.py entrypoint with the --help flag for an explanation to the application logic:

hatch run python src/python_project/main.py --help          # Uses the "default" Hatch environment.
hatch run default:python src/python_project/main.py --help  # Equivalent to not specifying "default:".

Unit Tests

Run the test script of the "test" Hatch environment to execute the pytest-backed unit tests and generate a coverage report:

hatch run test:test

Formatting, Linting and Type Checking

Run the lint script of the "lint" Hatch environment to perform (1) formatting and linting using ruff and (2) static type checking using mypy.

hatch run lint:lint

Set up pre-commit hooks that always align with the "lint" Hatch environment:

hatch run lint:hooks

Bumping the Version

Run hatch version followed by the SemVer component to bump, e.g.:

hatch version patch  # Or `hatch version minor` or `hatch version major`.

Commit the updated __version__.py script to version control before creating a git tag. Ensure the tag has the same name as the (now bumped) version:

git tag -a $(hatch version) -m 'Descriptive tag message'

License

See LICENSE.