Skip to content

Python Project Template

PyPI version python uv Ruff Pydantic v2 tests code-quality Ask DeepWiki license PRs contributors

🚀 A production‑ready Python project template to help developers bootstrap new Python projects fast. It includes modern packaging, local tooling, Docker, and a complete CI/CD suite.

Important: This is a template repository. Do not develop directly on this repository. Instead, use it to create your own project by clicking the button below and following the setup instructions.

Click Use this template to start a new repository from this scaffold.

Other Languages: English | 繁體中文 | 简体中文

✨ Highlights

  • Modern src/ layout and type‑hinted code
  • Fast dependency management via uv
  • Pre‑commit suite: ruff, mdformat(+plugins), codespell, nbstripout, mypy, uv hooks
  • Strong typing: mypy with Pydantic plugin configuration
  • Pytest with coverage and xdist; PR coverage summary comment
  • Coverage gate at 80% with HTML/XML reports committed under .github/
  • MkDocs Material with mkdocstrings (inheritance diagrams), markdown‑exec, MathJax
  • Dev server at 0.0.0.0:9987; bilingual docs scaffolded
  • Docs generator script: by class/file, optional notebook execution, concurrency, preserves folder structure
  • Async file processing via anyio and rich progress bars
  • Packaging with uv build and changelog via git-cliff
  • Automatic PEP 440 versioning from git via dunamai in CI
  • Dockerfile multi‑stage with uv/uvx and Node.js; Compose services (Redis/Postgres/Mongo/MySQL) with healthchecks and volumes
  • GitHub Actions: tests, quality, docs deploy, package build, docker image publish (GHCR with buildx cache), release drafter, auto labeler, secret scan, semantic PR, pre‑commit auto‑update
  • Pre‑commit runs on multiple git stages (pre‑commit, post‑checkout, post‑merge, post‑rewrite)
  • i18n‑friendly linting (Chinese punctuation allowed confusables)
  • Alternative env managers documented (Rye, Conda)
  • Legacy compatibility: export requirements.txt via uv pip if needed

🚀 Quick Start

For Template Users (Creating a New Project)

This is the recommended workflow for starting a new project:

  1. Create Your Repository: Click Use this template to create a new repository

  2. Clone and Setup:

    git clone https://github.com/YOUR_USERNAME/your_new_project.git
cd your_new_project
make uv-install               # Install uv (only needed once)
uv sync                       # Install dependencies
uv tool install pre-commit    # Install pre-commit

  3. Rename the Project:

    • Rename src/repo_template/ directory to src/your_project_name/
    • Update all imports from repo_template to your_project_name
    • Update pyproject.toml with your project details:
      • Project name, version, description, authors
      • Homepage and Repository URLs
      • CLI script names if needed
    • Update mkdocs.yml: site_name, site_url, repo_name, repo_url, site_author
    • Update all three README files (preserve badges, only update URLs)
    • Update .github/CODEOWNERS with your GitHub username
    • Update Docker labels in docker/Dockerfile and .devcontainer/Dockerfile

  4. Verify Setup:

    make format                   # Run pre-commit hooks
make test                     # Run tests
uv run your_project_name      # Test your CLI

For Template Developers (Testing This Template)

If you're contributing to this template:

make uv-install               # Install uv
uv sync                       # Install dependencies
uv tool install pre-commit    # Install pre-commit
make format                   # Run pre-commit hooks
make test                     # Run tests
uv run repo_template          # Test example CLI

🧰 Commands Reference

# Development
make help               # List available make targets
make clean              # Clean caches, artifacts and generated docs
make format             # Run all pre-commit hooks
make test               # Run pytest across the repository
make gen-docs           # Generate docs from src/ and scripts/

# Git submodules (if you use them)
make submodule-init     # Init and update all submodules
make submodule-update   # Update all submodules to remote

# Dependencies (via uv)
make uv-install         # Install uv on your system
uv add <pkg>            # Add production dependency
uv add <pkg> --dev      # Add development dependency
# Sync optional groups
uv sync --group dev     # Install dev-only deps (pre-commit, poe, notebook)
uv sync --group test    # Install test-only deps
uv sync --group docs    # Install docs-only deps

📚 Documentation

  • Live docs are built with MkDocs Material.
  • Generate API docs locally and serve:
uv sync --group docs
make gen-docs
uv run mkdocs serve    # http://localhost:9987
  • Auto generation script: scripts/gen_docs.py (supports .py and .ipynb)
# Generate docs by class (default)
uv run python ./scripts/gen_docs.py --source ./src --output ./docs/Reference gen_docs

# Generate docs by file
uv run python ./scripts/gen_docs.py --source ./src --output ./docs/Reference --mode file gen_docs

🐳 Docker and Local Services

