Herramientas de empaquetado de Python#

Herramientas para construir su paquete#

Hay varias herramientas de construcción diferentes que puede utilizar para crear las distribuciones sdist y wheel de su paquete de Python. A continuación, discutimos las características, beneficios y limitaciones de las herramientas de empaquetado de Python más comúnmente utilizadas. Nos enfocamos en paquetes de Python puro en esta guía. Sin embargo, también destacamos herramientas que actualmente admiten paquetes con extensiones en C/C++ y otros lenguajes.

Diagrama de árbol de decisión que muestra las diversas herramientas de empaquetado frontend y backend. Puede decidir qué herramienta de empaquetado utilizar pensando en qué características necesita. PDM y Hatch son actualmente las herramientas más flexibles ya que también utilizan diferentes backends de construcción. Por lo tanto, actualmente PDM y Hatch son las herramientas que creemos que los principiantes podrían apreciar más, con Poetry siendo un segundo cercano. Poetry es agradable para proyectos de Python puro. — Diagrama que muestra las diferentes herramientas de construcción de frontend disponibles para usar en el ecosistema de paquetes de Python que puede seleccionar. Seleccionamos herramientas para incluir en este diagrama basándonos en la encuesta de PyPI que nos ayudó a comprender las herramientas más populares en el ecosistema. Cada herramienta tiene características diferentes como se destaca a continuación.#

Si desea saber más sobre paquetes de Python que tienen extensiones escritas en otros lenguajes, consulte la página sobre construcciones de paquetes complejas.

Herramientas que revisamos aquí#

En esta sección hemos seleccionado las herramientas de empaquetado más populares en la encuesta de PyPA. Aprenderá más sobre las siguientes herramientas en esta página:

Resumen de herramientas Hatch vs. PDM vs. Poetry (y setuptools)#

Si está buscando un resumen rápido, lea a continuación.

En general, cualquier herramienta moderna que seleccione de esta página será excelente para construir su paquete. La selección de que herramienta usar depende de las características de su flujo de trabajo.
Sugerimos que los principiantes comiencen con una herramienta de flujo de trabajo moderna como PDM en lugar de navegar por las complejidades de setuptools.
Si va a utilizar Poetry (es la herramienta más popular y tiene la mejor documentación), tenga en cuenta que la herramienta asume automáticamente una dependencia a la versión mayor actual y considere eliminar estas dependencias cuando la herramienta las agregue. ¡Si hace eso, Poetry funcionará bien para construcciones de Python puro! Poetry también tiene un discord activo donde puede hacer preguntas.

Abajo hay algunas características que Hatch y PDM ofrecen que Poetry no.

PDM:

Admite otros backends, lo que lo hace ideal para construcciones que no son de Python puro. Esto significa que PDM es una excelente opción tanto para Python puro como para construcciones de Python más complejas, ya que admite meson-python y otros backends de construcción.
Ofrece flexibilidad en la gestión de dependencias que nos gusta
Ofrece archivos de bloqueo si los necesita

Hatch:

Ofrece gestión de entornos que le permite ejecutar pruebas en versiones de Python. Si esta característica es importante, Hatch es el claro ganador.
Ofrece una herramienta Nox / Make file para optimizar su flujo de trabajo de construcción. Si está buscando reducir el número de herramientas en su flujo de trabajo, Hatch podría ser una buena opción.

Constructores frontend vs. constructores backend#

Para comprender mejor sus opciones, cuando se trata de construir un paquete de Python, es importante primero comprender la diferencia entre un constructor de frontend y un constructor de backend.

Constructores backend#

La mayoría de las herramientas de empaquetado tienen una herramienta de construcción de backend que construye su paquete y crea archivos de distribución (sdist y wheel) asociados. Algunas herramientas, como Flit, solo admiten construcciones de paquetes de Python puro. Una construcción de Python puro se refiere a una construcción de paquete que no tiene extensiones escritas en otro lenguaje de programación (como C o C++).

Otros paquetes que tienen extensiones en C y C++ (o que envuelven otros lenguajes como Fortran) requieren pasos adicionales de compilación de código cuando se construyen. Backends como setuptools.build, meson.build y scikit-build admiten construcciones complejas con pasos personalizados. Si su construcción es particularmente compleja (es decir, tiene varias extensiones C/C++), entonces le sugerimos que use meson.build o scikit-build.

