Repository files navigation

• Modern Python: Python 3.11-3.13 support with type hints
• Fast Package Management: Usesuv for blazing-fast dependency management
• Flexible Configuration: 20+ customization options via Copier
• Production Ready: Docker, CI/CD, documentation out of the box

• Code Formatting: Black + isort for consistent style
• Linting: Ruff + mypy + Pylint for code quality
• Testing: pytest with coverage enforcement (80%+ default)
• Security: Bandit for security vulnerability scanning
• Pre-commit Hooks: 12+ automated checks before commits
• Single Source of Truth: All configuration inpyproject.toml

• Session Management: Track AI coding sessions with context
• Multi-AI Support: Works with Claude Code, Cursor, GitHub Copilot, Google Gemini, and Aider
• TDD Workflow: Integrated Test-Driven Development guidelines
• Comprehensive Guides: 5 detailed AI documentation files
• Project Context: Automatic context preservation across sessions

• Multi-stage Dockerfile: Optimized production builds
• Docker Compose: Full service orchestration
• MkDocs Material: Beautiful documentation sites
• Auto-generated API Docs: Using mkdocstrings
• GitHub Pages Ready: Deploy docs with one command

• Python 3.11 or higher
• uv (recommended) or pip
• Copier 9.0.0 or higher

# Install Copier (choose one)pip install copier# oruv tool install copier

copier copy gh:Atyantik/python-modern-template my-awesome-projectcd my-awesome-project

Smart Defaults: The folder name is automatically used as the default forproject_name andproject_slug:

• my-awesome-project → Project: "My Awesome Project", Package:my_awesome_project
• data_processor → Project: "Data Processor", Package:data_processor
• backend-api-v2 → Project: "Backend Api V2", Package:backend_api_v2

You can still override these defaults during the interactive prompts.

copier copy --defaults gh:Atyantik/python-modern-template my-project

copier copy \  --data project_name="My Awesome Project" \  --data include_quality_scripts=true \  --data include_ai_tools=true \  --data include_docker=true \  gh:Atyantik/python-modern-template my-project

We provide 7 ready-to-use example configurations:

Seeexamples/README.md for detailed guides and commands.

Note: Example projects are generated locally on-demand usingexamples/generate-all.sh and are not tracked in git. This keeps the repository lightweight while providing fresh examples from the latest template.

• project_name: Human-readable project name (defaults to folder name, title-cased)
• project_slug: Repository/slug name (defaults to folder name)
• package_name: Python package name (derived from slug with underscores)
• project_description: Short description
• author_name: Your name
• author_email: Your email
• license: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, or Proprietary

• python_version: 3.11, 3.12, or 3.13
• min_python_version: Minimum required version
• line_length: 79, 88, 100, or 120

• include_quality_scripts: Quality enforcement scripts (default: true)
• include_ai_tools: AI session management (default: true)
• include_docker: Docker support (default: false)
• include_docs: MkDocs documentation (default: false)
• include_pre_commit: Pre-commit hooks (default: true)
• include_cli: CLI framework (default: false)

• min_coverage: Minimum test coverage % (default: 80)

• all: All AI tools (Claude, Cursor, Copilot, Gemini, Aider)
• minimal: Just AGENTS.md (universal)
• claude: Claude Code only
• cursor: Cursor IDE only
• custom: Pick individually

my-project/├── src/│   └── my_project/          # Your Python package├── tests/                   # Test files├── scripts/│   ├── quality/            # Quality check scripts (optional)│   └── ai_tools/           # AI session tools (optional)├── docs/                   # Documentation (optional)├── AI_DOCS/                # AI guides (optional)├── .github/│   └── workflows/          # CI/CD pipelines├── pyproject.toml          # Project configuration├── Makefile                # Common tasks├── Dockerfile              # Docker config (optional)├── docker-compose.yml      # Service orchestration (optional)├── mkdocs.yml              # Docs config (optional)└── README.md               # Project documentation

# Install dependenciesuv sync --all-extras --dev# Run testsmaketest# Run all quality checksmake check# Format codemake format# Run lintersmake lint# View coverage reportmake coverage# Serve documentation (if enabled)make docs-serve

