Python Project Template

🚀 A comprehensive Python project template designed to help developers quickly bootstrap new projects with complete CI/CD pipelines, modern tooling, and best practices.

The template includes everything needed to start a professional Python project without spending time on infrastructure setup.

Other Languages: English | 中文

Why Use This Template?

This template eliminates the time-consuming setup of project infrastructure, allowing you to focus on building your application. It provides:

• Zero-configuration CI/CD: Complete GitHub Actions workflows out of the box
• Modern Python tooling: Latest best practices with uv, ruff, and pytest
• Professional development environment: VS Code Dev Container with optimized terminal setup
• Comprehensive documentation: Auto-generated docs with MkDocs Material
• Quality assurance: Pre-commit hooks, testing, and coverage reporting

🎯 Key Features

Modern Development Stack

• Python 3.10, 3.11, 3.12 support with uv dependency management
• Ruff for ultra-fast linting and formatting
• pytest with coverage reporting and parallel execution
• Pre-commit hooks for automated code quality checks

Complete CI/CD Pipeline

• Automated testing across multiple Python versions
• Code quality gates with ruff validation
• GitHub Pages deployment for documentation
• Release automation with semantic versioning
• Auto-labeling for pull requests

Production-Ready Infrastructure

• Docker support with multi-stage builds
• VS Code Dev Container with zsh, oh-my-zsh, and powerlevel10k
• MkDocs documentation with Material theme
• Makefile commands for common development tasks

Intelligent Automation

• Project initialization script (scripts/initpyrepo.go) for personalized setup
• Documentation generation (scripts/gen_docs.py) from code and notebooks
• Auto-generated API docs from Python code
• Blog functionality for project updates

🚀 Getting Started

Quick Setup Options

GitHub TemplateInitialization ScriptManual SetupQuick Customization

1. Click Use this template
2. Configure your new repository
3. Clone and start developing

# Clone the template
git clone https://github.com/Mai0313/mcp_agents.git
cd mcp_agents

# Run the initialization script
go run scripts/initpyrepo.go

# Follow the prompts to customize your project

# Clone the repository
git clone https://github.com/Mai0313/mcp_agents.git
cd mcp_agents

# Install uv if not already installed
make uv-install

# Install dependencies
uv sync

# Set up pre-commit hooks
make format

# Clone the repository
git clone https://github.com/Mai0313/mcp_agents.git
cd mcp_agents

# Replace with your project name (snake_case)
find . -type f -name "*.py" -o -name "*.md" -o -name "*.toml" | xargs sed -i 's/mcp_agents/your_project_name/g'

# Replace with your project title (PascalCase)
find . -type f -name "*.py" -o -name "*.md" -o -name "*.toml" | xargs sed -i 's/MCPAgents/YourProjectTitle/g'

# Install and setup
make uv-install && uv sync && make format

Development Workflow

# Run tests
make test

# Format code
make format

# Generate documentation
make gen-docs

# Clean artifacts
make clean

📁 Project Structure

The template follows Python packaging best practices with a clean, organized structure:

├── .devcontainer/          # VS Code Dev Container setup
│   ├── Dockerfile         # Development environment
│   └── devcontainer.json  # VS Code configuration
├── .github/
│   ├── workflows/         # CI/CD pipelines
│   │   ├── test.yml      # Multi-version testing
│   │   ├── code-quality-check.yml
│   │   ├── deploy.yml    # Documentation deployment
│   │   └── release_drafter.yml
│   └── copilot-instructions.md
├── docker/
│   ├── Dockerfile        # Production container
│   └── docker-compose.yaml
├── docs/                 # MkDocs documentation
│   ├── index.md
│   ├── installation/
│   └── blog/
├── scripts/              # Automation tools
│   ├── initpyrepo.go    # Project initialization
│   └── gen_docs.py      # Documentation generation
├── src/
│   └── mcp_agents/   # Main package
├── tests/               # Test suite
├── pyproject.toml       # Project configuration
├── .pre-commit-config.yaml
├── Makefile            # Development commands
└── README.md

🔧 Configuration Files

The template includes comprehensive configuration for:

• pyproject.toml: Project metadata, dependencies, and tool configurations
• .pre-commit-config.yaml: Code quality hooks with ruff
• pytest configuration: Testing, coverage, and reporting setup
• mkdocs.yml: Documentation generation and deployment
• Docker configurations: Development and production containers

🎨 Customization

Project Name Customization

This template is designed for quick customization through simple global replacements:

1. Replace package name: Change all instances of mcp_agents to your project name (recommended: snake_case)
2. Replace project title: Change all instances of MCPAgents to your project title (recommended: PascalCase)
3. Update metadata: Modify author, description, and other details in pyproject.toml

Example commands:

# If your project is called "awesome_project"
find . -type f -name "*.py" -o -name "*.md" -o -name "*.toml" | xargs sed -i 's/mcp_agents/awesome_project/g'
find . -type f -name "*.py" -o -name "*.md" -o -name "*.toml" | xargs sed -i 's/MCPAgents/AwesomeProject/g'

Dependency Management

# Add production dependencies
uv add requests pydantic

# Add development dependencies
uv add pytest black --dev

# Update all dependencies
uv sync

Documentation

The template uses MkDocs with Material theme and supports:

• Auto-generated API docs from Python docstrings
• Jupyter notebook integration with automatic conversion
• Blog functionality for project updates
• Custom themes and styling

CI/CD Customization

All workflows are modular and can be customized:

• Testing matrix: Modify Python versions in .github/workflows/test.yml
• Code quality: Adjust ruff rules in pyproject.toml
• Documentation: Configure MkDocs deployment in .github/workflows/deploy.yml
• Release process: Customize release drafting and versioning

🏢 Enterprise Features

Security & Compliance

• Dependency scanning with automated updates
• Security linting with bandit integration
• License compliance tracking
• Secrets management best practices

Team Development

• Standardized development environment with Dev Containers
• Code review automation with quality gates
• Consistent coding standards enforced by pre-commit hooks
• Documentation requirements for all public APIs

🌟 Success Stories

This template has been used to bootstrap:

• Machine Learning projects with GPU support
• Web APIs with FastAPI and async support
• Data processing pipelines with scientific computing stack
• CLI tools with modern Python packaging

📚 Learn More

• Installation Guide - Detailed setup instructions
• Development Workflow - Best practices for development
• CI/CD Configuration - Understanding the automation
• Customization Guide - Adapting for your needs

🤝 Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports and fixes
• ✨ Feature requests and implementations
• 📝 Documentation improvements
• 🎨 Template enhancements

See our Contributing Guide for details.

👥 Contributors

Made with contrib.rocks

---

Ready to start your next Python project? Use this template and focus on building amazing applications! 🚀