4. Criando uma Distribuição Fonte

Nota

Este documento está sendo mantido apenas até que a documentação do setuptools em https://setuptools.readthedocs.io/en/latest/setuptools.html cubra independentemente todas as informações relevantes atualmente incluídas aqui.

Conforme mostrado na seção Um Exemplo Simples, você usa o comando sdist para criar uma distribuição fonte. No caso mais simples,

python setup.py sdist

(assuming you haven’t specified any sdist options in the setup script or config file), sdist creates the archive of the default format for the current platform. The default format is a gzip’ed tar file (.tar.gz) on Unix, and ZIP file on Windows.

You can specify as many formats as you like using the --formats option, for example:

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

to create a gzipped tarball and a zip file. The available formats are:

Formatação	Descrição	Notas
zip	arquivo zip (.zip)	(1),(3)
gztar	gzip’ed tar file (.tar.gz)	(2)
bztar	bzip2’ed tar file (.tar.bz2)	(5)
xztar	xz’ed tar file (.tar.xz)	(5)
ztar	compressed tar file (.tar.Z)	(4),(5)
tar	arquivo tar (.tar)	(5)

Alterado na versão 3.5: Added support for the xztar format.

Notas:

1. default on Windows

2. default on Unix

3. requires either external zip utility or zipfile module (part of the standard Python library since Python 1.6)

4. requires the compress program. Notice that this format is now pending for deprecation and will be removed in the future versions of Python.

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

When using any tar format (gztar, bztar, xztar, ztar or tar), under Unix you can specify the owner and group names that will be set for each member of the archive.

For example, if you want all files of the archive to be owned by root:

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

4.1. Specifying the files to distribute

Se você não fornecer uma lista explícita de arquivos (ou instruções sobre como gerá-la), o comando sdist coloca um conjunto padrão mínimo na distribuição fonte:

• todos os arquivos fonte Python implícitos nas opções py_modules e packages

• todos os arquivos fonte C mencionados nas opções ext_modules ou libraries

• scripts identified by the scripts option See Installing Scripts.

• qualquer coisa que se pareça com um script de teste: test/test*.py (atualmente, os Distutils não fazem nada com scripts de teste, exceto incluí-los em distribuições fonte, mas no futuro haverá um padrão para teste de distribuições de módulo Python)

• Any of the standard README files (README, README.txt, or README.rst), setup.py (or whatever you called your setup script), and setup.cfg.

• all files that matches the package_data metadata. See Installing Package Data.

• all files that matches the data_files metadata. See Installing Additional Files.

Às vezes, isso é suficiente, mas normalmente você deseja especificar arquivos adicionais para distribuir. A maneira típica de fazer isso é escrever um modelo de manifesto, chamado MANIFEST.in por padrão. O modelo de manifesto é apenas uma lista de instruções sobre como gerar seu arquivo de manifesto, MANIFEST, que é a lista exata de arquivos a serem incluídos em sua distribuição fonte. O comando sdist processa este modelo e gera um manifesto baseado em suas instruções e no que ele encontra no sistema de arquivos.

If you prefer to roll your own manifest file, the format is simple: one filename per line, regular files (or symlinks to them) only. If you do supply your own MANIFEST, you must specify everything: the default set of files described above does not apply in this case.

Alterado na versão 3.1: An existing generated MANIFEST will be regenerated without sdist comparing its modification time to the one of MANIFEST.in or setup.py.

Alterado na versão 3.1.3: MANIFEST files start with a comment indicating they are generated. Files without this comment are not overwritten or removed.

Alterado na versão 3.2.2: sdist will read a MANIFEST file if no MANIFEST.in exists, like it used to do.

Alterado na versão 3.7: README.rst is now included in the list of distutils standard READMEs.

O modelo de manifesto tem um comando por linha, onde cada comando especifica um conjunto de arquivos para incluir ou excluir da distribuição fonte. Por exemplo, voltamos novamente para o próprio modelo de manifesto do Distutils:

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

The meanings should be fairly clear: include all files in the distribution root matching *.txt, all files anywhere under the examples directory matching *.txt or *.py, and exclude all directories matching examples/sample?/build. All of this is done after the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the --no-defaults option to disable the standard set entirely.) There are several other commands available in the manifest template mini-language; see section Criando uma distribuição de fontes: o comando sdist.

A ordem dos comandos no modelo de manifesto é importante: inicialmente, temos a lista de arquivos padrão conforme descrito acima, e cada comando no modelo adiciona ou remove dessa lista de arquivos. Depois de processarmos totalmente o modelo de manifesto, removemos os arquivos que não devem ser incluídos na distribuição fonte:

• all files in the Distutils “build” tree (default build/)

• all files in directories named RCS, CVS, .svn, .hg, .git, .bzr or _darcs

Agora temos nossa lista completa de arquivos, que é gravada no manifesto para referência futura e usada para construir o(s) arquivo(s) de distribuição fonte.

You can disable the default set of included files with the --no-defaults option, and you can disable the standard exclude set with --no-prune.

Seguindo o modelo de manifesto do próprio Distutils, vamos rastrear como o comando sdist constrói a lista de arquivos a serem incluídos na distribuição fonte Distutils:

1. inclua todos os arquivos fonte Python nos subdiretórios distutils e distutils/command (porque os pacotes correspondentes a esses dois diretórios foram mencionados na opção packages no script de configuração – consulte a seção Escrevendo o Script de Configuração)

2. include README.txt, setup.py, and setup.cfg (standard files)

3. include test/test*.py (standard files)

4. include *.txt in the distribution root (this will find README.txt a second time, but such redundancies are weeded out later)

5. include anything matching *.txt or *.py in the sub-tree under examples,

6. exclude all files in the sub-trees starting at directories matching examples/sample?/build—this may exclude files included by the previous two steps, so it’s important that the prune command in the manifest template comes after the recursive-include command

7. exclude the entire build tree, and any RCS, CVS, .svn, .hg, .git, .bzr and _darcs directories

Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems.

4.2. Manifest-related options

The normal course of operations for the sdist command is as follows:

• if the manifest file (MANIFEST by default) exists and the first line does not have a comment indicating it is generated from MANIFEST.in, then it is used as is, unaltered

• if the manifest file doesn’t exist or has been previously automatically generated, read MANIFEST.in and create the manifest

• if neither MANIFEST nor MANIFEST.in exist, create a manifest with just the default file set

• use the list of files now in MANIFEST (either just generated or read in) to create the source distribution archive(s)

There are a couple of options that modify this behaviour. First, use the --no-defaults and --no-prune to disable the standard “include” and “exclude” sets.

Second, you might just want to (re)generate the manifest, but not create a source distribution:

python setup.py sdist --manifest-only

-o is a shortcut for --manifest-only.