pip tools

herramientas-pip = compilación-pip + sincronización-pip

Un conjunto de herramientas de línea de comandos para ayudarle a mantener actualizados sus paquetes basados ​​en pip , incluso cuando los haya fijado. Los fijas, ¿verdad? (Al crear su aplicación Python y sus dependencias para producción, debe asegurarse de que sus compilaciones sean predecibles y deterministas).

Instalación

De manera similar a pip , pip-tools debe instalarse en cada uno de los entornos virtuales de su proyecto:

$ source /path/to/venv/bin/activate
(venv) $ python -m pip install pip-tools

Nota : todos los comandos de ejemplo restantes suponen que ha activado el entorno virtual de su proyecto.

Ejemplo de uso para pip-compile

El comando pip-compile le permite compilar un archivo requirements.txt a partir de sus dependencias, especificado en pyproject.toml , setup.cfg , setup.py o requirements.in .

Ejecútelo con pip-compile o python -m piptools compile (o pipx run --spec pip-tools pip-compile si pipx se instaló con la versión adecuada de Python). Si usa varias versiones de Python, también puede ejecutar py -XY -m piptools compile en Windows y pythonX.Y -m piptools compile en otros sistemas.

pip-compile debe ejecutarse desde el mismo entorno virtual que su proyecto para que las dependencias condicionales que requieren una versión específica de Python u otros marcadores de entorno se resuelvan en relación con el entorno de su proyecto.

Nota : Si pip-compile encuentra un archivo requirements.txt existente que cumple con las dependencias, no se realizarán cambios, incluso si hay actualizaciones disponibles. Para compilar desde cero, primero elimine el archivo requirements.txt existente o consulte Actualización de requisitos para conocer enfoques alternativos.

Requisitos de pyproject.toml

El archivo pyproject.toml es el último estándar para configurar paquetes y aplicaciones, y se recomienda para proyectos nuevos. pip-compile admite tanto la instalación de su project.dependencies como su project.optional-dependencies . Gracias a que se trata de un estándar oficial, puede utilizar pip-compile para fijar las dependencias en proyectos que utilizan herramientas de empaquetado modernas que cumplen con los estándares, como Setuptools, Hatch o flit.

Supongamos que tiene una aplicación Python 'foobar' empaquetada con Setuptools y desea fijarla para producción. Puede declarar los metadatos del proyecto como:

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

[ project ]
requires-python = " >=3.9 "
name = " foobar "
dynamic = [ " dependencies " , " optional-dependencies " ]

[ tool . setuptools . dynamic ]
dependencies = { file = [ " requirements.in " ] }
optional-dependencies.test = { file = [ " requirements-test.txt " ] }

Si tiene una aplicación Django empaquetada con Hatch y desea fijarla para producción. También desea anclar sus herramientas de desarrollo en un archivo pin separado. Declaras django como una dependencia y creas un dev de dependencia opcional que incluye pytest :

[ build-system ]
requires = [ " hatchling " ]
build-backend = " hatchling.build "

[ project ]
name = " my-cool-django-app "
version = " 42 "
dependencies = [ " django " ]

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

Puede producir sus archivos pin tan fácilmente como:

$ pip-compile -o requirements.txt pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --output-file=requirements.txt pyproject.toml
#
asgiref==3.6.0
    # via django
django==4.1.7
    # via my-cool-django-app (pyproject.toml)
sqlparse==0.4.3
    # via django

$ pip-compile --extra dev -o dev-requirements.txt pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --extra=dev --output-file=dev-requirements.txt pyproject.toml
#
asgiref==3.6.0
    # via django
attrs==22.2.0
    # via pytest
django==4.1.7
    # via my-cool-django-app (pyproject.toml)
exceptiongroup==1.1.1
    # via pytest
iniconfig==2.0.0
    # via pytest
packaging==23.0
    # via pytest
pluggy==1.0.0
    # via pytest
pytest==7.2.2
    # via my-cool-django-app (pyproject.toml)
sqlparse==0.4.3
    # via django
tomli==2.0.1
    # via pytest

Esto es excelente tanto para fijar sus aplicaciones como para mantener estable el CI de su paquete Python de código abierto.

Requisitos de setup.py y setup.cfg

