copier-astral - Python Project Template with Astral Toolchain

Overview

copier-astral is an opinionated Copier template for bootstrapping Python projects using Astral's modern toolchain. It provides batteries-included project scaffolding with linting (ruff), type checking (ty), package management (uv), testing (pytest + hatch), documentation (MkDocs), CLI framework (Typer), and CI/CD (GitHub Actions) pre-configured and ready to use.

Core Value Proposition: Generate production-ready Python project structure in seconds with modern Astral tooling (uv, ruff, ty) instead of legacy pip/flake8/mypy, eliminating hours of boilerplate configuration.

Problem Addressed

Key Statistics (as of January 31, 2026)

Key Features

1. Astral Toolchain Integration

2. Testing Infrastructure

• pytest: Industry-standard test framework
• hatch: Multi-version testing with matrix envs
• pytest-cov: Coverage reporting with Codecov integration
• Matrix testing: Python 3.10, 3.11, 3.12, 3.13 support

3. Documentation

• MkDocs: Static site generator
• Material theme: Modern, responsive documentation
• mkdocstrings: Auto-generate API docs from docstrings
• GitHub Pages: Automatic deployment via Actions

4. CLI Support (Optional)

• Typer: Modern CLI framework with type hints
• Pre-configured entry point in pyproject.toml
• Help text and command structure ready

5. CI/CD Workflows

• Test workflow: Runs on PR and push to main
• Lint workflow: Ruff + ty checks
• Docs workflow: Build and deploy to GitHub Pages
• Release workflow: Automatic PyPI publishing on tag
• Codecov integration: Coverage badge and reports

6. Containerization (Optional)

• Dockerfile: Multi-stage build for minimal image size
• Docker Compose: Development environment setup
• Production-ready container configuration

7. Code Quality

• pre-commit hooks: Enforced formatting and linting
• Ruff configuration: Comprehensive rule set in pyproject.toml
• Type annotations: Strict typing enforced by ty

8. Template Options

Technical Architecture

Installation & Usage

Prerequisites

# Install Copier
pip install copier

# Install required extension for custom Jinja2 filters
pip install copier-template-extensions

Generate a Project

# From GitHub (recommended)
copier copy --trust gh:ritwiktiwari/copier-astral my-project

# From local clone
copier copy --trust /path/to/copier-astral my-project

Note: The --trust flag is required because the template uses custom Jinja2 extensions for auto-detecting git user info and generating slugified package names.

Post-Generation Setup

cd my-project

# Initialize git and install dependencies
git init -b main
make install

# Activate virtual environment
source .venv/bin/activate

# Install pre-commit hooks (if enabled)
pre-commit install
uv run pre-commit run -a

# Verify everything works
make verify
make test

Development Commands

Releasing

# Create version tag (triggers PyPI publish workflow)
git tag v0.1.0
git push --tags

Updating Existing Projects

# Sync with latest template improvements
copier update --trust

Generated Project Structure

Relevance to Claude Code Development

Direct Applications

1. Plugin Scaffolding: Use as base template for generating new Claude Code plugins with consistent structure
2. Skill Development: Bootstrap Python-based skills with proper testing and type checking
3. MCP Server Templates: Foundation for creating MCP servers with Astral tooling
4. Agent Infrastructure: Scaffold agent implementations with production-ready CI/CD

Patterns Worth Adopting

1. Astral Toolchain: uv + ruff + ty combination is significantly faster than legacy pip + flake8 + mypy
2. Makefile Abstraction: Simple make verify, make test commands abstract complex uv/hatch invocations
3. Copier Update Mechanism: Template improvements can propagate to existing projects via copier update
4. Feature Toggles: Conditional file generation based on boolean options is clean for customization
5. Matrix Testing: Hatch envs for multi-Python testing without Docker complexity
6. Single Source of Truth: pyproject.toml contains all tool configurations (ruff, pytest, hatch, etc.)

Integration Opportunities

1. claude-code-plugin-template: Fork/adapt for Claude Code plugin-specific scaffolding
2. mcp-server-template: Specialize for MCP server projects with FastMCP defaults
3. skill-template: Create skill-specific variant with SKILL.md and references/ structure
4. Pre-commit Integration: This repo already uses prek - could sync ruff configurations

Key Insight

copier-astral demonstrates the modern Python tooling stack that Claude Code-related projects should adopt. The Astral toolchain (uv, ruff, ty) provides 10-100x performance improvements over legacy tools while maintaining compatibility. The Copier template mechanism allows project structure standardization with the ability to propagate improvements to existing projects - a pattern applicable to Claude Code plugin/skill templates.

References

1. Documentation Site: https://ritwiktiwari.github.io/copier-astral/ (accessed 2026-01-31)
2. GitHub Repository: https://github.com/ritwiktiwari/copier-astral (accessed 2026-01-31)
3. User Guide: https://ritwiktiwari.github.io/copier-astral/guide/ (accessed 2026-01-31)
4. Template Options: https://ritwiktiwari.github.io/copier-astral/options/ (accessed 2026-01-31)
5. Copier Documentation: https://copier.readthedocs.io/ (accessed 2026-01-31)
6. uv Documentation: https://docs.astral.sh/uv/ (accessed 2026-01-31)
7. ruff Documentation: https://docs.astral.sh/ruff/ (accessed 2026-01-31)
8. ty Documentation: https://docs.astral.sh/ty/ (accessed 2026-01-31)
9. Typer Documentation: https://typer.tiangolo.com/ (accessed 2026-01-31)
10. MkDocs Material: https://squidfunk.github.io/mkdocs-material/ (accessed 2026-01-31)

Related Tools