Constructores frontend de paquetes de Python#

Una herramienta de frontend de empaquetado se refiere a una herramienta que facilita la realización de tareas de empaquetado comunes utilizando comandos similares. Estas tareas incluyen:

Construir sus paquetes (crear las distribuciones sdist y wheel)
Instalar su paquete en un modo de desarrollo (para que se actualice cuando actualice su código)
Publicar en PyPI
Ejecutar tests
Construir documentación
Gestionar uno o varios entornos de desarrollo en los que necesita ejecutar tests y desarrollar su paquete

Hay varias herramientas de empaquetado de Python que puede utilizar para construcciones de Python puro. Cada herramienta de frontend discutida a continuación admite un conjunto ligeramente diferente de tareas de empaquetado de Python.

Por ejemplo, puede utilizar las herramientas de empaquetado Flit, Hatch o PDM tanto para construir como publicar su paquete en PyPI. Sin embargo, mientras Hatch y PDM admite el versionado y la gestión de entornos, Flit no lo hace. Si desea una herramienta que admita el bloqueo de dependencias, puede utilizar PDM o Poetry pero no Hatch. Si solo necesita construir los archivos de distribución sdist y wheel de su paquete, entonces puede quedarse con Build de PyPA. Luego usaría Twine para publicar en PyPI.

Nota

Si está utilizando Setuptools, no hay un frontend de construcción predeterminado fácil de usar que realice múltiples tareas. Necesitará usar build para construir su paquete y twine para publicar en PyPI.

Ejemplo de pasos de construcción que se pueden simplificar utilizando una herramienta de frontend#

A continuación, puede ver cómo una herramienta de construcción simplifica su experiencia de empaquetado. Ejemplo para construir su paquete con Hatch:

# Build your sDist and .whl files
hatch build

# Example to publish to PyPI:
hatch publish --repo test

Ejemplo de pasos de construcción utilizando el backend de setuptools y build:

# Build the package
python3 -m build

