Irving's Python Project Cookiecutter Template

A python project template to simplify project setup. Adapted from https://github.com/fmind/cookiecutter-mlops-package

The template provides a robust foundation for building, testing, packaging, and deploying Python packages and Docker Images. Adapt it to your project's needs; the source material is MLOps-focused but is suitable for a wide array of Python projects.

Original resources:

• MLOps Coding Course (Learning): Learn how to create, develop, and maintain a state-of-the-art MLOps code base.
• MLOps Python Package (Example): Kickstart your MLOps initiative with a flexible, robust, and productive Python package.

Philosophy

This Cookiecutter is designed to be a common ground for diverse python environments. Whether you're working with Kubernetes, Vertex AI, Databricks, Azure ML, or AWS SageMaker, the core principles of using Python packages and Docker images remain consistent.

This template equips you with the essentials for creating, testing, and packaging your code, providing a solid base for integration into your chosen platform.

You have the freedom to structure your src/ and tests/ directories according to your preferences. Alternatively, you can draw inspiration from the structure used in the MLOps Python Package project for a ready-made implementation.

Quick Start

1. Generate your project:

# With uv:
uv tool install cookiecutter
# With pip:
# pip install cookiecutter
cookiecutter gh:irod973/python-project-template

You'll be prompted for the following variables.

• user: Your GitHub username.
• name: The name of your project.
• repository: The name of your GitHub repository.
• package: The name of your Python package.
• license: The license for your project (Note: use "NA" until we define a standard licence or omit entirely)
• version: The initial version of your project.
• description: A brief description of your project.
• python_version: The Python version to use (e.g., 3.12).
• include_fastapi: Whether to include a sample FastAPI application.
• include_metaflow: Whether to include a sample Metaflow application.
• include_torchvision: Whether to include a sample Torchvision application.
• include_package: Whether to include a sample application for publishing a Python package.

2. Initialize a git repository:

cd {{ cookiecutter.repository }}
git init
# Create remote repo
gh repo create
# Then make first push:
git checkout -b feature/initial-setup
git add .
git commit -m "Initial commit"
git push -u origin feature/initial-setup

3. Explore the generated project:

• src/{{cookiecutter.package}}: Your Python package source code.
• tests/: Unit tests for your package.
• tasks/: just commands for automation.
• docker/Dockerfile.python: Configuration for building your Docker image.
• docker-compose.yml: Orchestration file for running your project.

4. Start developing!

Use the provided just commands to manage your development workflow:

• uv run just check: Run code quality, type, security, and test checks.
• uv run just clean: Clean up generated files.
• uv run just commit: Commit changes to your repository.
• uv run just doc: Generate API documentation.
• uv run just docker: Build and run your Docker image.
• uv run just format: Format your code with Ruff.
• uv run just install: Install dependencies, pre-commit hooks, and GitHub rulesets.
• uv run just package: Build your Python package.
• uv run just project: Run the project in the CLI.

Applications

This template includes a few optional application skeletons. See the nested README for details.

Key Features

This section was copied into the created project's README so tool info is available.

• Streamlined Project Structure: A well-defined directory layout for source code, tests, documentation, tasks, and Docker configurations. Uv Integration: Effortless dependency management and packaging with uv.
• Automated Testing and Checks: Pre-configured workflows using Pytest, Ruff, Mypy, Bandit, and Coverage to ensure code quality, style, security, and type safety.
• Pre-commit Hooks: Automatic code formatting and linting with Ruff and other pre-commit hooks to maintain consistency.
• Dockerized Deployment: Dockerfile and docker-compose.yml for building and running the package within a containerized environment (Docker).
• uv+just Task Automation: just commands to simplify development workflows such as cleaning, installing, formatting, checking, building, documenting and running the project.
• Comprehensive Documentation: pdoc generates API documentation, and Markdown files provide clear usage instructions.
• GitHub Workflow Integration: Continuous integration and deployment workflows are set up using GitHub Actions, automating testing, checks, and publishing.
• Profiling: Several standard profilers are included for developers to choose from. Two popular call-stack profilers are pyinstrument and pyspy. memray is included for memory profiling.
• Load testing with Locust.

Development

Checks

This will run all checks on this cookiecutter repo (not just the project template) as specified in the tasks/check.just command: code quality, test coverage, unit tests, formatting, typing, and security.

uv run just check

Type checking

Syncing Projects with the Latest Template

If you have older projects created from this template before recent updates, you can sync them with the latest template files using the template_sync_cli.py utility.

Using the Sync Tool

The sync tool updates high-priority files in your project to match the latest template:

• tasks/ - Task definitions for development automation
• justfile - Task runner configuration
• .gitignore - Git ignore patterns
• .python-version - Python version specification

Basic usage:

# Sync your project with the template
python template_sync_cli.py --source /path/to/template --target /path/to/your-project

# Preview changes without committing (dry-run)
python template_sync_cli.py --source /path/to/template --target /path/to/your-project --dry-run

With Claude Code:

/sync-project-template --source ~/python-project-template --target ~/your-project

The sync tool will:

1. Validate both source (template) and target (project) directories
2. Copy updated files and directories
3. Stage changes in git
4. Create a commit with a summary of synced files

Important Notes

• Your project must be a git repository for syncing to work
• The tool skips files that haven't changed
• A commit is automatically created with all synced changes
• Use --dry-run to preview changes before committing

License

The source material this is adapted from is licensed under the MIT License. See the LICENSE.txt file for details.