Python Project Template

Read the docs!

This repository is a template for a basic Python project. Included here is:

• Example Python package
• Tests
• Documentation
• Automatic incremental versioning
• CI/CD
  • Installs and tests the package
  • Builds documentation on branches
  • Deploys documentation on main branch
  • Deploys docker image to AWS ECR
• Githook to ensure linting and code checking

Getting Started

Using the Githook

From the root directory of the repo, run:

git config --local core.hooksPath .githooks/

This will set this repo up to use the git hooks in the .githooks/ directory. The hook runs ruff format --check and ruff check to prevent commits that are not formatted correctly or have errors. The hook intentionally does not alter the files, but informs the user which command to run.

Installing the package

You can install everything needed to run the project (even including Python) with uv.

uv sync

It will set up a Python virtualenv in .venv. Activate it as normal with . .venv/bin/activate or prefix commands with uv run. In fact, uv run will automatically set things up with no need for uv sync. You can add packages with uv add and remove them with uv remove.

Making it Your Own

This repo has a single package in the ./src/... path called mypackage (creative I know). Change this to the name of your package and update it in:

• docs/conf.py
• src/**/*.py
• tests/**/*.py
• pyproject.toml

To make thing move a bit faster, use the script ./rename-package.sh to rename all references of mypackage to whatever you like. For example:

./rename-package.sh "acoolnewname"

Will rename the package and all references to "acoolnewname"

After doing this it is recommended to also run:

cd docs
make apidoc

To keep your documentation in sync with the package name. You may need to delete a file called mypackage.rst from ./docs/sources/...

Deploying Docs to GitHub Pages

If you want docs to be published to github pages automatically, go to your repo settings and enable docs from GitHub Actions and the workflows will do the rest.

Building Docs Locally

The documentation is driven by Sphinx an industry standard for documentation with a healthy userbase and lots of add-ons. It uses sphinx-apidoc to generate API documentation for the codebase from Python docstrings.

To run sphinx-apidoc run:

cd docs
make apidoc

This will populate ./docs/sources/... with *.rst files for each Python module, which may be included into the documentation.

Documentation can then be built locally by running make html, or found on the GitHub Deployment.

Run the Tests

To run the tests run:

pytest

Automatic Versioning

This codebase is set up using autosemver a tool that uses git commit history to calculate the package version. Each time you make a commit, it increments the patch version by 1. You can increment by:

• Normal commit. Use for bugfixes and small updates
  • Increments patch version: x.x.5 -> x.x.6
• Commit starts with * NEW:. Use for new features
  • Increments minor version x.1.x -> x.2.x
• Commit starts with * INCOMPATIBLE:. Use for API breaking changes
  • Increments major version 2.x.x -> 3.x.x

Docker and the ECR

The python code is packaged into a docker image and pushed to the AWS ECR. For the deployment to succeed you must:

• Add 2 secrets to the GitHub Actions:
  • AWS_REGION: <our-region>
  • AWS_ROLE_ARN: <the-IAM-role-used-to-deploy>
• Add a repository to the ECR with the same name as the GitHub repo