python-repo-template

Modern Python project template with Poetry, Makefile workflows, automated testing, linting, and GitHub Actions CI/CD.

All notable changes to this project will be documented in CHANGELOG.

Supports Python 3.12, 3.13

✨ What’s Included

🔧 Development Tools

• Poetry - Modern dependency management
• Makefile - Convenient command shortcuts for common tasks
• pytest - Testing framework with coverage reporting
• black - Code formatting
• flake8 - Python code linting
• yamllint - YAML file linting

🔐 Security & Code Quality

• CodeQL - Automated security analysis (workflow)
• Secrets Scan - Gitleaks and TruffleHog for detecting hardcoded secrets (workflow)
• Snyk - Vulnerability scanning (workflow)
• Dependabot - Automated dependency updates (config)

🚀 CI/CD

• GitHub Actions - Automated testing and deployment
• Codecov - Code coverage reporting
• Stale Issue Management - Automatically closes inactive issues

🚀 Getting Started

1. Create Repository from Template

Click “Use this template” on GitHub or:

mkdir new_repo_name
cd new_repo_name
git init
git pull https://github.com/kyhau/python-repo-template

2. Customize Your Project

Update these files:

• pyproject.toml - Package name, version, dependencies
• Makefile - Set PACKAGE_NAME and TEST_PATH variables
• README.md - Replace with your project description
• app/ - Rename to your package name

3. Set Up Development Environment

Quick setup (recommended for first-time setup):

make setup-init

Manual setup (if you prefer step-by-step):

make setup-venv    # Configure Poetry to use local virtualenv
make install-all   # Install all dependencies

📋 Development Workflow

Common Commands

make setup-init         # First-time setup (configure, lock, install everything)
make help               # Show all available commands
make install-all        # Install all dependencies (main, dev, test)
make test               # Run tests without coverage
make test-with-coverage # Run tests with coverage
make format-python      # Auto-format Python code
make lint-python        # Lint Python code
make lint-yaml          # Lint YAML files
make pre-commit         # Run all quality checks (format, lint, test)
make build              # Build the package
make clean              # Clean build artifacts

Running Tests

# Run tests with coverage
make test-with-coverage

# Run tests only
make test

# Format and lint code
make format-python
make lint-python
make lint-yaml

Managing Dependencies

# Update dependencies to latest compatible versions
make update-deps

# Regenerate lock file
make lock

🏗️ Project Structure

python-repo-template/
├── .github/
│   ├── workflows/        # CI/CD workflows
│   └── dependabot.yml    # Dependency updates config
├── app/                  # Your Python package
│   ├── __init__.py
│   └── main.py
├── tests/                # Unit tests
│   └── test_main.py
├── pyproject.toml        # Project metadata and dependencies
├── Makefile              # Build and test commands
└── README.md             # This file

📦 Building and Releasing

# Build the package
make build

# The built package will be in dist/
ls dist/

This site is open source. Improve this page.