Pyproject.toml de Python: Una visión general

Compartir código y colaborar en software de código abierto ha supuesto una transformación en el desarrollo de software. Ha permitido a los desarrolladores crear aplicaciones más complicadas con equipos más pequeños utilizando paquetes y bibliotecas ya existentes.

En el ecosistema Python, la mayoría de los paquetes están registrados en el Índice de paquetes Python (PyPI). Utilizando el índice, los desarrolladores pueden compartir su código como paquetes para otros desarrolladores. Para crear su propio paquete y subirlo a PyPI, necesitará un archivo pyproject.toml. Este artículo es una guía sobre cómo funciona.

¿Qué es pyproject.toml?

Antes de llegar a lo que es el archivo, entendamos primero el vacío que intenta llenar. Cuando suba un paquete a PyPI, se podrá instalar mediante pip. Por ejemplo, si su paquete se llama ejemplo-paquete después de subirlo a PyPI, sería instalable usando el comando

pip install ejemplo-paquete

Al publicar paquetes en el Índice de Paquetes Python, usted sube un archivo .whl. Pero cuando se escribe código, la mayoría de las veces se escriben archivos .py, así que ¿cómo se genera un archivo . whl? Usted utiliza una herramienta de compilación como setuptools o poetry.

Esta herramienta tomará su código fuente y lo convertirá en un archivo . whl que se puede cargar. Como se mencionó antes, hay múltiples herramientas que puede utilizar para generar un archivo whl. Para especificar qué herramienta quiere que utilice Python, debe escribirlo en el archivo pyproject. toml.

Por lo tanto, el archivo pyproject.toml es un archivo que especifica cómo debe construirse su proyecto Python en un paquete. Además de eso, puede proporcionar información adicional, como los metadatos de su paquete, que se mostrarán en el listado de su paquete en PyPI.

El proceso de construcción de Python

Para ejecutar la herramienta del proceso de construcción, utilice el comando

python -m build

Pero antes de poder hacerlo, necesita instalarlo

python -m pip install build

Cuando ejecute el comando build en un proyecto que contenga un archivo pyproject.toml, creará nuevos archivos y directorios. Estos incluyen la carpeta distque contiene dos archivos, un archivo comprimido sdist y un archivo .whl que luego distribuirá en PyPI.

¿Cómo generar un paquete Python?

Para ayudarle a solidificar lo que acabamos de aprender, he aquí un ejemplo de cómo generar un paquete Python.

#1. Cree un proyecto de ejemplo

Para empezar, cree un paquete sencillo con la siguiente estructura de alfombras

example_package/
├─ example_package/
│ ├─ example_module.py
│ ├─ __init__.py
├─ pyproject.toml
├─ setup.cfg
├─ README.md

El directorio raíz del proyecto se llama ejemplo_paquete. Ahí es donde está contenida toda nuestra base de código. Dentro de la raíz del proyecto, tenemos tres archivos y un directorio. Su contenido se explica a continuación:

pyproject.toml

Este archivo contiene información sobre qué herramientas de compilación utilizará cuando construya su proyecto. Para este sencillo ejemplo, estos son los contenidos:

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

En este caso, estamos declarando setuptools. build_meta como nuestro build backend. Pero setuptools.build_meta está contenido dentro del paquete setuptools, así que primero, lo listamos como un requisito en nuestra lista de requisitos. Discutiremos más opciones que puede especificar más adelante en este artículo.

LÉAME.md

Contiene información sobre su paquete. Se mostrará como documentación en la página de su paquete en PyPI. Puede escribir cualquier cosa en ese archivo.

setup.cfg

El archivo setup . cfg contiene metadatos del proyecto, como el nombre del paquete y la versión actual. Por ahora, añada el siguiente código como contenido de setup. cfg:

[<x>metadatos]</x>
nombre = ejemplo-paquete
versión = 1.0.0

ejemplo-proyecto

Dentro de nuestro directorio raíz hay otro directorio con el mismo nombre. Este directorio es donde reside nuestro código fuente. Para fines de demostración, he incluido dos archivos:

