4. Tworzenie dystrybucji źródłowej

Informacja

Ten dokument jest przechowywany wyłącznie do czasu, gdy dokumentacja setuptools pod adresem https://setuptools.readthedocs.io/en/latest/setuptools.html niezależnie obejmie wszystkie istotne informacje, które są tutaj zawarte.

Jak pokazano w rozdziale Prosty przykład, używasz polecenia sdist aby utworzyć dystrybucję źródłową. W najprostszym przypadku,

python setup.py sdist

(zakładając że nie ustaliłeś żadnych opcji polecenia sdist`w skrypcie instalacyjnym lub pliku konfiguracyjnym), polecenie :command:`sdist tworzy archiwum domyślnego formatu dla danej maszyny/środowiska. Domyślnym formatem jest zgzipowany plik tar (.tar.gz) na Unixie i plik ZIP na Windows.

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

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

aby utworzyć zgzipowany tarball i plik zip. Dostępne formaty to:

Format	Opis	Notatki
zip	plik zip (.zip)	(1),(3)
gztar	zgzipowany plik tar (.tar.gz)	(2)
bztar	zbzip2owany plik tar (.tar.bz2)	(5)
xztar	xz’ed tar file (.tar.xz)	(5)
ztar	skompresowany plik tar (.tar.Z)	(4),(5)
tar	plik tar (.tar)	(5)

Zmienione w wersji 3.5: Added support for the xztar format.

Uwagi:

1. domyślne dla Windows

2. domyślne dla Unix

3. wymaga zewnętrznego programu użytkowego zip lub modułu zipfile (części standardowej biblioteki języka pytonowskiego od wersji 1.6 języka pytonowskiego)

4. wymaga programu kompresji compress. Zauważ że ten format oczekuje teraz na przedawnienie i zostanie zdjęty w przyszłych wersjach języka pytonowskiego.

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.

Dla przykładu, gdy chcesz aby wszystkie pliki archiwum były posiadane przez roota:

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

4.1. Określanie plików do rozprowadzenia

Jeśli nie dostarczasz jawnej listy plików (lub instrukcji jak ją wygenerować), polecenie sdist wkłada minimalny zbiór domyślny w dystrybucję źródeł:

• all Python source files implied by the py_modules and packages options

• all C source files mentioned in the ext_modules or libraries options

• scripts identified by the scripts option See Instalowanie skryptów.

• cokolwiek co wygląda jak skrypt testujący: plik test/test*.py (obecnie Distutils nie robi nic ze skryptami testowymi z wyjątkiem załączania ich w dystrybucji źródeł, ale w przyszłości będzie standard dla testowania dystrybucji modułów języka pytonowskiego)

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

• wszystkie pliki które odpowiadają danym-o-danych package_data. Zobacz Instalowanie danych pakietu.

• wszystkie pliki które odpowiadają danym-o-danych data_files. Zobacz Instalowanie dodatkowych plików.

Czasem to jest wystarczające, ale zwykle potrzebujesz określić dodatkowe pliki do rozprowadzenia. Typowym sposobem robienia tego jest napisanie wzoru manifestu - z ang. - manifest template zwanego MANIFEST.in domyślnie. Wzór manifestu jest po prostu listą instrukcji na to jak wygenerować plik manifestu, MANIFEST, który jest dokładnie listą plików do włączenia w twoją dystrybucję źródłową. Polecenie sdist przetwarza ten wzorzec i wytwarza manifest w oparciu o jego instrukcje i to, co znajdzie w systemie plików.

Jeśli wolisz napisać swój własny plik manifestu, format jest prosty: jedna nazwa pliku na linię, jedynie pliki zwyczajne (lub symboliczne odwołania do nich). Jeżeli dostarczysz swój własny plik MANIFEST, musisz określić wszystko: domyślny zbiór plików opisujących powyższe nie odnosi się do tego przypadku.

Zmienione w wersji 3.1: An existing generated MANIFEST will be regenerated without sdist comparing its modification time to the one of MANIFEST.in or setup.py.

Zmienione w wersji 3.1.3: MANIFEST files start with a comment indicating they are generated. Files without this comment are not overwritten or removed.

Zmienione w wersji 3.2.2: sdist will read a MANIFEST file if no MANIFEST.in exists, like it used to do.

Zmienione w wersji 3.7: README.rst is now included in the list of distutils standard READMEs.

The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils» own manifest template:

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 Creating a source distribution: the sdist command.

Kolejność poleceń we wzorze manifestu ma znaczenie: początkowo, mamy listę domyślnych plików, jak opisano powyżej, i każde polecenie we wzorze dodaje lub zdejmuje z tej listy plików. Gdy mamy całkowicie przetworzony wzór manifestu, usuwamy pliki, które nie powinny znajdować się w dystrybucji źródłowej:

• wszystkie pliki w drzewie budowania Distutils (domyślne build/)

• wszystkie pliki w katalogach nazwanych RCS, CVS, .svn, .hg, .git, .bzr or _darcs

Teraz mamy naszą pełną listę plików, które są zapisane w manifeście dla przyszłego odniesienia, i potem używane do budowania archiwum(ów) źródłowych dystrybucji.

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.

Podążając za wzorem manifestu własnego Distutils, prześledźmy jak polecenie sdist buduje listę plików do załączenia w źródłowej dystrybucji Distutils:

1. include all Python source files in the distutils and distutils/command subdirectories (because packages corresponding to those two directories were mentioned in the packages option in the setup script—see section Pisanie Skryptu Instalacyjnego)

2. include README.txt, setup.py, and setup.cfg (standardowe pliki)

3. include test/test*.py (standardowe pliki)

4. załącz pliki *.txt w nadrzędnym katalogu dystrybucji (to odnajdzie plik README.txt po raz drugi, ale takie nadmiarowości są odchwaszczane później)

5. załącz cokolwiek pasującego do wzoru *.txt lub *.py w poddrzewie pod examples,

6. wyłącz wszystkie pliki w poddrzewach pasujące do examples/sample?/build— to może wyłączyć pliki załączone w poprzednich dwóch krokach, więc istotne jest aby polecenie prune we wzorcu manifestu następowało po poleceniu recursive-include

7. wyłącz całe drzewo build, i wszystkie katalogi RCS CVS, .svn, .hg, .git, .bzr i _darcs

Tak jak w skrypcie instalacyjnym, nazwy plików i katalogów we wzorcu manifestu powinny zawsze być separowane-ukośnikiem; Distutils zajmie się zamianą ich na standardową postać na twojej maszynie/środowisku. W ten sposób, wzór manifestu jest przenośny pomiędzy systemami operacyjnymi.

4.2. Związane-z-Manifestem opcje

Normalny kurs operacji polecenia sdist jest następujący:

• 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

• Jeśli żaden z plików MANIFEST ani MANIFEST.in nie istnieją, stwórz manifest tylko z domyślnym zestawem plików

• użyj listy plików teraz znajdujących się w pliku MANIFEST (albo dopiero co wygenerowanych albo wczytanych) do utworzenia archiwum(/ów) dystrybucji źródłowej

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.

Po drugie możesz po prostu chcieć wygenerować (powtórnie) manifest, ale nie tworzyć dystrybucji źródłowej:

python setup.py sdist --manifest-only

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