How to Customize Your Project¶

This guide shows you how to modify common settings in a project generated from the template. These changes are safe to make and will be preserved when you update from the template.

Prerequisites¶

uv installed
A project generated with uvx copier copy gh:stateful-y/python-package-copier my-package

Customize Ruff Rules¶

Edit pyproject.toml to adjust linting and formatting:

[tool.ruff]
line-length = 88  # Change from default 120

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "ARG", "SIM", "PL", "T201"]
ignore = ["PLR0913"]  # Allow many arguments

Run just fix to apply the new rules.

Adjust Coverage Thresholds¶

The default coverage threshold is intentionally permissive (fail_under = 1). To increase it:

[tool.coverage.report]
fail_under = 80  # Require 80% coverage

Customize Pre-commit Hooks¶

Edit .pre-commit-config.yaml to add or remove hooks. For example, to add a security scanner:

- repo: https://github.com/PyCQA/bandit
  rev: 1.8.3
  hooks:
    - id: bandit
      args: ["-r", "src/"]

After editing, run the hooks:

uv run prek run --all-files

Most hooks have no rev to update: the repo: builtin hooks are pinned by prek's own version, and the linters resolve from uv.lock. Both are kept current by Dependabot's uv ecosystem. uv run prek update bumps the remaining pinned rev: — today only commitizen's — and is not something you should need routinely.

Customize the Docstring Coverage Threshold¶

The default requires 75% docstring coverage. To change it:

[tool.interrogate]
fail-under = 90  # Require 90% docstring coverage

Add Custom Nox Sessions¶

Edit noxfile.py to add project-specific automation sessions. For example, a benchmarking session:

@nox.session(python=PYTHON_VERSIONS[0])
def benchmark(session: nox.Session) -> None:
    """Run performance benchmarks."""
    session.install(".[tests]", "pytest-benchmark")
    session.run("pytest", "benchmarks/", "--benchmark-only")

Customize Documentation Theme¶

Edit mkdocs.yml to change the theme colors, logo, or features:

theme:
  palette:
    - scheme: default
      primary: blue  # Change color
      accent: amber

Common Variations¶

Switching build backend: Possible but requires updating pyproject.toml [build-system] and removing hatch-vcs config
Adding a CLI: Add an entry point in pyproject.toml [project.scripts] and create the CLI module