Python Library Template

A Cookiecutter template for creating modern Python libraries with uv, ruff, mypy, and pytest.

Features

• Modern Python setup with Python 3.12+ support
• uv for fast dependency management
• Ruff for linting and formatting
• MyPy for type checking
• Pytest with coverage support
• bump-my-version for automated version management
• Invoke tasks for common operations
• Pre-configured development workflow
• Type hints support with py.typed marker
• CLAUDE.md guidance for Claude Code integration

Quick Start

1. Install cookiecutter:

   pipx install cookiecutter
   

2. Generate a new project:

   cruft create https://gitlab.com/roxautomation/templates/python-lib-template
   

   Or locally:

   cookiecutter /path/to/python-lib-template
   

3. The template will prompt for project details and automatically:

   • Initialize git repository
   • Set up uv environment
   • Run initial linting and formatting
   • Execute tests to verify setup

Template Variables

Variable	Description	Example
project_name	Human-readable project name	"My Python Library"
project_slug	Repository/directory name	"my-python-library"
package_name	Python package name	"my_python_library"
description	Short project description	"A modern Python library"
author_name	Author's full name	"Your Name"
author_email	Author's email	"your.email@example.com"
version	Initial version	"0.1.0"
python_version	Minimum Python version	"3.12"

Generated Project Structure

your-project/
├── CLAUDE.md                    # Claude Code guidance
├── README.md                    # Project documentation
├── pyproject.toml               # Project configuration
├── tasks.py                     # Invoke tasks
├── src/
│   └── your_package/
│       ├── __init__.py
│       ├── core.py
│       └── py.typed
├── tests/
│   └── test_your_package.py
└── examples/
    └── basic_usage.py

Development Workflow

The generated project includes these common tasks:

Setup

uv sync

Code Quality

uv run ruff check --fix    # Linting
uv run ruff format         # Formatting
uv run mypy .              # Type checking
uv run invoke lint         # All quality checks

Testing

uv run pytest                    # Run tests
uv run invoke test               # Run tests with coverage

Version Management

uv run bump-my-version bump patch    # 0.1.0 → 0.1.1
uv run bump-my-version bump minor    # 0.1.0 → 0.2.0
uv run bump-my-version bump major    # 0.1.0 → 1.0.0

Template Development

To modify this template:

1. Edit files in {{cookiecutter.project_slug}}/
2. Update variables in cookiecutter.json
3. Modify the post-generation hook in hooks/post_gen_project.py
4. Test changes:

   cookiecutter . --output-dir /tmp
   

Requirements

• Python 3.12+
• uv (automatically installed during generation)
• git (for version control)

License

MIT License - see LICENSE file for details.