4. Crear una distribución del código fuente

Nota

Este documento se conserva únicamente hasta que la documentación de setuptools en https://setuptools.readthedocs.io/en/latest/setuptools.html cubra de forma independiente toda la información relevante que se incluye actualmente aquí.

Como se muestra en la sección Un ejemplo simple, use el comando sdist para crear una distribución de código fuente. En el caso más simple,

python setup.py sdist

(suponiendo que no ha especificado ninguna opción sdist en el script de configuración o en el archivo de configuración), sdist crea el archivo con el formato predeterminado para la plataforma actual.El formato predeterminado es un archivo tar comprimido con gzip (.tar.gz) en Unix, y el archivo ZIP en Windows.

Puede especificar tantos formatos como desee usando la opción --formats, por ejemplo:

python setup.py sdist --formats=gztar,zip

para crear un tarball comprimido y un archivo zip. Los formatos disponibles son:

Formato	Descripción	Notas
zip	archivo zip (.zip)	(1),(3)
gztar	archivo tar comprimido con gzip (.tar.gz)	(2)
bztar	archivo tar comprimido con bzip2 (.tar.bz2)	(5)
xztar	archivo tar comprimido con xz (.tar.xz)	(5)
ztar	archivo tar comprimido (.tar.Z)	(4),(5)
tar	archivo tar (.tar)	(5)

Distinto en la versión 3.5: Soporte agregado para el formato xztar.

Notas:

1. por defecto en Windows

2. por defecto en Unix

3. se requiere o bien un programa externo zip o el módulo zipfile (parte del estándar de la biblioteca de Python desde Python 1.6)

4. requiere el programa compress. Tenga en cuenta que ahora este formato está deprecado y será eliminado en las futuras versiones de Python.

5. deprecated by PEP 527; PyPI only accepts .zip and .tar.gz files.

Al usar cualquier formato tar (gztar, bztar, xztar, ztar o tar), en Unix se puede especificar el nombre del propietario y grupo que se establecerá para cada uno de los miembros del archivo.

Por ejemplo, si quiere que todos los archivos pertenezcan al usuario root:

python setup.py sdist --owner=root --group=root

4.1. Especificar los archivos a distribuir

Si no se proporciona una lista explícita de los archivos (o instrucciones sobre cómo generar uno), el comando sdist pone un conjunto mínimo por defecto en la distribución de código fuente:

• todos los archivos de código fuente de Python implícitos por las opciones py_modules y packages

• todos los archivos de código fuente de C mencionados en las opciones ext_modules o libraries

• scripts identificados por la opción scripts Ver Instalar scripts.

• cualquier archivo que parezca un script de pruebas: test/test*.py (actualmente, Distutils no hace nada con scripts de prueba, solo los incluye en la distribución, pero en el futuro habrá un estándar para realizar pruebas de los módulos de Python en las distribuciones)

• Cualquiera de los archivos estándar LÉAME (README, README.txt, o README.rst), setup.py (o cualquier nombre que le haya puesto al script de configuración), y setup.cfg.

• todos los archivos que coincidan con los metadatos package_data. Vea Instalar datos del paquete.

• todos los archivos que coincidan con los metadatos data_files. Vea Instalar archivos adicionales.

A veces esto es suficiente, pero por lo general, va a querer especificar archivos adicionales a distribuir. La forma típica de hacer esto es escribir una plantilla de manifiesto, por defecto con el nombre MANIFEST.in. La plantilla de manifiesto es sólo una lista de instrucciones para generar el archivo de manifiesto, MANIFEST, el cual es la lista exacta de archivos a incluir en la distribución de código fuente. El comando sdist procesa esta plantilla y genera un manifiesto basado en las instrucciones y en lo que encuentra en el sistema de ficheros.

Si prefiere crear su propio archivo de manifiesto, el formato es simple: un nombre de archivo por línea, solamente archivos normales (o enlaces simbólicos a ellos). Si hace su propio MANIFEST, debe especificar todo: el conjunto predeterminado de los archivos descritos más arriba no se aplica en este caso.

Distinto en la versión 3.1: Un MANIFEST ya existente y generado, será regenerado sin sdist comparando su tiempo de modificación con el de MANIFEST.in o setup.py.

Distinto en la versión 3.1.3: MANIFEST los archivos comienzan con un comentario indicando que son generados. Los archivos que no tengan este comentario no se sobrescriben ni eliminan.

