1. Wprowadzenie do Distutils

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.

Ten dokument opisuje użycie Distutils do dystrybucji twoich modułów języka pytonowskiego koncentrując się na roli twórcy/dystrybutora: jeśli szukasz informacji o instalowaniu modułów języka pytonowskiego powinieneś odwołać się do rozdziału Installing Python Modules (Legacy version).

1.1. Pojęcia i Terminy

Użycie Distutils jest całkiem proste, zarówno dla twórców modułów jak i dla użytkowników/administratorów instalujących moduły ze strony osób trzecich. Jako twórca, twoim zadaniem (poza pisaniem porządnego, dobrze udokumentowanego i dobrze przetestowanego kodu, rzecz jasna!) są:

• napisanie skryptu instalacyjnego (pliku setup.py - zgodnie ze zwyczajem)

• (opcjonalnie) napisanie pliku konfiguracji instalacji

• utworzenie dystrybucji źródłowej

• (nadobowiązkowe) stworzyć jedną lub więcej zbudowaną (binarną) dystrybucję

Każde z tych zadań jest opisane w tym dokumencie.

Nie wszyscy twórcy mają dostęp do wielu maszyn/środowisk, więc nie zawsze rozsądne jest oczekiwanie od nich tworzenia wielu zbudowanych dystrybucji. Jest oczekiwane że pewien zbiór pośredników, zwanych pakowaczami, powstanie aby zaradzić tym potrzebom. Pakowacze biorą dystrybucje źródłowe wypuszczonych przez twórców modułów, budują je na jednej lub większej liczbie maszyn/środowisk, i wypuszczają wynikłe zbudowane dystrybucje. Zatem, użytkownicy większości popularnych platform będą w stanie instalować większość popularnych dystrybucji modułów języka pytonowskiego w najbardziej naturalny sposób dla ich maszyn/środowisk, bez konieczności uruchomienia nawet jednego skryptu instalacyjnego ani kompilowania ani jednej linijki kodu.

1.2. Prosty przykład

Skrypt instalacyjny jest zwykle raczej prosty, chociaż od kiedy jest pisany w języku pytonowskim, nie ma odgórnych granic co można z nim zrobić, chociaż powinieneś być ostrożny w umieszczaniu dowolnie kosztownych operacji w swoim skrypcie instalacyjnym. W przeciwieństwie do dajmy na to skryptów konfiguracyjnych w stylu Autoconf-a, skrypt instalacyjny może być uruchamiany kilka razy w trakcie budowania i instalowania twojej dystrybucji modułu.

Jeśli wszystkim czego chcesz dokonać jest dystrybuowanie modułu nazwanego foo zawartego w pliku foo.py wtedy twój plik skryptu instalacyjnego może być tak prosty jak:

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

Pewne obserwacje

• większość informacji które dostarczasz do Distutils jest podawana jako parametry słów kluczowych do zadania setup().

• te parametry słów kluczowych należą do dwóch kategorii: informacje o danych pakietu (- z ang. - metadata) (nazwa, numer wersji) i informacja o tym co jest w pakiecie (lista czysto pytonowskich modułów, w tym przypadku)

• moduły są określone przez nazwę modułu nie nazwę pliku (to samo odnosi się do pakietów i rozszerzeń)

• polecane jest abyś dostarczył nieco więcej informacji o danych, w szczególności swoje imię, adres email i URL projektu (sięgnij do rozdziału Pisanie Skryptu Instalacyjnego po przykład)

To create a source distribution for this module, you would create a setup script, setup.py, containing the above code, and run this command from a terminal:

python setup.py sdist

For Windows, open a command prompt window (Start ‣ Accessories) and change the command to:

setup.py sdist

sdist will create an archive file (e.g., tarball on Unix, ZIP file on Windows) containing your setup script setup.py, and your module foo.py. The archive file will be named foo-1.0.tar.gz (or .zip), and will unpack into a directory foo-1.0.

If an end-user wishes to install your foo module, all they have to do is download foo-1.0.tar.gz (or .zip), unpack it, and—from the foo-1.0 directory—run

python setup.py install

które ostatecznie kopiują plik foo.py do odpowiedniego katalogu dla modułów pochodzących od osób trzecich w ich instalacji języka pytonowskiego.

Ten prosty przykład demonstruje pewne podstawowe pojęcia Distutils. Po pierwsze zarówno twórcy modułów jak i instalujący je mają ten sam podstawowy sprzęg użytkownika tj. skrypt instalacyjny. Różnica polega na tym, którego polecenia ( - z ang. - command ) Distutils używają: polecenie sdist jest prawie wyłącznie dla twórców modułów, podczas gdy install jest częściej dla instalujących (chociaż większość twórców też będzie chciała zainstalować swój własny kod czasami).