pip-compile también tiene soporte completo para proyectos basados ​​en setup.py y setup.cfg que usan setuptools .

Simplemente defina sus dependencias y extras como de costumbre y ejecute pip-compile como se indica arriba.

Requisitos de requirements.in

También puede utilizar archivos de texto sin formato según sus necesidades (por ejemplo, si no desea que su aplicación sea un paquete). Para utilizar un archivo requirements.in para declarar la dependencia de Django:

 # requirements.in
django

Ahora, ejecute pip-compile requirements.in :

$ pip-compile requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile requirements.in
#
asgiref==3.6.0
    # via django
django==4.1.7
    # via -r requirements.in
sqlparse==0.4.3
    # via django

Y producirá su requirements.txt , con todas las dependencias de Django (y todas las dependencias subyacentes) fijadas.

(requisitos-de-actualización)=

Requisitos de actualización

pip-compile genera un archivo requirements.txt utilizando las últimas versiones que cumplen con las dependencias que especifica en los archivos compatibles.

Si pip-compile encuentra un archivo requirements.txt existente que cumple con las dependencias, no se realizarán cambios, incluso si hay actualizaciones disponibles.

Para forzar pip-compile a actualizar todos los paquetes en un requirements.txt existente, ejecute pip-compile --upgrade .

Para actualizar un paquete específico a la última versión o a una versión específica, utilice el indicador --upgrade-package o -P :

# only update the django package
$ pip-compile --upgrade-package django

# update both the django and requests packages
$ pip-compile --upgrade-package django --upgrade-package requests

# update the django package to the latest, and requests to v2.0.0
$ pip-compile --upgrade-package django --upgrade-package requests==2.0.0

Puede combinar --upgrade y --upgrade-package en un solo comando para proporcionar restricciones sobre las actualizaciones permitidas. Por ejemplo, para actualizar todos los paquetes y al mismo tiempo restringir las solicitudes a la última versión inferior a 3.0:

$ pip-compile --upgrade --upgrade-package ' requests<3.0 '

Usando hashes

Si desea utilizar el modo de verificación de hash disponible en pip desde la versión 8.0, pip-compile ofrece el indicador --generate-hashes :

$ pip-compile --generate-hashes requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --generate-hashes requirements.in
#
asgiref==3.6.0 
    --hash=sha256:71e68008da809b957b7ee4b43dbccff33d1b23519fb8344e33f049897077afac 
    --hash=sha256:9567dfe7bd8d3c8c892227827c41cce860b368104c3431da67a0c5a65a949506
    # via django
django==4.1.7 
    --hash=sha256:44f714b81c5f190d9d2ddad01a532fe502fa01c4cb8faf1d081f4264ed15dcd8 
    --hash=sha256:f2f431e75adc40039ace496ad3b9f17227022e8b11566f4b363da44c7e44761e
    # via -r requirements.in
sqlparse==0.4.3 
    --hash=sha256:0323c0ec29cd52bceabc1b4d9d579e311f3e4961b98d174201d5622a23b85e34 
    --hash=sha256:69ca804846bb114d2ec380e4360a8a340db83f0ccf3afceeb1404df028f57268
    # via django

Archivo de salida

Para generar los requisitos fijados en un nombre de archivo que no sea requirements.txt , utilice --output-file . Esto podría resultar útil para compilar varios archivos, por ejemplo con diferentes restricciones en Django para probar una biblioteca con ambas versiones usando tox:

$ pip-compile --upgrade-package ' django<1.0 ' --output-file requirements-django0x.txt
$ pip-compile --upgrade-package ' django<2.0 ' --output-file requirements-django1x.txt

O para enviar a la salida estándar, use --output-file=- :

$ pip-compile --output-file=- > requirements.txt
$ pip-compile - --output-file=- < requirements.in > requirements.txt

Opciones de reenvío a pip

Cualquier indicador o argumento pip válido se puede transmitir con la opción --pip-args de pip-compile , por ejemplo

$ pip-compile requirements.in --pip-args " --retries 10 --timeout 30 "

Configuración

Puede definir los valores predeterminados a nivel de proyecto para pip-compile y pip-sync escribiéndolos en un archivo de configuración en el mismo directorio que sus archivos de entrada de requisitos (o el directorio de trabajo actual si canaliza la entrada desde stdin). De forma predeterminada, tanto pip-compile como pip-sync buscarán primero un archivo .pip-tools.toml y luego en su pyproject.toml . También puede especificar un archivo de configuración TOML alternativo con la opción --config .