# Start a new coding sessionmake ai-start TASK="Add user authentication"# Log progressuv run ai-log"Implemented login endpoint"# Update planuv run ai-update-plan"Complete login tests"# Get context summarymake ai-context# Finish sessionmake ai-finish

# Build imagemake docker-build# Run containermake docker-run# Start servicesmake docker-compose-up# Stop servicesmake docker-compose-down

This template is optimized for AI-powered development! Each AI assistant automatically reads its configuration file.

When you open your project with an AI assistant, it automatically understands:

• ✅Test-Driven Development - Write tests before code
• ✅Quality Standards - Type hints, docstrings, 80%+ coverage
• ✅Project Structure - Where to put files
• ✅Make Commands -make test,make check, etc.
• ✅Session Tracking - Track progress across sessions (if AI tools enabled)

1. Create your project:

   copier copy gh:Atyantik/python-modern-template my-projectcd my-project

2. Open in Claude Code:

   • Claude automatically readsCLAUDE.md
   • It knows to write tests first, follow TDD

3. Start coding with AI:

   make ai-start TASK="Add user authentication"

4. Let AI help you code:

   • Ask: "Create a User class with email and password"
   • Claude will write tests first, then implementation
   • It will runmake test to verify

5. Run quality checks:

   make check

6. Finish the session:

   make ai-finish

1. Create and open project:

   copier copy gh:Atyantik/python-modern-template my-projectcursor my-project# or open in Cursor IDE

2. Cursor loads.cursorrules automatically

3. Start with Cmd+K or Cmd+L:

   • Ask: "Add a function to validate email addresses"
   • Cursor follows TDD: writes tests first
   • It knows project conventions

4. Test your changes:

   maketestmake check

1. Create project and open in VS Code:

   copier copy gh:Atyantik/python-modern-template my-projectcode my-project

2. Copilot reads.github/copilot-instructions.md

3. Start coding:

   • As you type, Copilot suggests code following project standards
   • Suggestions include type hints and docstrings
   • Test files suggested when creating new modules

4. Verify with quality checks:

   make check

If terms like "TDD" or "make commands" are unfamiliar:

Read the Complete Beginner's Guide - Step-by-step explanations of everything!

• Getting Started Guide: Complete beginner's guide (START HERE!)
• Examples Guide: 7 example configurations with full commands
• Project Summary: Implementation details and statistics
• AI Tools Guide: AI session management (if enabled)
• TDD Workflow: Test-Driven Development guide (if enabled)
• Code Conventions: Style and best practices (if enabled)

• Template Development Guide: Working on this template repository

• ✅ Quality enforcement built-in
• ✅ AI coding assistant integration
• ✅ TDD workflow for better code
• ✅ Production-ready from day one

• ✅ Consistent project structure
• ✅ Automated quality checks
• ✅ Comprehensive documentation
• ✅ CI/CD pipelines included

• ✅ Best practices enforced
• ✅ Modern Python patterns
• ✅ Type hints everywhere
• ✅ Well-documented examples

cd my-projectcopier update

Want to see the example projects in action? Generate all 7 configurations locally:

cd examples./generate-all.sh

This creates:

• 01-minimal-package/ - Basic structure (25 files)
• 02-cli-tool/ - CLI with Typer (25 files)
• 03-library/ - Library with 90% coverage (23 files)
• 04-data-science/ - Data science with Docker (45 files)
• 05-web-api/ - Web API with Docker (50 files)
• 06-ai-assisted/ - AI tools enabled (40 files)
• 07-full-featured/ - Everything enabled (68 files)

Each example is a fully working project you can explore and test.

1. Fork this repository
2. Modify files intemplate/ directory
3. Updatecopier.yml configuration
4. Test withcopier copy . test-project

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Copyright © 2025Atyantik Technologies Private Limited

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

• Built withCopier
• Powered byuv
• Quality tools:Black,Ruff,mypy,Pylint
• Testing:pytest
• Documentation:MkDocs Material
• Inspired by modern Python best practices

• Website:www.atyantik.com
• Email:contact@atyantik.com
• Issues:GitHub Issues