Aprenda sobre la construcción de un paquete de Python#

Image showing the progression of creating a Python package, building it and then publishing to PyPI and conda-forge. You take your code and turn it into distribution files (sdist and wheel) that PyPI accepts. Then there is an arrow towards the PyPI repository where ou publish both distributions. From PyPI if you create a conda-forge recipe you can then publish to conda-forge.

Once you have published both package distributions (the source distribution and the wheel) to PyPI, you can then publish to conda-forge. The conda-forge requires an source distribution on PyPI in order to build your package on conda-forge. You do not need to rebuild your package to publish to conda-forge.#

Necesita construir su paquete de Python para publicarlo en PyPI (o en un canal de conda). El proceso de construcción organiza su código y metadatos en un formato de distribución que puede ser subido a PyPI y posteriormente descargado e instalado por los usuarios. NOTA: necesita publicar un sdist (distribución del código fuente) en PyPI para que conda-forge pueda construir su paquete automáticamente.

¿Qué es construir un paquete de Python?#

Para publicar su paquete de Python y hacer que sea fácil de instalar para cualquiera, primero necesita construirlo.

Pero, ¿qué significa construir un paquete de Python?

Como se muestra en la figura de arriba, cuando construye su paquete de Python, convierte los archivos de código fuente en algo llamado paquete de distribución. Un paquete de distribución contiene su código fuente y metadatos sobre el paquete, en el formato requerido por el Python Package Index (PyPI), para que pueda ser instalado por herramientas como pip.

Nota

El término paquete solía significar muchas cosas diferentes en Python y otros lenguajes. En esta página, adaptamos la convención de la Autoridad de Empaquetado de Python y nos referimos al producto del paso de construcción como un paquete de distribución.

Este proceso de organizar y formatear su código, documentación, pruebas y metadatos en un formato que tanto pip como PyPI pueden usar, se llama paso de construcción.

Metadatos del proyecto y PyPI#

Los metadatos que tanto las herramientas de construcción como PyPI utilizan para describir y entender su paquete generalmente se almacenan en un archivo pyproject.toml. Estos metadatos se utilizan para varios propósitos:

  1. Ayuda a la herramienta que use para construir su paquete (pip, Build de pypa o una herramienta de extremo a extremo como poetry, PDM o Hatch) a entender cómo construir su paquete. La información que proporciona a su herramienta de construcción incluye:

  • La tabla [build-system] en su archivo pyproject.toml le dice a pip qué herramienta de backend de construcción desea usar para crear sus distribuciones sdist (distribución del código fuente) y wheel (distribución construida).

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

  • Y la sección de dependencias de su tabla de proyecto le dice a la herramienta de construcción y a PyPI qué dependencias requiere su proyecto.

dependencies = [
    "numpy",
    "geopandas",
]

  1. Cuando la herramienta de construcción crea el archivo de distribución de su paquete (el archivo que publica en PyPI), también crea un archivo METADATA que PyPI puede leer y usar para ayudar a los usuarios a encontrar su paquete. Por ejemplo:

  • The classifiers = section of your [project] table in the pyproject.toml file provides information that users on PyPI can use to filter for packages that address different topics or that support specific versions of python.