# Publish to test PyPI using twine
twine upload -r testpypi dist/*

Eligiendo un backend de construcción#

La mayoría de las herramientas de empaquetado de frontend tienen su propia herramienta de construcción de backend. La herramienta de construcción crea los archivos de distribución (sdist y wheel) de su paquete. Para paquetes de Python puro, la principal diferencia entre los diferentes backends de construcción discutidos a continuación es:

Qué tan configurables son - por ejemplo, ¿le permiten agregar pasos de construcción que admitan extensiones no Python?
Cuánto necesita configurarlos para asegurarse de que los archivos correctos se incluyan en sus distribuciones sdist y wheel.

Construcción de soporte de backend para paquetes no puros de Python#

Es importante tener en cuenta que algunos backends de construcción, como Flit-core, solo admiten construcciones de Python puro. Otros backends admiten extensiones en C y C++ de la siguiente manera:

setuptools admite construcciones utilizando extensiones en C / C++
Hatchling (backend de hatch) admite extensiones en C / C++ a través de complementos que el desarrollador crea para personalizar una construcción
El backend de PDM admite extensiones en C / C++ utilizando setuptools
El backend de Poetry admite extensiones en C/C++ sin embargo esta funcionalidad actualmente no está documentada. Por lo tanto, no recomendamos usar Poetry para construcciones complejas o no puras de Python hasta que esté documentada.

Si bien no discutiremos construcciones más complejas a continuación, identificaremos qué herramientas tienen soporte documentado para extensiones en C / C++.

Un ecosistema de herramientas de construcción de Python#

A continuación, presentamos varias de las herramientas de frontend de construcción de paquetes de Python más comúnmente utilizadas. Destacamos las características que ofrece cada herramienta como una forma de ayudarlo a decidir qué herramienta podría ser la mejor para su flujo de trabajo.

No sugerimos usar setuptools

Sugerimos que elija una de las herramientas modernas discutidas anteriormente en lugar de setuptools porque setuptools requerirá algunos conocimientos adicionales para configurarse correctamente.

Revisamos setuptools como backend porque todavía es popular. Sin embargo, no es la opción más amigable para el usuario.

Las herramientas más utilizadas en el ecosistema son el backend de setuptools (con build) y Poetry (una herramienta de frontend con numerosas características y excelente documentación).

Gráfico que muestra los resultados de la encuesta de PyPA 2022 de herramientas de empaquetado de Python. En el eje x está la respuesta porcentual y en el eje y están las herramientas. — Los resultados de la encuesta de desarrolladores de Python (n => 8,000 usuarios de PyPI) muestran setuptools y poetry como las herramientas de empaquetado de Python más utilizadas. Las herramientas centrales que hemos visto que se utilizan en la comunidad científica están incluidas aquí. Puede ver los resultados completos de la encuesta haciendo clic aquí. NOTA: estos datos representan a los mantenedores en todos los dominios y es probable que estén fuertemente representados por aquellos en desarrollo web. Por lo tanto, esto representa una instantánea de todo el ecosistema de Python.#

Elige una herramienta de flujo de trabajo de construcción#

Las herramientas que revisamos a continuación incluyen:

Twine, Build + setuptools
Flit
Hatch
PDM
Poetry

Cuando esté seleccionando una herramienta, puede considerar este flujo de preguntas:

¿Es su herramienta de Python puro? ¿Sí? ¡Puede usar la herramienta que desee! Elija la herramienta que tenga las características que desea utilizar en su flujo de trabajo de construcción. Sugerimos:

Flit, Hatch, PDM or Poetry (read below for more)

¿Tiene su herramienta unas pocas extensiones en C o C++? Genial, sugerimos usar PDM por el momento. Es la única herramienta en la lista a continuación que tiene tanto un flujo de trabajo documentado para apoyar tales extensiones como soporte para otros backends en el caso de que los hooks de construcción no sean suficientes para su flujo de trabajo. PDM admite otros backends como scikit-build y meson-python que le permitirán personalizar completamente la construcción de su paquete.

NOTA: También puede usar Hatch para construcciones no puras de Python. Hatch, similar a PDM, le permite escribir sus propios hooks de construcción o complementos para admitir pasos de construcción personalizados. Pero actualmente, hatch no admite otros backends de construcción. Muchos de los paquetes científicos principales se están cambiando a meson-python para construir sus paquetes. Por lo tanto, apreciamos que PDM pueda trabajar con meson-python específicamente.

Resumen de herramientas de empaquetado de Python#

A continuación, resumimos las características ofrecidas por las herramientas de frontend de construcción más populares. Es importante tener en cuenta que estas herramientas de frontend eliminan la necesidad de usar otras herramientas centrales en su flujo de trabajo. Por ejemplo, si usa setuptools, también necesitará usar Build y Twine para construir su paquete y publicar en PyPI. Pero si usa Poetry, Hatch o PDM, puede hacer todas esas cosas con la misma herramienta (por ejemplo, hatch build, hatch publish o pdm build, pdm publish).

Note que debido a que setuptools no ofrece una interfaz de frontend, no se incluye en la tabla.

Tabla de características de las herramientas de empaquetado#

Feature	Flit	Hatch	PDM	Poetry
Backend de construcción predeterminado	Flit-core	hatchling	PDM	Poetry-core
Usar otros backends de construcción	✖	✅	✅	✖
Gestión de dependencias	✖	✖	✅	✅
Publicar en PyPI	✅	✅	✅	✅
Versionado basado en control de versiones (usando `git tags`)	✖	✅	✅	✅
Incremento de versión	✖	✅	✅	✅
Gestión de entornos	✖	✅	✅	✅
¿Más de un mantenedor? (factor bus)	✖	✖	✖	✅

Notas:

Hatch planea admitir la gestión de dependencias en el futuro
Poetry admite versionado semántico. Por lo tanto, admitirá el incremento de versión siguiendo los mensajes de confirmación si utiliza una herramienta como Python Semantic Release

PDM#

PDM is a Python packaging and dependency management tool. PDM supports builds for pure Python projects. It also provides multiple layers of support for projects that have C and C++ extensions.

PDM admite extensiones en C y C++

PDM admite el uso del backend de PDM y setuptools al mismo tiempo. Esto significa que puede ejecutar setuptools para compilar y construir extensiones en C. El backend de construcción de PDM recibe los archivos de extensión compilados (.so, .pyd) y los empaqueta con los archivos de Python puro.

PDM features#

Feature	PDM	Notes
Usar otros backends de construcción	✅	Cuando configura PDM, le permite seleccionar uno de varios backends de construcción, incluidos: PDM-core, flit-core y hatchling. PDM también puede trabajar con Meson-Python que admite construcciones de Python más complejas.
Especificaciones de dependencias	✅	PDM has flexible support for managing dependencies. PDM defaults to using an open bound (e.g. `requests >=1.2`) approach to dependencies. However you can customize how you want to add dependencies in case you prefer another approach such as that of Poetry which uses an upper bound limit.**
Archivos de bloqueo de entorno	✅	PDM y Poetry son actualmente las únicas herramientas que crean archivos de bloqueo de entorno. Los archivos de bloqueo son más útiles para los desarrolladores que crean aplicaciones web donde bloquear el entorno es crítico para una experiencia de usuario consistente. Para paquetes utilizados por la comunidad, es probable que nunca desee usar un archivo de bloqueo.
Gestión de entornos	✅	PDM proporciona soporte de gestión de entornos. Admite entornos virtuales de Python, conda y un entorno local `__pypackages__` que es una opción más nueva en el ecosistema de Python. No se necesitan extensiones para este soporte.
Seleccione su tipo de entorno en la instalación	✅	Cuando ejecuta `PDM init`, PDM descubrirá los entornos que ya están en su sistema y le permitirá seleccionar uno para usar en su proyecto.
Publicar en PyPI	✅	PDM admite la publicación tanto en test PyPI como en PyPI
Versionado basado en control de versiones	✅	PDM tiene una herramienta similar a setuptools_scm integrada en ella que le permite usar versiones dinámicas
Incremento de versión	✅	PDM le permite incrementar la versión de su paquete utilizando términos de versión semántica estándar patch; minor; major
Sigue los estándares de empaquetado actuales	✅	PDM admite los estándares de empaquetado actuales para agregar metadatos al archivo pyproject.toml.
Instalar su paquete en modo editable	✅	PDM admite instalar su paquete en modo editable.
Construir sus distribuciones sdist y wheel	✅	Al igual que todas las demás herramientas, PDM también construye los archivos sdist y wheel de sus paquetes.

PDM vs. Poetry

La funcionalidad de PDM es similar a la de Poetry. Sin embargo, PDM también ofrece soporte adicional y documentado para extensiones en C y versionado basado en control de versiones. Por lo tanto, PDM es preferido para aquellos que trabajan en paquetes no puros de Python.

Sí está decidiendo entre Poetry y PDM, una diferencia más pequeña es la forma predeterminada en que se agregan las dependencias a su archivo pyproject.toml.

Poetry por defecto sigue un versionado semántico estricto agregando dependencias a su archivo pyproject.toml usando una restricción de límite superior (^). El bloqueo de límite superior significa que Poetry nunca incrementará una dependencia a la siguiente versión principal (es decir, de 1.2 a 2.0). Sin embargo, puede indicarle a Poetry que use un enfoque de límite abierto agregando explícitamente el paquete de esta manera: poetry add requests >= 1.2 en lugar de simplemente usar poetry add requests que resultará en un bloqueo de límite superior (es decir, los bloqueos de límite superior significan que requests 2.0 nunca se podría instalar incluso si saliera y su paquete pudiera beneficiarse de ello).
PDM por defecto utiliza la adición de dependencias de límites abiertos (>=) que es el enfoque preferido en el ecosistema de Python científico. Sin embargo, PDM también le permite especificar la forma en que se agregan las dependencias de forma predeterminada. Por lo tanto, también puede especificar límites superiores (^) utilizando PDM si requiere ese enfoque.

Finalmente, hay algunas diferencias matizadas en cómo ambas herramientas crean archivos de bloqueo de los que no entraremos en detalles aquí.

Dificultades con PDM#

PDM es una herramienta de empaquetado completa. Sin embargo, no está exenta de dificultades:

Su documentación puede ser confusa, especialmente si eres nuevo en el empaquetado. Por ejemplo, PDM no proporciona un flujo de trabajo de principio a fin en su documentación.
PDM solo tiene un mantenedor actualmente. Consideramos que los equipos de mantenedores con una sola persona son un riesgo potencial. Si el mantenedor decide que ya no tiene tiempo para trabajar en el proyecto, deja a los usuarios sin soporte. Hatch y Flit también tienen equipos de un solo mantenedor.

Puede ver un ejemplo de un paquete que usa PDM aquí. El archivo README de este le proporciona directamente una descripción general de cómo se ve la interfaz de línea de comandos de PDM cuando la usa.

Flit#

Flit es una herramienta de empaquetado sin adornos y simplificada que admite los estándares de empaquetado de Python modernos. Flit es una excelente opción si está construyendo un paquete básico para usar en un flujo de trabajo local que no requiere ninguna característica avanzada. Y si su estructura de paquete ya está creada. Más sobre eso a continuación.

Flit features#

Feature	Flit	Notes
Publicar en PyPI y test PyPI	✅	Flit admite la publicación tanto en test PyPI como en PyPI
Ayuda a agregar metadatos a su archivo pyproject.toml	✅	Flit admite agregar metadatos a su archivo pyproject.toml siguiendo los estándares de empaquetado modernos.
Sigue los estándares de empaquetado actuales	✅	Flit admite los estándares de empaquetado actuales para agregar metadatos al archivo pyproject.toml.
Instalar su paquete en modo editable	✅	Flit admite instalar su paquete en modo editable.
Construir sus distribuciones sdist y wheel	✅	Flit se puede usar para construir las distribuciones sdist y wheel de sus paquetes.

NOTA: _Si está utilizando la versión más actual de pip, admite tanto un enfoque de enlace simbólico flit install -s

Aprende más sobre flit

¿Por qué usar flit?

¿Por qué no querrías usar Flit#

Debido a que Flit no tiene adornos, es mejor para construcciones básicas y rápidas. Si eres un principiante, puede que quieras seleccionar Hatch o PDM que te ofrecerán más soporte en operaciones comunes.

Quizás NO quieras usar flit si:

Quieres configurar un seguimiento y gestión de versiones más avanzado (usando control de versiones para incrementar versiones)
Quieres una herramienta que maneje las versiones de las dependencias (usa PDM o Poetry en su lugar)
Tienes un proyecto que no es Python puro (Usa Hatch, PDM o setuptools)
Quieres gestión de entornos (usa PDM, Hatch o Poetry)

Hatch#

Hatch, similar a Poetry y PDM, proporciona una interfaz de línea de comandos unificada. Para contrastar Hatch con Poetry y PDM, este también proporciona un gestor de entornos para tests que le facilitará la ejecución de tests localmente en diferentes versiones de Python. También ofrece una característica similar a nox / makefile que le permite crear flujos de trabajo de construcción personalizados como construir su documentación localmente. Esto significa que potencialmente podría eliminar una herramienta como Make o Nox de su flujo de trabajo y usar Hatch en su lugar.

Características de Hatch#

Feature	Hatch	Notes
Usar otros backends de construcción	✅	Hatch utiliza el backend Hatchling de forma predeterminada, pero le permite usar otro backend cambiando la declaración en pyproject.toml.
Gestión de dependencias	✖	Actualmente, tiene que agregar dependencias manualmente con Hatch. Sin embargo, una característica para soportar la gestión de dependencias puede ser agregada en una versión futura.
Gestión de entornos	✅	Hatch admite entornos virtuales de Python. Si desea usar otros tipos de entornos como Conda, necesitará instalar un plugin como hatch-conda para soporte de conda.
Publicar en PyPI y test PyPI	✅	Hatch admite la publicación tanto en test PyPI como en PyPI
Versionado basado en control de versiones	✅	Hatch ofrece `hatch_vcs` que es un plugin que utiliza setuptools_scm para soportar el versionado utilizando etiquetas de git. El flujo de trabajo con `hatch_vcs` es el mismo que con `setuptools_scm`.
Incremento de versión	✅	Hatch le permite incrementar la versión de su paquete utilizando términos de versión semántica estándar patch; minor; major
Sigue los estándares de empaquetado actuales	✅	Hatch admite los estándares de empaquetado actuales para agregar metadatos al archivo pyproject.toml.
Instalar su paquete en modo editable	✅	Hatch instalará su paquete en cualquiera de sus entornos de forma predeterminada en modo editable. Puede instalar su paquete en modo editable manualmente utilizando `python -m pip install -e .` Hatch menciona instalaciones en modo editable pero se refiere a pip en su documentación.
Construir sus distribuciones sdist y wheel	✅	Hatch construirá las distribuciones sdist y wheel
✨Creación de entorno de matriz para soportar testing en diferentes versiones de Python✨	✅	La creación de entorno de matriz es una característica única de Hatch en el ecosistema de empaquetado. Esta característica es útil si desea probar su paquete localmente en diferentes versiones de Python (en lugar de usar una herramienta como tox).
✨Funcionalidad similar a Nox / MAKEFILE✨	✅	Esta característica también es única de Hatch. Esta funcionalidad le permite crear flujos de trabajo en la configuración pyproject.toml para hacer cosas como servir documentos localmente y limpiar el directorio de construcción de su paquete. Esto significa que puede tener una herramienta menos en su flujo de trabajo de construcción.
✨Un backend de construcción flexible: hatchling✨	✅	**El backend de construcción hatchling ofrecido por el mantenedor de Hatch permite a los desarrolladores construir fácilmente plugins para soportar pasos de construcción personalizados al empaquetar.

Hay algunos argumentos sobre este enfoque que coloca una carga en los mantenedores para crear un sistema de construcción personalizado. Pero otros aprecian la flexibilidad. El enfoque de hooks de construcción de Hatch también es comparable con las características ofrecidas por PDM.

¿Por qué no querría usar Hatch?#

Hay algunas características que Hatch no tiene y que pueden ser importantes para algunos. Estas incluyen:

Hatch no admite agregar dependencias. Tendrá que agregarlas manualmente.
Hatch no reconocerá por defecto los entornos de Conda sin un plugin.
Al igual que PDM, la documentación de Hatch puede ser difícil de utilizar, especialmente si eres nuevo en la construcción de paquete.
Hatch, al igual que PDM y Flit, actualmente solo tiene un mantenedor.

Poetry#

Poetry es una herramienta de construcción completa. También es la segunda herramienta de empaquetado de frontend más popular (según la encuesta de PyPA). Poetry es fácil de usar y tiene documentación limpia y fácil de leer.

Nota

Aunque algunos han usado Poetry para construcciones de Python con extensiones C/C++, este soporte no está documentado actualmente. Por lo tanto, no recomendamos usar Poetry para construcciones más complejas.

Características de Poetry#

Feature	Poetry	Notes
Añadir dependencias a su archivo pyproject.toml	✅	Poetry helps you add dependencies to your `pyproject.toml` metadata.
Especificación de dependencias	✅	Poetry le permite ser específico sobre la versión de las dependencias que agrega al archivo pyproject.toml de su paquete. Sin embargo, su enfoque de límite superior predeterminado puede ser problemático para algunos paquetes (le sugerimos que anule la configuración predeterminada al agregar dependencias). Lea a continuación para más información.
Gestión de entornos	✅	Poetry le permite usar su entorno integrado o puede seleccionar el tipo de entorno que desea usar para administrar su paquete. Lea más sobre sus opciones de gestión de entornos integrados.
Archivos de bloqueo	✅	Poetry crea un archivo poetry.lock que puede usar si necesita un archivo de bloqueo para su construcción.
Publicar en PyPI y test PyPI	✅	Poetry admite la publicación tanto en PyPI Test como en PyPI
Versionado basado en control de versiones	✅	El plugin Poetry dynamic versioning admite versionado utilizando etiquetas de git con Poetry.
Incremento de versión	✅	Poetry le permite incrementar la versión de su paquete utilizando términos de versión semántica estándar patch; minor; major
Sigue los estándares de empaquetado actuales	✅	Since version 2.0, Poetry supports most current project metadata standards. However, not all standards are supported, and it also supports the legacy Poetry format. Read below for more.
Instalar su paquete en modo editable	✅	Poetry supports installing your package in editable mode.
Construir sus distribuciones sdist y wheel	✅	Poetry construirá sus distribuciones sdist y wheel usando `poetry build`

Desafíos con Poetry#

Algunos desafíos de Poetry incluyen:

Poetry has its own concept of grouped dependencies (poetry add --group=GROUP_NAME DEPENDENCY). Dependencies added as grouped dependencies are not optional and there is no Python standard for this type of dependency. This should not be confused with «optional» dependencies (poetry add --optional=GROUP_NAME DEPENDENCY), which is standardised and lets you group your dependencies into several optional groups.
While Poetry supports «development» dependencies (i.e. dependencies you use for development but not running the code, such as pytest), Poetry does not yet follow the standardised format for specifying such dependencies.
Poetry, by default, pins dependencies using an «upper bound» limit (which is specified with the ^ symbol in the legacy format). However, this behavior can be over-written by specifying the dependency when you use poetry add as follows: poetry add "requests>=2.1" See breakout below for more discussion on issues surrounding upper-bounds pinning.

Poetry is a popular packaging tool and introduced many very useful features. However, if you decide to use it, then use caution when adding dependencies as Poetry’s approach to pinning can be problematic for many builds. If you use Poetry, we strongly suggest that you override the default upper bound dependency option.

Desafíos con el fijado de dependencias de Poetry

Por defecto, Poetry fija las dependencias utilizando ^ por defecto. Este símbolo ^ significa que hay un «límite superior» en la dependencia. Por lo tanto, Poetry no incrementará la versión de una dependencia a una nueva versión mayor. Por lo tanto, si su paquete usa una dependencia que está en la versión 1.2.3, Poetry nunca incrementará la dependencia a 2.0 incluso si hay una nueva versión mayor del paquete. En su lugar, Poetry incrementará hasta 1.9.x.

Poetry hace esto porque se adhiere a la versión semántica estricta que establece que un incremento de versión mayor (de 1.0 a 2.0 por ejemplo) significa que hay cambios de ruptura en la herramienta. Sin embargo, no todas las herramientas siguen la versión semántica estricta. Este enfoque se ha encontrado problemático por muchos de nuestros paquetes científicos principales.

Este enfoque tampoco soportará otras formas de versionar herramientas, por ejemplo, algunas herramientas usan calver que crea nuevas versiones basadas en la fecha.

Using Setuptools back-end for Python packaging with Build front-end#

Setuptools es la herramienta de construcción de empaquetado de Python más madura con desarrollo que data de 2009 y antes. Setuptools también tiene el mayor número de usuarios de la comunidad (según la encuesta de PyPA). Setuptools no ofrece un frontend de usuario como Flit, Poetry y Hatch ofrecen. Como tal, necesitará usar otras herramientas como build para crear las distribuciones de su paquete y twine para publicar en PyPI.

Aunque setuptools es la herramienta más comúnmente utilizada, sugerimos a los mantenedores de paquetes a considerar usar una herramienta más moderna para el empaquetado como Poetry, Hatch o PDM.

Discutimos setuptools aquí porque se encuentra muy a menudo en el ecosistema y entenderlo puede beneficiarle.

Setuptools features#

Algunas de las características de setuptools incluyen:

Flujo de trabajo de construcción completamente personalizable
Muchos paquetes científicos de Python lo utilizan.
Ofrece versionado de paquetes basado en control de versiones utilizando setuptools_scm
Admite empaquetado moderno utilizando pyproject.toml para metadatos
Admite compatibilidad con versiones anteriores para enfoques de empaquetado antiguos.

Desafíos al usar setuptools#

Setuptools tiene algunos desafíos:

Setuptools no admite características interactivas como la detección automática de la API por defecto si está trabajando en un IDE como VSCODE y está utilizando una instalación editable para desarrollo. Vea las notas aquí sobre el soporte de pylance. En comparación, herramientas como flit, hatch, PDM admiten características interactivas como la detección automática de la API cuando se utiliza un IDE como VSCODE o pycharm (¡siempre que su versión de pip esté actualizada!).
Debido a que setuptools tiene que mantener la compatibilidad con versiones anteriores en una gama de paquetes, no es tan flexible en su adopción de los estándares de empaquetado de Python modernos.
La compatibilidad con versiones anteriores mencionada anteriormente hace que la base de código sea más compleja.
Su experiencia como usuario será más compleja utilizando setuptools en comparación con otras herramientas discutidas en esta página.

También hay algunas configuraciones predeterminadas problemáticas de las que los usuarios deben ser conscientes cuando usan setuptools. Por ejemplo:

setuptools construirá un proyecto sin nombre o versión si no está utilizando un archivo pyproject.toml para almacenar metadatos.
setuptools también incluirá todos los archivos en el repositorio de su paquete si no le dice explícitamente que excluya archivos utilizando un archivo MANIFEST.in