• ejemplo_modulo.py - Contiene una función ficticia. Usted también puede hacer lo mismo.
• __init__.py - Hará del directorio un paquete que puede ser importado. Puede estar vacío.

#2. Ejecute el comando de compilación

Ahora, puede ejecutar el comando build en el directorio raíz del proyecto.

python -m build

Si no lo ha hecho, asegúrese de instalar la herramienta utilizando lo siguiente:

pip install build

Debería obtener una salida parecida a esta:

Como puede ver, la última línea le indica que construyó example-package-1.0.0.tar.gz y example-package-1.0.0-py3-none-any-whl. Cuando liste el contenido de su directorio utilizando el comando ls que aparece a continuación, debería ver los nuevos archivos.

ls

La salida debería ser la siguiente:

dist ejemplo_paquete ejemplo_paquete.egg-info pyproject.toml README.md setup.cfg

Si lista el contenido de su directorio dist, debería encontrar el archivo .whl y el archivo tar.gz.

$ ls dist
example_package-1.0.0-py3-none-any.whl
example-package-1.0.0.tar.gz

Contenido del archivo pyproject.toml

En nuestro sencillo ejemplo, sólo hemos especificado el sistema de compilación de nuestro proyecto Python. Sin embargo, puede añadir más información a su archivo pyproject.toml. Estas son algunas de las opciones más comunes.

metadatos

En lugar de especificar los metadatos en el setup.cfg, puede escribirlos en su pyproject.toml. Esta información se utilizará al crear un listado para su paquete en el índice de paquetes.

Además, puede especificar las dependencias de su paquete y sus versiones para que puedan instalarse cuando se instale su paquete.

[proyecto]
name = "hello-world"
version = "1.0.0"
description = "Mi primer paquete Python"
requires-python = ">=3.8"
keywords = ["python", "first-project"]
authors = [
 {name = "John Doe", email = "john@example.com"},
]
dependencies = [
 "requests",
 "gidgethub[httpx]>4.0.0",
]

herramienta.<nombre_de_la_herramienta&gt

También puede utilizar la herramienta .<nombre_de_la_herramienta> donde es el nombre de la herramienta para proporcionar diferentes opciones de configuración para las herramientas que utilice.

Esto sólo puede hacerse con herramientas que admitan la configuración mediante este método. Por ejemplo, puede pasar opciones de configuración a Negro, un linter de código.

[tool.black]
line-length = 88
target-version = ["py38", "py39"]

Archivo de ejemplo

Reuniendo lo que hemos aprendido, he aquí un ejemplo de archivo pyproject.toml:

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

<x>[metadata]</x>
name = "my-project"
version = "1.0.0"
description = "Un proyecto de ejemplo"
author = "Su nombre"
author_email = "your.email@example.com"
license = "MIT"
keywords = ["ejemplo", "proyecto"]

[options]
python_requires = ">=3.6"

[tool.black]
line-length = 88
include = "\\.pyi?$"
exclude = '''
/(
 \.git
 | \.hg
 | \.mypy_cache
 | \.tox
 | |.venv
 | _build
 | buck-out
 | build
 | dist
)/
'''

[tool.blackd]
port = 45484
host = "localhost"

Para más información, lea esta página.

Ventajas de pyproject.toml

✅ Proporciona una forma estándar de gestionar las dependencias de los proyectos Python. Las dependencias
y otros metadatos relevantes de los proyectos pueden especificarse de forma declarativa.

✅ También proporciona una forma de especificar otros metadatos en sus proyectos, como los autores, la licencia y la URL de GitHub, entre otros atributos útiles.

✅ Se adapta a diferentes sistemas de compilación, y cambiar de sistema de compilación es fácil.

Palabras finales

pyproject.toml es un estándar útil que ayuda a evitar las desventajas de utilizar setup.py. Es más útil cuando está creando paquetes para su distribución. Para la mayoría de los proyectos nuevos, debería utilizar pyproject.toml en lugar de setup.py.

A continuación, vea cómo comprobar la versión de Python en Windows, Linux y macOS.