Es posible especificar valores de configuración tanto globalmente como específicos del comando. Por ejemplo, para generar de forma predeterminada hashes pip en la salida del archivo de requisitos resultante, puede especificar en un archivo de configuración:

[ tool . pip-tools ]
generate-hashes = true

Las opciones para pip-compile y pip-sync que pueden usarse más de una vez deben definirse como listas en un archivo de configuración, incluso si solo tienen un valor.

pip-tools admite valores predeterminados para todos los indicadores de línea de comandos válidos de sus subcomandos. Las claves de configuración pueden contener guiones bajos en lugar de guiones, por lo que lo anterior también podría especificarse en este formato:

[ tool . pip-tools ]
generate_hashes = true

Los valores predeterminados de configuración específicos de pip-compile y pip-sync se pueden colocar en secciones separadas. Por ejemplo, para realizar de forma predeterminada un ensayo con pip-compile :

[ tool . pip-tools . compile ] # "sync" for pip-sync
dry-run = true

Esto no afecta el comando pip-sync , que también tiene una opción --dry-run . Tenga en cuenta que las configuraciones locales tienen preferencia sobre las globales del mismo nombre, siempre que se declaren ambas, por lo que esto también haría que pip-compile genere hashes, pero descartará la configuración global de ejecución en seco:

[ tool . pip-tools ]
generate-hashes = true
dry-run = true

[ tool . pip-tools . compile ]
dry-run = false

Es posible que esté envolviendo el comando pip-compile en otro script. Para evitar confundir a los consumidores de su script personalizado, puede anular el comando de actualización generado en la parte superior de los archivos de requisitos configurando la variable de entorno CUSTOM_COMPILE_COMMAND .

$ CUSTOM_COMPILE_COMMAND= " ./pipcompilewrapper " pip-compile requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    ./pipcompilewrapper
#
asgiref==3.6.0
    # via django
django==4.1.7
    # via -r requirements.in
sqlparse==0.4.3
    # via django

Flujo de trabajo para requisitos en capas

Si tiene diferentes entornos para los que necesita instalar paquetes diferentes pero compatibles, puede crear archivos de requisitos en capas y usar una capa para restringir la otra.

Por ejemplo, si tiene un proyecto de Django en el que desea la versión 2.1 más reciente en producción y durante el desarrollo desea utilizar la barra de herramientas de depuración de Django, entonces puede crear dos archivos *.in , uno para cada capa:

 # requirements.in
django<2.2

En la parte superior de los requisitos de desarrollo dev-requirements.in utiliza -c requirements.txt para restringir los requisitos de desarrollo a los paquetes ya seleccionados para producción en requirements.txt .

 # dev-requirements.in
-c requirements.txt
django-debug-toolbar<2.2

Primero, compila requirements.txt como de costumbre:

 $ pip-compile
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile
#
django==2.1.15
    # via -r requirements.in
pytz==2023.3
    # via django

Ahora compila los requisitos de desarrollo y el archivo requirements.txt se utiliza como restricción:

$ pip-compile dev-requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile dev-requirements.in
#
django==2.1.15
    # via
    #   -c requirements.txt
    #   django-debug-toolbar
django-debug-toolbar==2.1
    # via -r dev-requirements.in
pytz==2023.3
    # via
    #   -c requirements.txt
    #   django
sqlparse==0.4.3
    # via django-debug-toolbar

Como puede ver arriba, aunque hay disponible una versión 2.2 de Django, los requisitos de desarrollo solo incluyen una versión 2.1 de Django porque estaban restringidos. Ahora ambos archivos de requisitos compilados se pueden instalar de forma segura en el entorno de desarrollo.

Para instalar requisitos en el uso de la etapa de producción:

$ pip-sync

Puede instalar requisitos en etapa de desarrollo mediante:

$ pip-sync requirements.txt dev-requirements.txt

Integración del control de versiones