Jeśli chcesz uczynić rzeczy naprawdę łatwymi dla swoich użytkowników, możesz stworzyć jedną lub więcej zbudowaną dystrybucję dla nich. Na przykład, jeśli działasz na komputerze z Windows, i chcesz uczynić rzeczy łatwymi dla innych użytkowników Windowsa, możesz utworzyć wykonywalny instalator (najbardziej odpowiedni typ zbudowanej dystrybucji dla tej maszyny/środowiska) z poleceniem bdist_wininst. Na przykład:

python setup.py bdist_wininst

utworzy wykonywalny instalator, foo-1.0.win32.exe, w bierzącym katalogu.

Inne użyteczne formaty dystrybucji to RPMy, wypełnione przez polecenie bdist_rpm, program pkgtootl Solarisa (bdist_pkgtool), i program swinstall` dla HP-UX (bdist_sdux). Na przykład, następujące polecenie utworzy plik RPM nazwany foo-1.0.noarch.rpm:

python setup.py bdist_rpm

(Polecenie bdist_rpm używa polecenia wykonywalnego rpm, zatem musi to być uruchamiane na opartym o RPMy systemie takim jak Linux Red Hat, Linux SuSE, lub Linux Mandrake.)

Możesz dowiedzieć się o tym które formaty dystrybucji są dostępne w każdej chwili uruchamiając:

python setup.py bdist --help-formats

1.3. Ogólne terminy języka pytonowskiego

Jeśli czytasz ten dokument, pewnie masz dobre pojęcie czym są moduły, rozszerzenia, itd. itp. Tym nie mniej, aby się upewnić że wszyscy operują ze wspólnego punktu początkowego, oferujemy następujący słowniczek wspólnych terminów języka pytonowskiego:

module

podstawowa miara powtórnej użyteczności kodu w języku pytonowskim: blok kodu zaimportowany przez inny kod. Trzy typy modułów interesują nas tutaj: moduły czysto pytonowskie, moduły rozszerzające, i pakiety.

pure Python module

a module written in Python and contained in a single .py file (and possibly associated .pyc files). Sometimes referred to as a „pure module.”

moduł rozszerzenia

moduł napisany w niskopoziomowym języku wypełnienia języka pytonowskiego: C/C++ dla języka pytonowskiego, Java dla języka Jytonowskiego. Typowo zawarty w pojedynczym dynamicznie ładowalnym uprzednio skompilowanym pliku, np. plik współdzielonych obiektów (- z ang. shared object - w skrócie so - .so) dla rozszerzeń języka pytonowskiego dla Unix, i DLL (mając dane rozszerzenie .pyd) dla rozszerzeń języka pytonowskiego na Windowsie, lub plik uogólnienia Javy dla języka rozszerzeń języka jytonowskiego. (Zauważ, że obecnie, Distutils obsługuje tylko rozszerzenia C/C++ dla języka pytonowskiego.)

package

moduł który zawiera inne moduły; typowo przechowywany w katalogu w systemie plików i rozróżniany od innych katalogów przez obecność pliku __init__.py.

root package

Korzeń hierarchii pakietów. (To nie jest właściwie pakiet, gdyż nie ma pliku __init__.py. Ale musimy jakoś go nazwać.) Znaczna większość standardowej biblioteki jest w pakiecie korzenia, tak jak wiele małych, samodzielnych modułów osób-trzecich, które nie pasują do większej kolekcji modułów. W przeciwieństwie do typowych pakietów, moduły w pakiecie korzenia można znaleźć w wielu katalogach: w rzeczywistości, każdy katalog wypisany w sys.path dokłada moduły do pakietu korzenia.

1.4. Terminologia szczególna dla Distutils

Następujące terminy odnoszą się bardziej szczególnie do domeny dystrybucji modułów pytonowskich przy użyciu Distutils:

module distribution

a collection of Python modules distributed together as a single downloadable resource and meant to be installed en masse. Examples of some well-known module distributions are NumPy, SciPy, Pillow, or mxBase. (This would be called a package, except that term is already taken in the Python context: a single module distribution may contain zero, one, or many Python packages.)

pure module distribution

dystrybucja modułów która zawiera tylko czysto pytonowskie moduły i pakiety. Czasami określana mianem „czystej dystrybucji.”

non-pure module distribution

dystrybucja modułu która zawiera przynajmniej jeden moduł rozszerzeń. Czasami określana jako „nie-czysta dystrybucja.”

distribution root

Nadrzędnego poziomu katalog twojego drzewa źródeł (inaczej dystrybucji źródeł); katalog w którym plik setup.py jest umieszczony. Ogólnie plik setup.py będzie uruchomiony z tego katalogu.