> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo crear tu archivo pyproject.toml

> Guía completa del archivo pyproject.toml en Python: aprende a crearlo, listar dependencias, fijar versiones y preparar tu proyecto para producción.

## 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

***

<Steps>
  <Step title="Crea el archivo pyproject.toml">
    Primero, crea un archivo llamado `pyproject.toml` en la raíz de tu proyecto.
  </Step>

  <Step title="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:

    ```toml pyproject.toml theme={null}
    [project]
    name = "my-python-project"
    description = "A sample Python project using pyproject.toml"
    version = "1.0.0"
    ```
  </Step>

  <Step title="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.

    ```toml pyproject.toml theme={null}
    [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"
    ]
    ```
  </Step>

  <Step title="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`.

    ```toml pyproject.toml theme={null}
    [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"
    ```
  </Step>
</Steps>

***

## 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.

```bash theme={null}
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:

```bash theme={null}
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.