Saltar al contenido principal

​
Archivo pyproject.toml para Python

El archivo pyproject.toml es una forma moderna de especificar en un único archivo todos los requisitos del sistema de compilación y las dependencias de tu proyecto. Esta guía muestra cómo crear, configurar y usar pyproject.toml para garantizar la consistencia entre los entornos de desarrollo y producción.

​
¿Qué es un archivo pyproject.toml?

Un pyproject.toml lista las dependencias, el sistema de compilación y otros metadatos de tu proyecto Python. Esto permite:
  • Que tú y tu equipo mantengan entornos idénticos
  • Que los nuevos colaboradores reproduzcan el entorno exactamente
  • Configurar las dependencias de desarrollo y producción por separado
1

Crea el archivo pyproject.toml

Primero, crea un archivo llamado pyproject.toml en la raíz de tu proyecto.
2

Define los detalles de tu proyecto

En el archivo pyproject.toml, comienza definiendo los metadatos de tu proyecto. Definiremos el nombre del proyecto, la versión, la descripción y otra información relevante.
El nombre del proyecto debe estar compuesto por letras ASCII, dígitos, guiones bajos “_”, guiones “-” y puntos “.”. No debe comenzar ni terminar con un guion bajo, guion o punto. Por ejemplo:
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
3

Lista las dependencias del proyecto

A continuación, listaremos las dependencias necesarias para nuestro proyecto. Podemos especificar tanto dependencias de desarrollo como de producción. Las dependencias de producción se listan en la sección dependencies, mientras que las dependencias de desarrollo pueden listarse en optional-dependencies con un nombre de grupo específico (por ejemplo, dev).
Puedes especificar las versiones de tus dependencias usando operadores de comparación como ==, >=, <… En el ejemplo de abajo no especificamos versiones. Esto significa que se instalará la más reciente. Se recomienda especificar versiones exactas para garantizar la reproducibilidad y evitar rupturas causadas por actualizaciones incompatibles en producción.
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord-py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]
4

Configura el sistema de compilación

Por último, debemos especificar los requisitos del sistema de compilación. Esto es necesario para que herramientas como pip sepan cómo compilar e instalar tu proyecto. Usaremos setuptools como nuestro backend de compilación, que es una elección común para proyectos Python, pero puedes elegir otros como poetry.
pyproject.toml
[project]
name = "my-python-project"
description = "A sample Python project using pyproject.toml"
version = "1.0.0"
dependencies = [
    "discord.py",
    "aiohttp"
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black"
]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

​
Instalar dependencias con pip

Para instalar las dependencias listadas en tu archivo pyproject.toml, puedes usar pip u otras herramientas compatibles con pyproject.toml. Esto te permite trabajar en tu proyecto teniendo las dependencias instaladas. 
pip install .
Este comando leerá el archivo pyproject.toml, instalará las dependencias listadas en dependencies y preparará tu proyecto para el desarrollo. Si también quieres instalar las dependencias de desarrollo, puedes usar: 
pip install .[dev]
Esto instalará tanto las dependencias de producción como las de desarrollo, permitiéndote trabajar en tu proyecto con todas las herramientas necesarias.

​
Buenas prácticas y consejos:

  • Mantenlo actualizado: Revisa y actualiza pyproject.toml con regularidad a medida que añades nuevas dependencias
  • Usa versiones exactas: Usa siempre == en lugar de >, >= o ninguna versión para evitar sorpresas en producción
  • Control de versiones: Confirma pyproject.toml en git para rastrear los cambios de dependencias y las actualizaciones de versión
  • Entorno aislado: Mantén un entorno virtual por proyecto para evitar conflictos globales
  • Prueba localmente: Antes de hacer el deploy, prueba el archivo con pip install . en un entorno nuevo

​
Próximos pasos

Con tu archivo pyproject.toml configurado:
  1. Confírmalo en tu repositorio Git.
  2. Aloja tu proyecto en Square Cloud.
  3. Configura el deploy automático mediante GitHub.
  4. ¡Bienvenido al hosting profesional de aplicaciones Python!
Un archivo pyproject.toml bien estructurado es la base de cualquier aplicación Python exitosa, garantizando que tu aplicación funcione perfectamente en Square Cloud.