Distinto en la versión 3.2.2: sdist leerá un archivo MANIFEST si no existe el archivo MANIFEST.in, como solía hacer.

Distinto en la versión 3.7: README.rst ahora está incluido en la lista de LEAMEs estándar de distutils.

La plantilla de manifiesto tiene un comando por línea, donde cada comando especifica un conjunto de archivos para incluir o excluir de la distribución de código fuente. Para un ejemplo, de nuevo nos dirigimos a la Distutils la propia plantilla de manifiesto:

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

Los significados debe ser bastante claros: incluya todos los archivos en la raíz de la distribución, que coincidan con *.txt, todos los archivos dentro del directorio examples que coincidan con *.txt o *.py, y excluir todos los directorios que coincidan con examples/sample?/build. Todo esto se hace después de seguir el conjunto estándar de inclusión, por lo que puede excluir archivos del conjunto establecido con instrucciones explícitas en la plantilla del manifiesto. (O bien, puede utilizar la opción --no-defaults para desactivar el conjunto estándar completo.) Hay varios otros comandos disponibles en el mini-lenguaje de la plantilla de manifiesto; vea la sección Creando una distribución de origen: el comando sdist.

El orden de los comandos en la plantilla de manifiesto es importante: inicialmente, tenemos la lista de archivos predeterminados como se describió anteriormente, y cada comando en la plantilla agrega o elimina de esa lista de archivos. Una vez que hemos procesado completamente la plantilla del manifiesto, eliminamos los archivos que no deberían incluirse en la distribución del código fuente:

• todos los archivos en el árbol «build» de Distutils (por defecto build/)

• todos los archivos en directorios nombrados RCS, CVS, .svn, .hg, .git, .bzr o _darcs

Ahora tenemos la lista completa de archivos, que está escrita en el manifiesto para una futura referencia, y luego se utilizará para construir los archivos de distribución de código fuente.

Puede deshabilitar el conjunto predeterminado de archivos incluidos con la opción --no-defaults, y puede deshabilitar el conjunto de exclusión estándar con --no-prune.

Siguiendo la propia plantilla de manifiesto de Distutils, rastreemos cómo el comando sdist crea la lista de archivos para incluir en la distribución fuente de Distutils:

1. incluir todos los archivos fuente de Python en los sub-directorios distutils y distutils/command (porque los paquetes correspondientes a esos dos directorios se mencionaron en la opción packages en el script de configuración —vea la sección Escribir el script de configuración)

2. incluir:file:README.txt, setup.py, y setup.cfg (archivos estándar)

3. incluir test/test*.py (archivos estándar)

4. incluir *.txt en la raíz de la distribución(esto encontrará README.txt por segunda vez, pero tales redundancias se eliminan más tarde)

5. incluir cualquier archivo que coincida con *.txt or *.py en el subárbol dentro de examples,

6. excluir todos los archivos en los subárboles que comiencen en los directorios que coincidan con examples/sample?/build—esto puede excluir los archivos incluidos en los dos pasos anteriores, por lo que es importante que el comando prune en la plantilla de manifiesto vaya después del comando recursive-include

7. excluir todo el árbol build y cualquier directorio RCS, CVS, .svn, .hg, .git, .bzr y _darcs

Al igual que en el script de configuración, los nombres de archivos y directorios en la plantilla de manifiesto siempre deben estar separados por barras; Distutils se encargará de convertirlos a la representación estándar en su plataforma. De esa manera, la plantilla de manifiesto es portable en todos los sistemas operativos.

4.2. Opciones relacionadas con el manifesto

El curso normal de operaciones para el comando sdist es el siguiente:

• si el archivo de manifiesto (MANIFEST por defecto) existe y la primera línea no tiene un comentario que indique que se genera a partir de MANIFEST.in, entonces se usa como está, sin alteraciones

• si el archivo de manifiesto no existe o si se ha generado previamente de forma automática, lea MANIFEST.in y cree el manifiesto

• si no existe MANIFEST ni MANIFEST.in, cree un manifiesto solamente con el conjunto de archivos predeterminado

• use la lista de archivos, que ahora están en MANIFEST (ya sea generado o leído) para crear los archivos de distribución de código fuente

Existen un par de opciones que modifican este comportamiento. Primero, use --no-defaults y --no-prune para desactivar los conjuntos estándar «include» y «exclude».

Segundo, quizá quiera (re)generar el manifesto, pero no crear la distribución del código fuente:

python setup.py sdist --manifest-only

-o es una forma corta de --manifest-only.