GitHub - GiovanniGiacometti/python-repo-template: A Python template repository, featuring Just and UV

https://github.com/GiovanniGiacometti/python-repo-template • May 17, 2025 11:27

Extracto

A Python template repository, featuring Just and UV - GiovanniGiacometti/python-repo-template

Resumen

Resumen Principal

Este contenido presenta una plantilla de repositorio Python para 2025, diseñada para ser simple, rápida, personalizable y lista para usar, consolidando las mejores prácticas y herramientas modernas en un solo paquete. Se posiciona como una solución integral que aborda tanto las necesidades de desarrollo como de infraestructura. En el ámbito de desarrollo, integra herramientas de vanguardia como UV para una gestión ultra-rápida de paquetes, Just como un moderno ejecutor de comandos, Ruff para un linting y formateo de código excepcionalmente veloz, Mypy para el chequeo estático de tipos, Pytest para pruebas robustas y Loguru para una gestión de logs simplificada. A nivel de infraestructura, incorpora pre-commit hooks para asegurar la calidad del código, soporte robusto para Docker con compilaciones multi-etapa e imágenes distroless para despliegues ligeros, y un pipeline CI/CD con GitHub Actions para automatizar pruebas y linting. Esta plantilla está pensada para optimizar el flujo de trabajo de los desarrolladores, estandarizando el setup del proyecto y promoviendo la consistencia desde el inicio.

Elementos Clave

Conjunto de Herramientas de Desarrollo de Alto Rendimiento: La plantilla integra un ecosistema de herramientas cuidadosamente seleccionadas para maximizar la productividad y calidad del código. UV acelera la gestión de dependencias, Ruff garantiza un código limpio y consistente con su velocidad de linting y formateo, mientras que Mypy y Pytest aseguran la robustez y corrección del software a través del tipado estático y pruebas exhaustivas, respectivamente. Loguru simplifica aún más la depuración y monitoreo.
Infraestructura Automatizada y Orientada a la Producción: Se incluye soporte completo para Docker con un Dockerfile multi-etapa que produce imágenes optimizadas y distroless, crucial para despliegues eficientes y seguros. Además, la plantilla incorpora pre-commit hooks para automatizar verificaciones de calidad antes de cada commit y un pipeline CI/CD con GitHub Actions que ejecuta automáticamente pruebas y linters en cada push a la rama principal, garantizando la integración continua y la entrega consistente.
Gestión de Entornos Flexible con UV y Just: La plantilla se basa en UV como gestor de paquetes y Just

Contenido

Python Repository Template

The ultimate 2025 Python repository template. Simple, fast, customizable, and ready to use.

I wrote a blog post about this template! Check it out here

🎯 Core Features

Development Tools

📦 UV - Ultra-fast Python package manager
🚀 Just - Modern command runner with powerful features
💅 Ruff - Lightning-fast linter and formatter
🔍 Mypy - Static type checker
🧪 Pytest - Testing framework with fixtures and plugins
🧾 Loguru - Python logging made simple

Infrastructure

🛫 Pre-commit hooks
🐳 Docker support with multi-stage builds and distroless images
🔄 GitHub Actions CI/CD pipeline

Usage

The template is based on UV as package manager and Just as command runner. You need to have both installed in your system to use this template.

Once you have those, you can just run

to create a virtual environment and install all the dependencies, including the development ones. If instead you want to build a "production-like" environment, you can run

In both cases, all extra dependencies will be installed (notice that the current pyproject.toml file has no extra dependencies).

You also need to install the pre-commit hooks with:

Formatting, Linting and Testing

You can configure Ruff by editing the .ruff.toml file. It is currently set to the default configuration.

Format your code:

Run linters (ruff and mypy):

Run tests:

Do all of the above:

Executing

The code is a simple hello world example, which just requires a number as input. It will output the sum of the provided number with a random number. You can run the code with:

Docker

The template includes a multi stage Dockerfile, which produces an image with the code and the dependencies installed. You can build the image with:

Github Actions

The template includes a Github Actions workflow that runs tests and linters on every push on the main branch. You can find the workflow file in .github/workflows/main-list-test.yml.