Python Library Template

Python library template with security scanning, automated publishing, and optional AWS integration.

📊 Live Dashboards

📖 Documentation	🧪 Test Results	📊 Coverage	🔒 Security	⚖️ Compliance

---

⚡ What You Get

Zero-Config CI/CD Pipeline

• Matrix testing with HTML reports
• Automated security scanning (Bandit, Safety, pip-audit, Semgrep)
• License compatibility checking and compliance reports
• Semantic versioning with automated changelog generation

Enterprise-Grade Quality

• Pre-commit hooks (Ruff, Black, conventional commits)
• Test-driven development setup with Click CLI testing
• Code coverage reporting with beautiful HTML dashboards
• API documentation auto-generated and deployed to GitHub Pages

Modern Python Stack

• Poetry dependency management with security/compliance groups
• Trusted publishing to PyPI/TestPyPI (no API keys needed)
• Optional AWS SAM integration with ephemeral test environments
• Windows/Git Bash compatibility with comprehensive guidance

🚀 Quick Start

1. Get the Template

# Use as GitHub template or clone
gh repo create my-awesome-lib --template svange/augint-api --public
cd my-awesome-lib

2. Quick Setup

# Run the two-stage bootstrap
python bootstrap-stage1.py     # Template customization
python bootstrap-stage2.py     # AWS integration (after manual SAM setup)

What this does:

• Customizes template with your project name
• Sets up AWS pipeline infrastructure
• Configures GitHub Actions OIDC authentication
• Creates comprehensive development environment

📋 For detailed setup instructions, see BOOTSTRAP.md

3. Secure Your Secrets

# Add GitHub token to .env, then
chezmoi add .env
chezmoi git add . && chezmoi git commit -m "Add project secrets"

4. Go Live

poetry install && pre-commit install
git add . && git commit -m "feat: initial project setup"
git push

That's it! Your CI/CD pipeline is now running with full security scanning and automated publishing.

📋 Prerequisites

Required Tools:

• Python 3.9+ and Poetry
• Git and GitHub CLI (optional)
• For AWS features: AWS CLI and SAM CLI
• For secret management: chezmoi and age

PyPI Setup (Important - Do This First!):

1. Reserve your package name on PyPI and TestPyPI
2. Set up Trusted Publishing:
   • Publisher: GitHub Actions
   • Repository: your-account/your-repo
   • Workflow: pipeline.yaml
   • Environment: pypi

Windows Users:

# Install tools
winget install Python.Python.3.11
winget install twpayne.chezmoi
winget install --id FiloSottile.age

# Set environment for Claude Code
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

AWS Setup (Optional - One Time Per Account):

# Enable GitHub Actions OIDC
aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

🏗️ Project Setup

This template uses a two-stage bootstrap process that eliminates common setup friction:

Stage	Purpose	When to Run
Stage 1	Template customization	Immediately after cloning
Stage 2	AWS integration	After sam pipeline bootstrap

Why two stages? This approach prevents dependency conflicts and handles the interactive SAM setup gracefully.

See BOOTSTRAP.md for complete setup instructions (delete after setup).

📚 Documentation Best Practices

API Documentation (Google-style docstrings):

def process_data(data: list[str], format: str = "json") -> dict:
    """Process input data and return formatted results.

    Args:
        data: List of strings to process.
        format: Output format ("json" or "xml").

    Returns:
        Processed data in specified format.

    Example:
        >>> process_data(["item1", "item2"])
        {"processed": ["item1", "item2"]}
    """

Library vs CLI Design:

• Use __all__ to control public API surface
• Keep CLI commands in separate modules
• Document both library and CLI usage in module docstrings

🛠️ Development Workflow

# Daily development
poetry run pytest              # Run fast tests
poetry run pytest -m slow      # Run AWS integration tests  
poetry run ruff check --fix     # Lint and fix
poetry run black .              # Format code

# Security and compliance (CI runs these automatically)
poetry install --with security,compliance
poetry run bandit -r src/
poetry run safety check
poetry run pip-licenses

# Documentation
poetry run pdoc src/your_module  # Generate docs locally

💡 Pro Tips

• Branch Protection: See .github/BRANCH_PROTECTION.md for recommended settings
• Dependabot: Auto-merge is configured for safe updates (patch/minor)
• Security Scans: Only run on main/dev branches to keep feature branches fast
• Windows Users: All commands work in Git Bash, PowerShell, and CMD
• Claude Code: Generate CLAUDE.md during bootstrap for AI-assisted development