BrianPugh/python-template: Python project and library template for clean, reliable, open-source projects. · GitHub

A template to quickly get you creating an open-source python library or project with linting, static analysis, CI, and CD to PyPI.

To use this template, click the green "Use this template" button in the github web interface. Then run:

git clone YOUR_REPO
# then cd into your local repo, and run:
./bootstrap

And follow the on-screen prompts. bootstrap uses some git data (like detecting your username and repository name), so cloning the repo generated from the template is necessary.

General sanity checks and best practices are performed on provided responses. To disable these, run with the --no-verify flag:

./bootstrap --no-verify

This template's bootstrap functionality only works on MacOS/Linux/WSL, it will not work natively on windows. The resulting project, however, may be windows-compatible.

• Features dependent if project is a library or a standalone project.

• uv support.

  • If not installed, uv will automatically be installed when running bootstrap.
  • setuptools-scm - Dynamically handles your project version based on git tags.

• Optional command line interface boilerplate using Cyclopts.

• Optional C binding support via Cython.

• Sphinx + ReadTheDocs.

  • To setup, goto ReadTheDocs Dashboard and click on "Import a Project".

  • To locally build the docs:

    cd docs/
    make html

    This results in html files in docs/build/html/. Double click docs/build/html/index.html to view the docs in your web browser.

• Pre-commit linting and static analysis. The following hooks are pre-configured and will automatically run on git commit:

  • Ruff - An extremely fast Python linter and formatter.
  • Creosote - Identifies unused dependencies.
  • Codespell - Checks code and documentation for common misspellings.
  • Pyright - Static type checker.
  • On CI, lightweight hooks run on pre-commit.ci, which also auto-fixes pull requests and auto-updates hook versions weekly. Enable it for your repository at https://pre-commit.ci.

• Docker support for standalone projects.

• GitHub Actions for:

  • Running pre-commit on pull requests and commits to main.

  • Running unit tests, coverage, and verify docs build on pull requests and commits to main.

    • Goto your Codecov Dashboard and add your repo.

  • Build and upload wheels to PyPI on semver tags vX.Y.Z.

    • Publishing uses a PyPI Trusted Publisher (OIDC); no API token or GitHub secret is required. To set it up, go to PyPI -> Your account -> Publishing -> "Add a new pending publisher" and enter:

      • PyPI Project Name: your project name.
      • Owner / Repository name: your GitHub username and repository name.
      • Workflow name: build_wheels.yaml if using Cython, otherwise deploy.yaml.
      • Environment name: pypi.

      The first tagged release will then create the PyPI project automatically.

    • If using Cython, pre-built binary packages will be created for all major operating systems, python versions, and computer architectures.

  • Build and upload docker images to Dockerhub.

    • Add your Dockerhub username and token to your GitHub secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN.
    • Optionally, modify the tags field in .github/workflows/docker.yaml. By default, it assumes your docker username is the same as your github username.

This template has an option to add boilerplate for Cython. Cython is a programming language that simplifies the creation of C extensions for Python. The Cython documentation is quite good; the aim of this section is to explain what this template sets up, and what actions will still need to be performed by you. This explanation assumes you are familiar with C. Replace any reference here to pythontemplate with your project name.

1. Place all C and header files in the pythontemplate/_c_src directory. If you don't plan on using any explicit C files, you may delete this directory.
2. Update pythontemplate/cpythontemplate.pxd with header information from the files in (1). Example of common definitions (functions, structs, and enums) are provided. Think of *.pxd as a header file that allows Cython .pyx code to access pure C .c files. This file will be compiled into a package of the same name that can be imported in a .pyx file via cimport. If you don't plan on using any explicit C files, you may delete this file and the _c_src directory.
3. Add Cython code to pythontemplate/_c_extension.pyx. Some class starter code is provided. This is where a good pythonic interface (functions and classes) should be written.
4. If adding type hints, update pythontemplate/_c_extension.pyi to reflect your .pyx implementation.
5. Optionally tweak setup.py (runs at setup/installation) with compiler options. The default setup.py offers a good, working starting point for most projects and performs the following:
   1. Recursively searches for all C files in pythontemplate/_c_src/. To change this action, modify the variable c_files.
   2. Compiles the code defined in _c_extension.pyx into a shared object file.
   3. Adds pythontemplate and pythontemplate/_c_src to the Include Path (python variable include_dirs).
   4. If your codebase contains a slower, python implementation of your Cython code, we can allow building to fail by uncommenting the allowed_to_fail logic at the top. The logic checks for the environment variable CIBUILDWHEEL because we don't want to allow build failures in our CI when creating pre-built wheels that we upload to PyPI.
   5. [tool.uv] in pyproject.toml sets cache-keys so that changes to Cython/C sources trigger a rebuild on the next uv sync.
6. The Github Action workflow defined in .github/workflows/build_wheels.yaml will create pre-built binaries for all major Python versions, operating systems, and computer architectures. It will also create a Source Distribution (sdist). All of these distributions will be uploaded to the github action job page. On git semver tags (vX.X.X), they will be uploaded to PyPI.

When developing, you must re-run uv sync to re-compile changes made in C/Cython code. The resulting, built Cython code will be importable from pythontemplate._c_extension, so it may be good to add something like the following to your pythontemplate/__init__.py:

__all__ = [
   "Foo",
]
from pythontemplate._c_extension import Foo

If you find this in the git history of a project and you like the structure, visit this template at https://github.com/BrianPugh/python-template .