pyprojecttest

A Python project based on pyproject-template

Features

• Modern tooling: uv for deps, ruff for format/lint, mypy in strict mode
• CI/CD ready: GitHub Actions for checks, coverage upload, and releases
• Release automation: hatch-vcs + commitizen-driven tagging and changelog

Installation

pip install pyprojecttest

Quick Start

from pyprojecttest import greet

# Example usage
message = greet("Python")
print(message)  # Output: Hello, Python!

Documentation

📚 Full documentation is available in the docs/ directory

Build and view locally:

doit docs_serve  # Opens at http://127.0.0.1:8000

Key documentation files:

• Installation Guide - Setup instructions
• Usage Guide - Development workflows and commands
• API Reference - Complete API documentation
• Extensions Guide - Optional tools and extensions

Development Setup

Prerequisites

• Python 3.12+
• uv - Fast Python package installer
• direnv - Automatic environment variable loading (optional but recommended)

Quick Start

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone repository
git clone https://github.com/endavis/pyprojecttest.git
cd pyprojecttest

# Create virtual environment and install dependencies
uv sync --all-extras --dev

# Install pre-commit hooks
doit pre_commit_install

# Optional: Install direnv for automatic environment management
# macOS:
brew install direnv

# Linux (using doit helper):
doit install_direnv

# Hook direnv into your shell (one-time setup)
# Bash:
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

# Zsh:
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

# Allow direnv to load .envrc
direnv allow

# Optional: Create .envrc.local for personal overrides
cp .envrc.local.example .envrc.local

Versioning & Releases

This project uses automated versioning and releases powered by commitizen and hatch-vcs.

• Single Source of Truth: The Git tag is the definitive version. pyproject.toml and _version.py are generated at build time from tags (no manual edits).
• Versioning Scheme:
  • Production: Standard SemVer (e.g., v1.0.0).
  • Development: SemVer Pre-release (e.g., v1.0.0-alpha.1, v1.0.0-beta.0).

Creating a Release

Production Release (PyPI):

doit release

This automated task will:

1. Calculate the next version based on conventional commits.
2. Update CHANGELOG.md, merging any pre-release entries (commitizen --merge-prerelease).
3. Create a git tag (e.g., v1.0.0).
4. Push commits and tags to GitHub, triggering the release workflow.

Development/Pre-release (TestPyPI):

doit release_dev              # Defaults to alpha
doit release_dev --type beta  # Specify type (alpha, beta, rc)

This automated task will:

1. Bump the version to the next pre-release (e.g., v1.0.0-alpha.1).
2. Update CHANGELOG.md for the prerelease.
3. Create a prerelease git tag (e.g., v1.0.0-alpha.1).
4. Push to GitHub, triggering the testpypi workflow.

Environment Variables

This project uses direnv for automatic environment management. After setup:

• .envrc (committed) contains project defaults and is loaded automatically
• .envrc.local (git-ignored) is for personal overrides and credentials
• Environment variables are set automatically when you enter the project directory
• Virtual environment is activated automatically

Manual Setup (without direnv)

If you prefer not to use direnv:

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Set environment variables manually
export UV_CACHE_DIR="$(pwd)/tmp/.uv_cache"

# Install dependencies
uv sync --all-extras --dev

Available Tasks

View all available tasks:

doit list

Quick Commands

# Testing
doit test          # Run tests (parallel execution with pytest-xdist)
doit coverage      # Run tests with coverage report

# Code Quality
doit format        # Format code with ruff
doit lint          # Run linting
doit type_check    # Run type checking with mypy
doit check         # Run ALL checks (format, lint, type check, test)

# Security
doit security      # Run security scan with bandit
doit audit         # Run dependency vulnerability audit
doit spell_check   # Check for typos with codespell
doit licenses      # Check licenses of dependencies

# Code Formatting
doit fmt_pyproject # Format pyproject.toml with pyproject-fmt

# Version Management (Commitizen)
doit commit        # Interactive commit with conventional format
doit release       # Production release (commitizen-driven)
doit release_dev   # Pre-release/TestPyPI (commitizen-driven)

# Documentation
doit docs_serve    # Serve docs locally with live reload
doit docs_build    # Build documentation site
doit docs_deploy   # Deploy docs to GitHub Pages

# Maintenance
doit cleanup       # Clean build artifacts and caches
doit update_deps   # Update dependencies and run tests

See the Usage Guide for comprehensive documentation of all development workflows.

Running Tests

# Run all tests (parallel execution - fast!)
doit test

# Run with coverage
doit coverage

# View coverage report
open tmp/htmlcov/index.html

# Advanced: Run specific test directly
uv run pytest tests/test_example.py::test_version -v

Code Quality

This project includes comprehensive tooling:

Core Tools

• uv - Fast Python package installer and dependency manager
• ruff - Extremely fast Python linter and formatter
• mypy - Static type checker with strict mode
• pytest - Testing framework with parallel execution (pytest-xdist)

Quality & Security

• bandit - Security vulnerability scanner
• codespell - Spell checker for code and documentation
• pip-audit - Dependency vulnerability auditor
• pip-licenses - License compliance checker
• pre-commit - Git hooks for automated quality checks
• pyproject-fmt - Keep pyproject.toml formatted and organized
• commitizen - Enforce conventional commit message standards

Documentation

• MkDocs - Documentation site generator
• mkdocs-material - Material Design theme for MkDocs

Run all quality checks:

doit check

Pre-commit Hooks

Install hooks to run checks automatically before each commit:

doit pre_commit_install

Hooks include:

• Code formatting (ruff)
• Type checking (mypy)
• Security scanning (bandit)
• Spell checking (codespell)
• YAML/TOML validation
• Trailing whitespace removal
• Private key detection

AI Agent Support

This template is designed primarily for Claude Code, which is the only agent that ships the full slash-command workflow (plan → implement → finalize → close-issue). Gemini CLI is supported in a narrower role as a second-opinion planner/reviewer inside Claude-orchestrated dual-agent commands, and Codex CLI is supported as a standalone alternative without slash commands. Support for additional primary agents is planned.

Requirements

Important: GitHub CLI (gh) is required for AI-assisted workflows.

Many doit tasks use gh for issue creation, PR management, and repository operations. Install and authenticate before using AI agents:

# Install (macOS)
brew install gh

# Install (Linux) - see https://github.com/cli/cli/blob/trunk/docs/install_linux.md

# Authenticate
gh auth login

Features

• AGENTS.md - Instructions and protocols for AI agents
• Dangerous command blocking - Hooks prevent destructive operations (force push to main, branch deletion, etc.)
• Workflow automation - doit issue and doit pr for GitHub operations

See AI Agent Setup and AI Command Blocking for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and checks (doit check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See CHANGELOG.md for release history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Add acknowledgments here