pypkgkit 2.1.0

A template for python packages

pypkgkit

A minimal, opinionated template for Python packages.

The goal is straightforward: provide a single starting point that assembles modern Python tooling into a coherent whole, so that new projects begin with CI, documentation, and release automation already in place — rather than reinventing this infrastructure each time.

What is included

Concern	Tool
Package management	uv
Linting & formatting	Ruff
Type checking	ty
Testing	pytest
Documentation	ProperDocs (MkDocs Material + mkdocstrings)
Versioning & releases	python-semantic-release with Conventional Commits
CI/CD	GitHub Actions (lint, type check, test across 3.10 – 3.13, build, release to PyPI, deploy docs)
Dependency updates	Dependabot (weekly, for both Actions and pip)
Pre-commit hooks	Ruff, ty, license headers, conventional commit validation

Requirements

• Python 3.10 or later
• uv installed

Getting started

Clone the repository and install dependencies:

git clone https://github.com/michaelellis003/pypkgkit.git
cd pypkgkit
uv sync

Install the pre-commit hooks:

uv run pre-commit install
uv run pre-commit install --hook-type commit-msg
uv run pre-commit install --hook-type pre-push

Development

A Makefile is provided for common tasks:

make test        # lint + pytest
make lint        # ruff check, format check, license headers, ty
make format      # add license headers, ruff format, ruff fix
make license     # add missing license headers
make docs        # build documentation
make serve-docs  # serve documentation locally
make install     # uv sync
make clean       # git clean (preserves .venv)

Or invoke tools directly:

uv run pytest -v
uv run ruff check .
uv run ruff format .
uv run ty check
uv run properdocs serve

How releases work

Releases are fully automated. When a commit lands on main and CI passes, python-semantic-release inspects the commit history to determine whether a version bump is warranted:

• fix: ... produces a patch release (0.1.0 → 0.1.1)
• feat: ... produces a minor release (0.1.0 → 0.2.0)
• A BREAKING CHANGE footer or ! suffix produces a major release (0.1.0 → 1.0.0)

If a bump is triggered, the pipeline updates the version in pyproject.toml and src/pypkgkit/__init__.py, creates a Git tag and GitHub release, generates the changelog, builds the package, and publishes it to PyPI via trusted publishing. Documentation is deployed to GitHub Pages immediately after.

Commit messages that do not follow the Conventional Commits spec are rejected by a pre-commit hook, so the release process stays well-defined.

License

Apache 2.0. See LICENSE for the full text.