template_python_project

A minimal, secure, and modern Python project template with a basic Hello World app, containerization support, and robust development tooling.

Development Philosophy

This template was collaboratively developed through "vibe coding" - an iterative, conversation-driven approach using AI assistance where the project evolved organically based on real needs and best practices. Rather than following a rigid specification, we built this template through continuous refinement, testing, and improvement in an interactive dialogue, ensuring it provides genuine value for Python developers starting new projects.

Features

• Python 3.13+ compatible
• Minimal Hello World application
• Containerization with Docker
• Comprehensive code quality standards - PEP8 and PEP440 compliance with automated enforcement
• Pre-commit hooks and code style enforcement (Black, Ruff, Mypy)
• Bootstrap scripts for easy setup (Linux/macOS and Windows)
• Security best practices (see below)
• Well-documented and easy to use

Security Best Practices

• Uses virtual environments for dependency isolation
• No secrets or sensitive data in code or config
• .gitignore excludes common sensitive files and folders
• Container runs as non-root by default (see Dockerfile for customization)
• Dependencies managed via pyproject.toml for reproducibility
• Pre-commit hooks help catch common mistakes before code is committed
• Automated SBOM (Software Bill of Materials) generation for supply chain security
• Vulnerability scanning with Trivy in CI/CD pipeline

Getting Started

💻 Local Development Setup

Quick Start

1. Clone the repository:

   git clone https://github.com/engineeringclouds/template_python_project.git
   cd template_python_project

2. Bootstrap your environment:

   Linux/macOS:

   ./scripts/bootstrap.sh

   Windows (PowerShell):

   .\scripts\bootstrap.ps1

3. Run the application:

   python -m template_python_project

🐳 Container Setup

Pre-built Images

Use the pre-built container images published to GitHub Container Registry:

# Pull and run the latest image
docker pull ghcr.io/engineeringclouds/template_python_project:latest
docker run --rm ghcr.io/engineeringclouds/template_python_project:latest

# Or pull a specific release version
docker pull ghcr.io/engineeringclouds/template_python_project:v1.0.0
docker run --rm ghcr.io/engineeringclouds/template_python_project:v1.0.0

📦 View all available images: ghcr.io/engineeringclouds/template_python_project

Docker Quick Start (Build from Source)

1. Build the image:

   docker build -t template-python-project .

2. Run the container:

   docker run --rm template-python-project

🧪 Testing

Run Tests

pytest

Run with Coverage

pytest --cov --cov-report=html

Example Output

When you run the application, you should see:

$ python -m template_python_project
Hello, world!

📚 Usage Examples

🚀 Creating a New Project from This Template

Method 1: GitHub Template (Recommended)

1. Click Use this template
2. Choose a repository name (e.g., my-awesome-project)
3. Clone your new repository:

   git clone https://github.com/yourusername/my-awesome-project.git
   cd my-awesome-project

Method 2: Manual Setup

# Download and extract template
curl -L https://github.com/engineeringclouds/template_python_project/archive/main.zip -o template.zip
unzip template.zip
mv template_python_project-main my-awesome-project
cd my-awesome-project

# Initialize as new git repository
rm -rf .git
git init
git add .
git commit -m "Initial commit from template"

🔧 Customizing the Template

Rename the Package

1. Update directory structure:

   mv src/template_python_project src/my_package_name

2. Update pyproject.toml:

   [project]
   name = "my-package-name"
   # ... other settings

3. Update imports and references:

   # In src/my_package_name/__main__.py
   from my_package_name.main import main

Add Your Own Functionality

# src/my_package_name/main.py
def hello(name: str = "world") -> str:
    """Generate a personalized greeting."""
    return f"Hello, {name}!"

def main():
    import sys
    name = sys.argv[1] if len(sys.argv) > 1 else "world"
    print(hello(name))

🔄 Development Workflow Examples

Daily Development

# Activate environment
source .venv/bin/activate  # or .\.venv\Scripts\Activate.ps1 on Windows

# Make changes to your code
# ...

# Run quality checks
pre-commit run --all-files

# Run tests with coverage
pytest --cov

# Build and test container
docker build -t my-project .
docker run --rm my-project

