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    | (2)           |
|             | con gzip (".tar.gz")      |               |
+-------------+---------------------------+---------------+
| "bztar"     | archivo tar comprimido    | (5)           |
|             | con bzip2 (".tar.bz2")    |               |
+-------------+---------------------------+---------------+
| "xztar"     | archivo tar comprimido    | (5)           |
|             | con xz (".tar.xz")        |               |
+-------------+---------------------------+---------------+
| "ztar"      | archivo tar comprimido    | (4),(5)       |
|             | (".tar.Z")                |               |
+-------------+---------------------------+---------------+
| "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".