Puede utilizar pip-compile como gancho para la confirmación previa. Consulte los documentos previos a la confirmación para obtener instrucciones. Ejemplo .pre-commit-config.yaml :

 repos :
  - repo : https://github.com/jazzband/pip-tools
    rev : 7.4.1
    hooks :
      - id : pip-compile

Es posible que desee personalizar los argumentos pip-compile configurando args y/o files , por ejemplo:

 repos :
  - repo : https://github.com/jazzband/pip-tools
    rev : 7.4.1
    hooks :
      - id : pip-compile
        files : ^requirements/production.(in|txt)$
        args : [--index-url=https://example.com, requirements/production.in]

Si tiene varios archivos de requisitos, asegúrese de crear un enlace para cada archivo.

 repos :
  - repo : https://github.com/jazzband/pip-tools
    rev : 7.4.1
    hooks :
      - id : pip-compile
        name : pip-compile setup.py
        files : ^(setup.py|requirements.txt)$
      - id : pip-compile
        name : pip-compile requirements-dev.in
        args : [requirements-dev.in]
        files : ^requirements-dev.(in|txt)$
      - id : pip-compile
        name : pip-compile requirements-lint.in
        args : [requirements-lint.in]
        files : ^requirements-lint.(in|txt)$
      - id : pip-compile
        name : pip-compile requirements.in
        args : [requirements.in]
        files : ^requirements.(in|txt)$

Ejemplo de uso para pip-sync

Ahora que tiene un requirements.txt , puede usar pip-sync para actualizar su entorno virtual y reflejar exactamente lo que hay allí. Esto instalará/actualizará/desinstalará todo lo necesario para que coincida con el contenido requirements.txt .

Ejecútelo con pip-sync o python -m piptools sync . Si usa varias versiones de Python, también puede ejecutar py -XY -m piptools sync en Windows y pythonX.Y -m piptools sync en otros sistemas.

pip-sync debe instalarse y ejecutarse desde el mismo entorno virtual que su proyecto para identificar qué paquetes instalar o actualizar.

Tenga cuidado : pip-sync está diseñado para usarse solo con un requirements.txt generado por pip-compile .

$ pip-sync
Uninstalling flake8-2.4.1:
    Successfully uninstalled flake8-2.4.1
Collecting click==4.1
    Downloading click-4.1-py2.py3-none-any.whl (62kB)
    100% |................................| 65kB 1.8MB/s
    Found existing installation: click 4.0
    Uninstalling click-4.0:
        Successfully uninstalled click-4.0
Successfully installed click-4.1

Para sincronizar varias listas de dependencias *.txt , simplemente páselas mediante argumentos de línea de comando, por ejemplo

$ pip-sync dev-requirements.txt requirements.txt

Pasar argumentos vacíos haría que el valor predeterminado sea requirements.txt .

Cualquier indicador o argumento pip install válido se puede pasar con la opción --pip-args de pip-sync , por ejemplo

$ pip-sync requirements.txt --pip-args " --no-cache-dir --no-deps "

Nota : pip-sync no actualizará ni desinstalará herramientas de empaquetado como setuptools , pip o pip-tools . Utilice python -m pip install --upgrade para actualizar esos paquetes.

¿Debo enviar requirements.in y requirements.txt al control de fuente?

Generalmente sí. Si desea una instalación de entorno reproducible disponible desde su control de fuente, entonces sí, debe enviar requirements.in y requirements.txt al control de fuente.

Tenga en cuenta que si está implementando en múltiples entornos Python (lea la sección siguiente), debe enviar un archivo de salida separado para cada entorno Python. Sugerimos utilizar el formato {env}-requirements.txt (por ejemplo: win32-py3.7-requirements.txt , macos-py3.10-requirements.txt , etc.).

Uso entre entornos de requirements.in y pip requirements.txt pip-compile

Las dependencias de un paquete pueden cambiar según el entorno Python en el que esté instalado. Aquí, definimos un entorno Python como la combinación de sistema operativo, versión de Python (3.7, 3.8, etc.) e implementación de Python (CPython, PyPy, etc.). Para una definición exacta, consulte las posibles combinaciones de marcadores ambientales PEP 508.

Como el requirements.txt resultante puede diferir para cada entorno, los usuarios deben ejecutar pip-compile en cada entorno de Python por separado para generar un requirements.txt válido para cada entorno. El mismo requirements.in se puede utilizar como archivo fuente para todos los entornos, utilizando marcadores de entorno PEP 508 según sea necesario, de la misma manera que se haría para el uso normal pip entre entornos.

Si el requirements.txt generado sigue siendo exactamente el mismo para todos los entornos de Python, entonces se puede utilizar en todos los entornos de Python de forma segura. Pero los usuarios deben tener cuidado ya que cualquier actualización de paquete puede introducir dependencias dependientes del entorno, lo que hace que cualquier requirements.txt recién generado también dependa del entorno. Como regla general, se recomienda que los usuarios siempre ejecuten pip-compile en cada entorno Python específico para evitar problemas.

Maximizar la reproducibilidad

pip-tools es una gran herramienta para mejorar la reproducibilidad de las compilaciones. Pero hay algunas cosas a tener en cuenta.

• pip-compile producirá diferentes resultados en diferentes entornos, como se describe en la sección anterior.
• pip debe usarse con la variable de entorno PIP_CONSTRAINT para bloquear dependencias en entornos de compilación como se documenta en el n.° 8439.
• Las dependencias provienen de muchas fuentes.

Continuando con el ejemplo anterior pyproject.toml , se podría crear un único archivo de bloqueo de la siguiente manera:

$ pip-compile --all-build-deps --all-extras --output-file=constraints.txt --strip-extras pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.9
# by the following command:
#
#    pip-compile --all-build-deps --all-extras --output-file=constraints.txt --strip-extras pyproject.toml
#
asgiref==3.5.2
    # via django
attrs==22.1.0
    # via pytest
backports-zoneinfo==0.2.1
    # via django
django==4.1
    # via my-cool-django-app (pyproject.toml)
editables==0.3
    # via hatchling
hatchling==1.11.1
    # via my-cool-django-app (pyproject.toml::build-system.requires)
iniconfig==1.1.1
    # via pytest
packaging==21.3
    # via
    #   hatchling
    #   pytest
pathspec==0.10.2
    # via hatchling
pluggy==1.0.0
    # via
    #   hatchling
    #   pytest
py==1.11.0
    # via pytest
pyparsing==3.0.9
    # via packaging
pytest==7.1.2
    # via my-cool-django-app (pyproject.toml)
sqlparse==0.4.2
    # via django
tomli==2.0.1
    # via
    #   hatchling
    #   pytest

Algunos backends de compilación también pueden solicitar dependencias de compilación dinámicamente utilizando los ganchos get_requires_for_build_ descritos en PEP 517 y PEP 660. Esto se indicará en el resultado con uno de los siguientes sufijos:

• (pyproject.toml::build-system.backend::editable)
• (pyproject.toml::build-system.backend::sdist)
• (pyproject.toml::build-system.backend::wheel)

Otras herramientas útiles

• pip-compile-multi: contenedor de comandos pip-compile para múltiples archivos de requisitos de referencias cruzadas.

• pipdeptree para imprimir el árbol de dependencias de los paquetes instalados.

• requirements.in / requirements.txt resaltado de sintaxis:

  • requisitos.txt.vim para Vim.
  • Extensión de Python para VS Code para VS Code.
  • pip-requirements.el para Emacs.

Depreciaciones

Esta sección enumera las características pip-tools que actualmente están en desuso.

• En la próxima versión principal, el comportamiento --allow-unsafe se habilitará de forma predeterminada (#989). Utilice --no-allow-unsafe para mantener el comportamiento anterior. Se recomienda pasar --allow-unsafe ahora para adaptarse al próximo cambio.
• El solucionador heredado está obsoleto y se eliminará en versiones futuras. El nuevo valor predeterminado es --resolver=backtracking .
• En la próxima versión principal, el comportamiento --strip-extras se habilitará de forma predeterminada (#1613). Utilice --no-strip-extras para mantener el comportamiento anterior.

Una nota sobre los solucionadores

Puede elegir entre el solucionador de seguimiento predeterminado o el solucionador heredado obsoleto.

En ocasiones, el solucionador heredado no podrá resolver las dependencias. El solucionador de retroceso es más robusto, pero en general puede tardar más en ejecutarse.

Puede continuar usando el solucionador heredado con --resolver=legacy aunque tenga en cuenta que está obsoleto y se eliminará en una versión futura.