This repository is a modern Python package template with packaging, tests, documentation, pre-commit checks, and GitHub Actions already wired together.

1. Create a new repository from this template.

2. Rename the package directory:

   PACKAGE_NAME=your_actual_package_name
   mv package_name "$PACKAGE_NAME"

3. Update package metadata in pyproject.toml:

   • project.name
   • project.version
   • project.description
   • project.authors
   • project.license
   • tool.setuptools.packages.find.include
   • coverage source and workflow coverage package names

4. Replace the sample module and tests:

   rm "$PACKAGE_NAME/module.py"
   rm tests/test_module.py

5. Install development dependencies:

   python -m pip install --upgrade pip
   python -m pip install -r requirements-dev.txt
   pre-commit install

6. Run the checks:

   pre-commit run --all-files
   python -m pytest
   python -m build

Package metadata lives in pyproject.toml using the standard PEP 621 [project] table. The template uses setuptools.build_meta and can be built with:

python -m build

Runtime dependencies belong in project.dependencies. Test, docs, and dev dependencies belong in project.optional-dependencies.

Tests live in the top-level tests/ directory and are configured through tool.pytest.ini_options in pyproject.toml.

Run tests with:

python -m pytest

Pre-commit is the source of truth for formatter and linter versions. The default stack uses Ruff for Python linting, import sorting, and formatting.

Run all hooks with:

pre-commit run --all-files

Documentation is built with Sphinx from the docs/ directory. The docs environment is installable with:

python -m pip install -r docs/requirements.txt
make -C docs html

GitHub Actions workflows are included for:

• running tests and coverage
• running pre-commit
• building documentation
• testing release candidates and building distributions

The Python support window is currently Python 3.10 through Python 3.14. Update pyproject.toml and the workflow matrices together when that changes.