docker-compose.yaml includes optional services for local development: redis, postgresql, mongodb, mysql, and an example app service that runs the CLI.

Create a .env file to configure ports and credentials (defaults shown):

REDIS_PORT=6379
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_PORT=5432
MONGO_PORT=27017
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=mysql
MYSQL_USER=mysql
MYSQL_PASSWORD=mysql
MYSQL_PORT=3306

Run services:

docker compose up -d redis postgresql mongodb mysql

# Or run the example app container
docker compose up -d app

📦 Packaging and Distribution

Build artifacts with uv (wheel and sdist go to dist/):

uv build

Publish to PyPI (requires UV_PUBLISH_TOKEN):

UV_PUBLISH_TOKEN=... uv publish

CI builds automatically run on tags matching v*, building multi-platform executables and Python packages, then uploading them to GitHub Release. To automate releases to PyPI, add the UV_PUBLISH_TOKEN secret in your repository settings (build_release.yml is already configured for automatic publishing).

Run your CLI locally and from PyPI

  • Local (from this repo):
uv run repo_template
uv run cli
  • From PyPI with uvx after publishing (ephemeral install):
# If your console script is named "repo_template"
uvx repo_template

# Disambiguate or pin a package/version
uvx --from your-package-name==0.1.0 your-entrypoint

🧭 Optional task runner (Poe the Poet)

Convenience tasks are defined under [tool.poe.tasks] in pyproject.toml and available after installing the dev group (uv sync --group dev) or via uvx:

uv run poe docs        # generate + serve docs (requires dev group)
uv run poe gen         # generate + deploy docs (gh-deploy) (requires dev group)
uv run poe main        # run CLI entry (same as uv run repo_template)

# or ephemeral via uvx (no local install)
uvx poe docs

🔁 CI/CD Actions Overview

All workflows live in .github/workflows/. This section explains what each action does, when it runs, and what to configure.

  • Tests (test.yml)

    • Trigger: Pull requests to main or release/* (ignores md files)
    • Runs pytest on Python 3.11/3.12/3.13/3.14 with coverage and comments a summary
    • Setup needed: none

  • Code Quality Check (code-quality-check.yml)

    • Trigger: Pull requests
    • Runs ruff and other pre-commit hooks
    • Setup needed: none

  • Docs Deploy (deploy.yml)

    • Trigger: Push to main and tags v*
    • Builds mkdocs site and publishes to GitHub Pages
    • Setup needed:
      • Enable GitHub Pages for the repo (Actions → Pages)
      • The workflow configures and uploads the site automatically

  • Build and Release (build_release.yml)

    • Trigger: Tags v* push or manual workflow dispatch
    • Builds multi-platform executables (via PyInstaller):
      • macOS (ARM64, x64)
      • Linux (x64 GNU, ARM64 GNU)
      • Windows (x64, ARM64)
    • Builds Python package (wheel & sdist)
    • Automatically publishes to PyPI (requires UV_PUBLISH_TOKEN secret)
    • Uploads all artifacts to GitHub Release
    • Note: This is a template demonstration workflow. Adjust to your project needs.

  • Publish Docker Image (build_image.yml)

    • Trigger: Push to main and tags v*
    • Builds and pushes a Docker image to GHCR: ghcr.io/<owner>/<repo>
    • Setup needed: none (uses GITHUB_TOKEN); ensure docker/Dockerfile defines prod target

  • Release Drafter (release_drafter.yml)

    • Trigger: Push to main and PR events
    • Maintains a draft release based on Conventional Commits

  • Pull Request Labeler (auto_labeler.yml)

    • Trigger: PRs and pushes
    • Auto-applies labels defined in .github/labeler.yml

  • Secret Scanning (secret_scan.yml)

    • Trigger: Push and PR
    • Runs gitleaks to detect leaked secrets

  • Semantic Pull Request (semantic-pull-request.yml)

    • Trigger: PR open/edit/sync
    • Enforces Conventional Commit style PR titles

CI/CD Configuration Checklist

  • Conventional commits for PR titles (enforced by the workflow)
  • Optional: set UV_PUBLISH_TOKEN secret to publish to PyPI (Settings → Secrets and variables → Actions)
  • Optional: enable GitHub Pages for docs deployment (Settings → Pages → Source: GitHub Actions)
  • Optional: ensure GHCR permissions for Docker image publishing (Settings → Actions → General → Workflow permissions: Read and write)
  • Container Registry permissions are handled automatically via GITHUB_TOKEN

🧩 Example CLI

Console entry points are defined in pyproject.toml as repo_template and cli. The example returns a simple Response model; replace with your own CLI logic.

uv run repo_template

🤝 Contributing

  • Open issues/PRs
  • Follow the coding style (ruff, type hints)
  • Use Conventional Commit messages and descriptive PR titles

📄 License

MIT — see LICENSE.