Python Project Template

A modern, minimal Cookiecutter template to kickstart your Python projects. It comes preconfigured with uv and includes all the essential tools for seamless development, testing, and code quality checks.

Features

• Fast and modern dependency management with uv.
• Automated linting, formatting, docstring checks, typo detection, secret scanning, and static analysis via pre-commit.
• Code quality checks with ruff and type safety with mypy.
• Parallel test execution and coverage reporting using pytest.
• Built-in config and logging setup in src/config/ using pydantic and loguru.
• Example I/O base classes in src/io/base.py to promote clean, extensible design.
• CI/CD workflows powered by GitHub Actions.
• Preconfigured Dockerfile for containerization and deployment.

Prerequisites

Before using this template, make sure you have the following installed:

• Cookiecutter. Install it using:

  pip install cookiecutter

• uv (check this link for more details).

Installation

1. Create the Python project:

   cookiecutter git@github.com:miguelmendesduarte/cookiecutter-python-template.git

2. Enter project details as prompted (example):

   [1/4] project_name (my-project): my-project-test
   [2/4] project_description (A brief description of the project.): This is just a test project.
   [3/4] author_name (Jane Doe): Miguel Duarte
   [4/4] author_email (jane.dow@example.com): miguel@gmail.com

   ⚠️ Note: The project name should use dashes (-) instead of spaces.

3. Navigate to the project folder (replace <your-project-folder> with the actual folder name):

   cd <your-project-folder>

4. Install all dependencies using uv:

   uv sync --all-extras

5. (Optional) Install pre-commit.

   pre-commit install

Usage

Once your project is set up, you can start coding right away! 🥳 The following commands are available to help with common tasks:

Initialize a Github Repository (Optional)

If you want to create a GitHub repository for your project, follow these steps:

1. Initialize a git repository:

   git init

2. Add your remote repository (replace with your own GitHub repo URL):

   git remote add origin git@github.com:yourusername/your-repo-name.git

3. Add and commit your files:

   git add .
   git commit -m "Initial commit"

4. Push to GitHub:

   git push -u origin main

Running Tests

To run tests with coverage (using auto parallelism):

make test

Static Checks & Fixes

To check and automatically fix code style, formatting, and types:

make static-fix

Environment Variables

If needed, create your .env file by copying the example:

cp .env.example .env

🚢 Running with Docker

1. Build the image:

   docker build -t my-project .

2. Run the container (default module: src.main):

   docker run --rm my-project

🚀 Contributing

Feel free to open a pull request, create an issue, or send an email if you have any feature requests, improvements, or questions!