classifiers = [
    # How mature is this project? Common values are
    "Development Status :: 4 - Beta",

    # Indicate who your project is intended for
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Build Tools",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]

¿Qué pasó con setup.py y setup.cfg para almacenar metadatos?

Los metadatos del proyecto solían almacenarse en un archivo setup.py o en un archivo setup.cfg. La práctica recomendada actual para almacenar metadatos de paquetes es utilizar un archivo pyproject.toml. Aprenda más sobre el archivo pyproject.toml aquí.

Un ejemplo - xclim#

When you publish to PyPI, you will notice that each package has metadata listed. Let’s have a look at xclim, one of our pyOpenSci packages. Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim’s maintainers, pyproject.toml file. This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website.

Imagen que muestra la barra lateral izquierda de PyPI para el paquete xclim. La sección en la parte superior dice Clasificador. Debajo hay una lista de elementos que incluyen: estado de desarrollo, audiencia prevista, licencia, idioma natural, sistema operativo, lenguaje de programación y tema. Debajo de cada una de esas secciones hay varias opciones de clasificación." width="300px">

Cuando agregue la sección de clasificación a su pyproject.toml y se construya su paquete, la herramienta de construcción organiza los metadatos en un formato que PyPI puede entender y representar en la página de inicio de PyPI. Estos clasificadores también permiten a los usuarios ordenar los paquetes por la versión de Python que admiten, categorías y más.#

Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. An arrow to the right takes you to a build distribution files box. That box leads you to either publishing to TestPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge.

Necesita construir su paquete de Python para publicarlo en PyPI (o Conda). El proceso de construcción organiza su código y metadatos en un formato de distribución que puede ser subido a PyPI y posteriormente descargado e instalado por los usuarios. NOTA: necesita publicar distribución del código fuente (sdist) en PyPI para que conda-forge pueda construir su paquete automáticamente.#

This screenshot shows the metadata on PyPI for the xclim package. On it you can see the name of the license, the author and maintainer names keywords associated with the package and the base python version it requires which is 3.8.

Captura de pantalla de PyPI que muestra metadatos para el paquete xclim.#

Here you see the maintainer metadata as it is displayed on PyPI. For xclim there are three maintainers listed with their profile pictures and github user names to the right.

Nombres de los mantenedores y nombres de usuario de GitHub para el paquete xclim tal como se muestran en PyPI. Esta información se registra en su pyproject.toml y luego es procesada por su herramienta de construcción y almacenada en las distribuciones sdist y wheel de sus paquetes.#

¿Cómo crear el formato de distribución que PyPI y Pip esperan?#

En teoría, podría crear sus propios scripts para organizar su código de la manera que PyPI quiere que sea. Sin embargo, al igual que hay paquetes que manejan estructuras conocidas como dataframes de Pandas y arrays de Numpy, hay paquetes y herramientas que le ayudan a crear archivos de distribución de construcción de paquetes.

Nota

Existen una serie de herramientas de empaquetado que pueden ayudarle con todo el proceso de empaquetado o solo con un paso del proceso. Por ejemplo, setuptools es un backend de construcción comúnmente utilizado que se puede usar para crear su sdist y wheel. Mientras que herramientas como Hatch, PDM, Poetry y flit ayudan con otras partes del proceso de empaquetado.

Si bien esto puede causar cierta confusión y complejidad en el ecosistema de empaquetado, en su mayor parte, cada herramienta proporciona la misma salida de distribución (con diferencias menores que a la mayoría de los usuarios pueden no importarles). Aprenda más sobre esas herramientas en esta página.

A continuación, aprenderá sobre los dos archivos de distribución que PyPI espera que publique: sdist y wheel. Aprenderá sobre su estructura y qué archivos pertenecen a cada uno.

Hay dos archivos de distribución principales que necesita crear para publicar su paquete de Python en PyPI: la distribución de origen (a menudo llamada sdist) y la distribución construida (wheel). El sdist contiene el código fuente sin procesar de su paquete. La wheel (.whl) contiene los archivos construidos / compilados que se pueden instalar directamente en el ordenador de cualquier persona.

Aprenda más sobre ambas distribuciones a continuación.

Nota

Si su paquete es un paquete de Python puro sin pasos adicionales de construcción / compilación, entonces las distribuciones sdist y wheel tendrán contenido similar. Sin embargo, si su paquete tiene extensiones en otros lenguajes o es más complejo en su construcción, las dos distribuciones serán muy diferentes.

Also note that we are not discussing conda build workflows in this section. You can learn more about conda builds here.

What is a source distribution (sdist)#

Los archivos de código fuente son los archivos sin construir necesarios para construir su paquete. Estos son los archivos «originales / sin procesar» que almacena en GitHub o en cualquier plataforma que utilice para gestionar su código.

Las distribuciones de código fuente (del inglés, source distribution) se denominan sdist. Como su nombre indica, una distribución sdist contiene el código fuente; no ha sido construido ni compilado de ninguna manera. Por lo tanto, cuando un usuario instala su distribución de código fuente usando pip, pip necesita ejecutar un paso de construcción primero. Por esta razón, podría definir una distribución sdist como un archivo comprimido que contiene todo lo necesario para construir una wheel (excepto las dependencias del proyecto) sin acceso a la red.

Normalmente, sdist se almacena como un archivo .tar.gz (a menudo llamado un «tarball»). Por lo tanto, cuando un usuario instala su distribución de origen usando pip, pip necesita ejecutar un paso de construcción primero.

A continuación se muestra un ejemplo de sdist para el paquete de Python stravalib:

stravalib-1.1.0.post2-SDist.tar.gz file contents

├─ 📂 stravalib
│  ├─ tests
│  │  ├─ integration
│  │  │  ├─ __init__.py
│  │  │  ├─ conftest.py
│  │  │  ├─ strava_api_stub.py
│  │  │  └─ test_client.py
│  │  ├─ unit
│  │  │  ├─ __init__.py
│  │  │  ├─ test_attributes.py
│  │  │  ├─ ...
│  │  ├─ __init__.py
│  │  ├─ auth_responder.py
│  │  └─ test.ini-example
│  ├─ util
│  │  ├─ __init__.py
│  │  └─ limiter.py
│  ├─ __init__.py
│  ├─ _version.py
│  ├─ _version_generated.py
│  ├─ attributes.py
│  ├─ ...
├─ stravalib.egg-info
│  ├─ PKG-INFO
│  ├─ SOURCES.txt
│  ├─ dependency_links.txt
│  ├─ requires.txt
│  └─ top_level.txt
├─ CODE_OF_CONDUCT.md
├─ CONTRIBUTING.md
├─ LICENSE.txt
├─ MANIFEST.in
├─ Makefile
├─ PKG-INFO
├─ README.md
├─ CHANGELOG.md
├─ environment.yml
├─ pyproject.toml
├─ requirements-build.txt
├─ requirements.txt
└─ setup.cfg

El archivo de GitHub vs sdist

Cuando se crea una versión en GitHub, se crea un git archive que contiene todos los archivos de su repositorio de GitHub. Si bien estos archivos son similares a un sdist, estos dos archivos no son iguales. El sdist contiene algunos otros elementos, incluido un directorio de metadatos y si utiliza setuptools_scm o hatch_vcs, el sdist también puede contener un archivo que almacena la versión.

What is a Python wheel (whl):#

Un archivo wheel es un archivo en formato ZIP cuyo nombre sigue un formato específico (a continuación) y tiene la extensión .whl. El archivo .whl contiene un conjunto específico de archivos, incluidos metadatos que se generan a partir del archivo pyproject.toml de su proyecto. El pyproject.toml y otros archivos que pueden estar incluidos en las distribuciones de origen no se incluyen en las wheels porque es una distribución construida.

La wheel (.whl) es su distribución binaria construida. Los archivos binarios son los archivos de código fuente construidos / compilados. Estos archivos están listos para ser instalados. Una wheel (.whl) es un archivo zip que contiene todos los archivos necesarios para instalar directamente su paquete. Todos los archivos en una wheel son binarios, lo que significa que el código ya está compilado / construido. Por lo tanto, estas son más rápidas de instalar, particularmente si tiene un paquete que requiere pasos de construcción.

La wheel no contiene ninguno de los archivos de configuración de su paquete como setup.cfg o pyproject.toml. Esta distribución ya está construida por lo que está lista para instalar.

Debido a que está construido, el archivo .whl será más rápido de instalar para proyectos de Python puro y llevará a instalaciones consistentes

Truco

Las wheels también son útiles en el caso de que un paquete necesite un archivo setup.py para admitir una construcción más compleja. En este caso, debido a que los archivos en el paquete de wheel están preconstruidos, el usuario que lo instala no tiene que preocuparse por inyecciones de código malicioso cuando se instala.

El nombre de archivo de una wheel contiene metadatos importantes sobre su paquete.

Por ejemplo: stravalib-1.1.0.post2-py3-none.whl

  • nombre: stravalib

  • versión: 1.1.0

  • número de construcción: 2 (post2) (lea más sobre post aquí)

  • py3: admite Python 3.x

  • none: no es específico del sistema operativo (se ejecuta en Windows, Mac, Linux)

  • any: se ejecuta en cualquier procesador / arquitectura de ordenador

¿Cómo se ve un archivo de rueda cuando se desempaqueta (descomprime)?

stravalib-1.1.0.post2-py3-none.whl file contents:

├─ 📂 stravalib
│  ├─ tests
│  │  ├─ functional
│  │  │  ├─ __init__.py
│  │  │  ├─ test_client.py
│  │  ├─ unit
│  │  │  ├─ __init__.py
│  │  │  ├─ test_attributes.py
│  │  ├─ __init__.py
│  │  ├─ auth_responder.py
│  │  └─ test.ini-example
│  ├─ util
│  │  ├─ __init__.py
│  │  └─ limiter.py
│  ├─ __init__.py
│  ├─ _version.py
│  ├─ _version_generated.py
│  ├─ attributes.py
│  ├─ client.py
└─ stravalib-1.1.0.post2.dist-info  # Package metadata are stored here
   ├─ LICENSE.txt
   ├─ METADATA
   ├─ RECORD
   ├─ WHEEL
   └─ top_level.txt

Truco

Lea más sobre el formato de rueda aquí