Release Workflow

# Make changes using conventional commits
git commit -m "feat: add user authentication system"
git commit -m "fix: resolve memory leak in data processing"
git commit -m "docs: update installation instructions"

# Push to main branch (triggers automatic release)
git push origin main

Manual Release

Use GitHub Actions workflow dispatch with options:

• Force version bump: patch, minor, major, prerelease
• Create prerelease: For testing unreleased features
• Dry run: Test release process without creating actual release

🧪 Testing Examples

Basic Testing

# tests/test_my_feature.py
import pytest
from my_package_name import my_function

def test_my_function():
    """Test basic functionality."""
    result = my_function("input")
    assert result == "expected_output"

def test_my_function_edge_case():
    """Test edge case handling."""
    with pytest.raises(ValueError):
        my_function(None)

Running Different Test Scenarios

# Run all tests
pytest

# Run specific test file
pytest tests/test_my_feature.py

# Run with coverage report
pytest --cov --cov-report=html

# Run performance tests only
pytest -m performance

# Run tests in parallel
pytest -n auto

🐳 Container Usage Examples

Using Pre-built Images

# Run latest version
docker run --rm ghcr.io/engineeringclouds/template_python_project:latest

# Run specific release version
docker run --rm ghcr.io/engineeringclouds/template_python_project:v1.0.0

# Run with environment variables
docker run --rm -e MY_CONFIG_VAR=value ghcr.io/engineeringclouds/template_python_project:latest

# Run with specific port mapping
docker run --rm -p 8080:8080 ghcr.io/engineeringclouds/template_python_project:latest

Development Container

# Build development image with test dependencies
docker build -f Dockerfile.dev -t my-project-dev .

# Run container with volume mounting for live development
docker run -v $(pwd):/app -it my-project-dev bash

Production Container

# Build optimized production image
docker build -t my-project:latest .

# Run with environment variables
docker run -e MY_CONFIG_VAR=value my-project:latest

# Run with specific port mapping
docker run -p 8080:8080 my-project:latest

Multi-stage Build Example

# Add to your Dockerfile for optimized builds
FROM python:3.13-slim as builder
WORKDIR /build
COPY pyproject.toml .
RUN pip install build && python -m build

