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

Nota

Este documento se mantiene ú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 actualmente incluida 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. deprecado por PEP 527; PyPI solo acepta archivos `.zip` y `.tar.gz`.

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 `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`.