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, target a stg staging environment and:

• 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 an integration test on Google Cloud Run that runs the application logic end-to-end.

On a commit/tag being merged/pushed (in)to the main branch, target a prd production environment and:

• perform the same steps as above;
• deploy a Cloud Run job;
• promote the now-vetted container image by adding tags such as latest, main and the SemVer tag (if any).

Requirements

Ensure Hatch is installed on your system. With Hatch installed, there is no need to manually create environments and install dependencies; that is all handled by Hatch.

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_template/main.py --help          # Uses the "default" Hatch environment.
hatch run default:python src/python_project_template/main.py --help  # Equivalent to not specifying "default:".

Unit Testing

The test Hatch environment defines scripts that can be used to execute and debug the pytest-backed unit tests and generate a coverage report:

hatch run test:test                      # To run all unit tests under the `./tests` subdirectory.
hatch run test:test tests/test_utils.py  # To execute the `tests/test_utils.py` unit tests.
hatch run test:debug                     # To perform unit testing in `pytest` debug mode.
hatch run test:cov-xml                   # To generate a `coverage.xml` that can be consumed by code scanners.

Formatting, Linting and Type Checking

The lint Hatch environment defines scripts to (1) perform ruff-based formatting and linting, (2) run mypy-based static type checking and (3) set up pre-commit hooks synced with the environment:

hatch run lint:lint    # To run a `ruff`-based style check followed by `mypy` type checking.
hatch run lint:style   # To run (only) a `ruff`-based style check.
hatch run lint:typing  # To run (only) `mypy`-based type checking.
hatch run lint:fix     # To attempt to fix issues identified by `ruff`.
hatch run lint:hooks   # To set up `pre-commit` hooks that always align with the "lint" Hatch environment.

Upgrading Dependencies

hatch run upgrade-all                          # To upgrade all Python dependencies of the `default` Hatch environment.
hatch run upgrade-pkg $PACKAGE_NAME            # To upgrade $PACKAGE_NAME in the `default` Hatch environment.
hatch run $ENV_NAME:upgrade-all                # To upgrade all Python dependencies in the specified Hatch environment.
hatch run $ENV_NAME:upgrade-pkg $PACKAGE_NAME  # To upgrade $PACKAGE_NAME in the specified Hatch environment.

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.