FROM python:3.13-slim as runtime
COPY --from=builder /build/dist/*.whl .
RUN pip install *.whl
CMD ["python", "-m", "my_package_name"]

GitHub Repository Configuration

This template includes automated GitHub repository configuration to set up optimal open source project settings.

Automated Setup

Run the configuration script to automatically configure your repository:

# Make the script executable
chmod +x scripts/configure-github-repo.sh

# Configure your repository
./scripts/configure-github-repo.sh

# Or configure a different repository
./scripts/configure-github-repo.sh your-username/your-repo

What Gets Configured

• Repository Settings: Description, topics, discussions, wiki, template status
• Labels: Comprehensive label system for issues and PRs
• Branch Protection: Protects main branch with required status checks
• Community Health: Verifies presence of all community health files

Prerequisites

1. Install GitHub CLI: brew install gh (macOS) or see installation guide
2. Authenticate: gh auth login

For detailed information, see:

• GitHub Configuration Guide
• GitHub CLI Reference
• Supply Chain Security & SBOM Guide

Troubleshooting

🐛 Common Issues

Test Import Errors

Problem: ModuleNotFoundError when running tests Solution: Ensure pytest configuration is correct:

# Method 1: Use pytest with proper path
PYTHONPATH=src pytest

# Method 2: Check pyproject.toml has:
# [tool.pytest.ini_options]
# pythonpath = ["src"]

Virtual Environment Issues

Problem: Bootstrap scripts fail or Python not found Solutions:

# Check Python version
python --version  # Should be 3.13+

# Manual environment setup
python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows:
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -e ".[dev]"

Container Build Failures

Problem: Docker build fails or image won't run Solutions:

# Check Docker is running
docker --version

# Clean build (no cache)
docker build --no-cache -t template-python-project .

# Debug build process
docker build -t template-python-project . --progress=plain

# Check logs
docker logs <container-id>

GitHub Actions Failures

Problem: CI/CD workflows fail Common causes:

• Missing secrets or environment variables
• Workflow file syntax errors
• Permission issues with GITHUB_TOKEN
• Dependency conflicts

Debug steps:

1. Check workflow logs in GitHub Actions tab
2. Verify all required secrets are configured
3. Test workflow locally with act (if available)
4. Compare with working template version

Security Note

For production use, remember to:

• Remove placeholder files like .venv/.gitkeep
• Update URLs in pyproject.toml to match your project
• Review and update the security practices for your specific use case
• Consider using pip-audit to check for known security vulnerabilities:

  pip install pip-audit
  pip-audit

CI/CD Pipeline

This project uses GitHub Actions with a robust, optimized CI/CD pipeline designed for reliability and maintainability.

📖 Detailed Architecture: See Workflow Architecture Documentation for comprehensive implementation details.

Workflow Dependencies

📱 View Workflow Diagram

graph TD
    A[Pull Request] --> B[PR Validation Workflow]
    B --> C[CI Matrix Jobs]
    C --> D[Container Build & Test]
    D --> E[Security Scan]
    E --> F[PR Ready for Merge]

    G[Push to main] --> H[CI Workflow]
    H --> I[Container Publishing]
    G --> J[Release Workflow]

    style B fill:#e1f5fe
    style H fill:#f3e5f5
    style I fill:#fff3e0
    style J fill:#e8f5e8

Loading

Pull Request Validation:

1. PR Validation Workflow (pr-validation.yml) - Comprehensive validation using needs keyword

   • CI Matrix: Cross-platform testing (Ubuntu, Windows, macOS)
     • Linting with Ruff
     • Code formatting check with Black
     • Type checking with MyPy
     • Testing with pytest
   • Container Job: Docker build and testing (depends on CI success)
   • Security Scan: Trivy vulnerability scanning (depends on container success)

Main Branch Automation:

2. CI Workflow (ci.yml) - Post-merge validation

   • Runs comprehensive testing after merge to main

3. Container Publishing (container.yml) - Production image builds

   • Dependency: Triggered by successful CI workflow completion
   • Builds and publishes container images to registry

4. Release Workflow (release.yml) - Automated semantic versioning

   • Trigger: Pushes to main branch or manual dispatch
   • Analyzes conventional commits for version bumps
   • Generates changelogs and creates GitHub releases
   • Validates template functionality

Key Benefits

• Reliable Dependencies: Uses GitHub's native needs keyword instead of complex cross-workflow polling
• Fast Feedback: Parallel job execution with proper dependency ordering
• Branch Protection: Required status checks prevent merge until all validations pass
• Clear Separation: Distinct workflows for PR validation vs. production automation

This ensures that only validated, tested code gets containerized and released, following the fail-fast principle and optimizing resource usage.

Automated Template Releases

The project uses semantic versioning with conventional commits to manage template releases:

• feat: → Minor version bump (0.1.0 → 0.2.0) - New template features
• fix: → Patch version bump (0.1.0 → 0.1.1) - Template fixes
• feat!: or BREAKING CHANGE: → Major version bump (0.1.0 → 1.0.0) - Breaking changes

Each release validates that the template produces working Python projects and provides clear upgrade paths for existing users.

See Release Workflow Guide for detailed information.

Documentation

• See Code Quality Standards Guide for PEP8/PEP440 compliance and automation
• See CONTRIBUTING.md for contribution guidelines
• See Release Workflow Guide for automated release information
• See Usage Examples for detailed implementation examples
• See GitHub Configuration Guide for repository setup
• See GitHub CLI Reference for CLI automation
• See CHANGELOG.md for release history
• See LICENSE for license details

Project URLs

• Homepage
• Documentation
• Source
• Tracker

Contributing

We welcome contributions! This project embodies a collaborative "vibe coding" philosophy - we believe the best solutions emerge through iterative conversation and real-world testing, whether that's human-to-human or human-to-AI collaboration. Whether you're suggesting improvements, fixing bugs, or adding features, we value the collaborative process of building something useful together.

Please see CONTRIBUTING.md for guidelines.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

This project is licensed under the MIT License.