Встановлення модулів Python (застаріла версія)

Автор:

Greg Ward

Примітка

Весь пакет distutils застарів і буде видалено в Python 3.12. Ця документація зберігається лише як довідка та буде видалена разом із пакетом. Перегляньте запис Що нового для отримання додаткової інформації.

Дивись також

Встановлення модулів Python

Актуальна документація по установці модуля. Для регулярного використання Python вам майже напевно потрібен цей документ, а не цей.

Примітка

Цей документ зберігається лише до тих пір, поки документація setuptools за адресою https://setuptools.readthedocs.io/en/latest/setuptools.html окремо не охопить всю відповідну інформацію, яка зараз включена тут.

Примітка

Цей посібник охоплює лише основні інструменти для створення та розповсюдження розширень, які надаються як частина цієї версії Python. Інструменти сторонніх розробників пропонують прості у використанні та безпечніші альтернативи. Для отримання додаткової інформації зверніться до розділу швидких рекомендацій у посібнику користувача з пакування Python.

вступ

У Python 2.0 API distutils було вперше додано до стандартної бібліотеки. Це забезпечило розробникам дистрибутивів Linux стандартний спосіб перетворення проектів Python у пакети дистрибутивів Linux, а системним адміністраторам — стандартний спосіб встановлення їх безпосередньо на цільових системах.

За багато років після випуску Python 2.0 тісно зв’язати систему збірки та інсталятор пакунків із циклом випуску середовища виконання мови виявилося проблематично, і тепер рекомендовано, щоб проекти використовували інсталятор пакетів pip і setuptools будує систему, а не використовує distutils безпосередньо.

Перегляньте Встановлення модулів Python і Розповсюдження модулів Python для отримання додаткової інформації.

Ця застаріла документація зберігається лише до тих пір, поки ми не будемо впевнені, що документація setuptools охоплює все необхідне.

Розповсюдження джерел на основі Distutils

If you download a module source distribution, you can tell pretty quickly if it was packaged and distributed in the standard way, i.e. using the Distutils. First, the distribution’s name and version number will be featured prominently in the name of the downloaded archive, e.g. foo-1.0.tar.gz or widget-0.9.7.zip. Next, the archive will unpack into a similarly named directory: foo-1.0 or widget-0.9.7. Additionally, the distribution will contain a setup script setup.py, and a file named README.txt or possibly just README, which should explain that building and installing the module distribution is a simple matter of running one command from a terminal:

python setup.py install

Для Windows цю команду слід запускати з вікна командного рядка (Пуск ‣ Аксесуари):

setup.py install

Якщо все це правда, то ви вже знаєте, як створити та встановити модулі, які щойно завантажили: виконайте наведену вище команду. Якщо вам не потрібно встановлювати щось нестандартним способом або налаштовувати процес збірки, цей посібник вам не потрібен. Або, точніше, наведена вище команда - це все, що вам потрібно, щоб вийти з цього посібника.

Стандартна збірка та встановлення

Як описано в розділі Розповсюдження джерел на основі Distutils, створення та встановлення дистрибутива модуля за допомогою Distutils зазвичай виконується однією простою командою з терміналу:

python setup.py install

Варіації платформи

Завжди слід запускати команду налаштування з кореневого каталогу розповсюдження, тобто підкаталогу верхнього рівня, куди розпаковується дистрибутив джерела модуля. Наприклад, якщо ви щойно завантажили дистрибутив вихідного коду модуля foo-1.0.tar.gz на систему Unix, звичайною справою є:

gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install

У Windows ви, ймовірно, завантажите foo-1.0.zip. Якщо ви завантажили архівний файл до C:\Temp, він буде розпакований у C:\Temp\foo-1.0; ви можете використовувати маніпулятор архіву з графічним інтерфейсом користувача (наприклад, WinZip) або інструмент командного рядка (наприклад, unzip або pkunzip), щоб розпакувати архів. Потім відкрийте вікно командного рядка та запустіть:

cd c:\Temp\foo-1.0
python setup.py install

Розподіл роботи

Запуск setup.py install збирає та встановлює всі модулі за один запуск. Якщо ви віддаєте перевагу працювати поступово — особливо корисно, якщо ви хочете налаштувати процес збирання, або якщо щось йде не так — ви можете використовувати сценарій налаштування, щоб виконувати одну дію за раз. Це особливо корисно, коли збирання та встановлення виконуватимуться різними користувачами — наприклад, ви можете створити дистрибутив модуля та передати його системному адміністратору для встановлення (або зробити це самостійно, з правами суперкористувача ).

Наприклад, ви можете створити все за один крок, а потім інсталювати все за другий крок, двічі викликавши сценарій встановлення:

python setup.py build
python setup.py install

Якщо ви це зробите, ви помітите, що виконання команди install спочатку запускає команду build, яка — в цьому випадку — швидко помічає, що вона не має нічого робити, оскільки все у каталозі build є актуальною.

Можливо, вам не знадобиться ця здатність часто розбивати речі, якщо все, що ви робите, це встановлювати модулі, завантажені з мережі, але це дуже зручно для більш складних завдань. Якщо ви починаєте розповсюджувати свої власні модулі та розширення Python, ви запускатимете багато окремих команд Distutils окремо.

Як працює будівництво

Як було зазначено вище, команда build відповідає за розміщення файлів для встановлення в каталог збірки. За замовчуванням це build у корені розповсюдження; якщо ви надмірно стурбовані швидкістю або хочете зберегти вихідне дерево незайманим, ви можете змінити каталог збірки за допомогою опції --build-base. Наприклад:

python setup.py build --build-base=/path/to/pybuild/foo-1.0

(Або ви можете зробити це назавжди за допомогою директиви у вашій системі чи особистому конфігураційному файлі Distutils; див. розділ Файли конфігурації Distutils.) Зазвичай це не обов’язково.

Типовий макет дерева побудови такий:

--- build/ --- lib/
or
--- build/ --- lib.<plat>/
               temp.<plat>/

де <plat> розширюється до короткого опису поточної ОС/апаратної платформи та версії Python. Перша форма, лише з каталогом lib, використовується для «дистрибутивів чистих модулів» — тобто дистрибутивів модулів, які містять лише чисті модулі Python. Якщо розповсюдження модуля містить будь-які розширення (модулі, написані мовою C/C++), то використовується друга форма з двома каталогами <plat>. У цьому випадку каталог temp.plat містить тимчасові файли, згенеровані процесом компіляції/посилання, які фактично не встановлюються. У будь-якому випадку каталог lib (або lib.plat) містить усі модулі Python (чистий Python і розширення), які буде встановлено.

У майбутньому буде додано більше каталогів для обробки сценаріїв Python, документації, двійкових виконуваних файлів і всього іншого, що буде потрібно для роботи зі встановлення модулів і програм Python.

Як працює установка

Після виконання команди build (незалежно від того, запускаєте ви її явно чи команда install робить це за вас), робота команди install відносно проста: усе, що вона має це скопіювати все в build/lib (або build/lib.plat) до вибраного каталогу встановлення.

Якщо ви не виберете каталог інсталяції — тобто якщо ви просто запустите setup.py install— тоді команда install встановить стандартне розташування для сторонніх модулів Python . Це розташування залежить від платформи та способу створення/встановлення самого Python. В Unix (і macOS, яка також базується на Unix), це також залежить від того, чи інстальований дистрибутив модуля є чистим Python чи містить розширення («нечисті»):

Платформа	Стандартне місце установки	Значення за замовчуванням	Примітки
Unix (чистий)	префікс/lib/pythonX.Y/site-packages	/usr/local/lib/pythonX.Y/site-packages	(1)
Unix (не чистий)	exec-prefix/lib/pythonX.Y/site-packages	/usr/local/lib/pythonX.Y/site-packages	(1)
вікна	prefix\Lib\site-packages	C:\PythonXY\Lib\site-packages	(2)

Примітки:

1. Більшість дистрибутивів Linux включають Python як стандартну частину системи, тому prefix і exec-prefix зазвичай обидва є /usr в Linux. Якщо ви самостійно створюєте Python на Linux (або будь-якій Unix-подібній системі), типовими prefix і exec-prefix є /usr/local.

2. Стандартним каталогом інсталяції в Windows був C:\Program Files\Python у Python 1.6a1, 1.5.2 і попередніх версіях.

prefix і exec-prefix означають каталоги, у які встановлено Python, і де він знаходить свої бібліотеки під час виконання. Вони завжди однакові під Windows і дуже часто однакові під Unix і macOS. Ви можете дізнатися, що ваша інсталяція Python використовує для prefix і exec-prefix, запустивши Python в інтерактивному режимі та ввівши кілька простих команд. В Unix просто введіть python у командному рядку оболонки. У Windows виберіть Пуск ‣ Програми ‣ Python X.Y ‣ Python (командний рядок). Після запуску інтерпретатора ви вводите код Python у запиті. Наприклад, у моїй системі Linux я вводжу три оператори Python, показані нижче, і отримую результат, як показано, щоб дізнатися мої prefix і exec-prefix:

Python 2.4 (#26, Aug  7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'

У цьому документі використовується кілька інших заповнювачів: X.Y означає версію Python, наприклад 3.2; abiflags буде замінено на значення sys.abiflags або порожній рядок для платформ, які не визначають прапори ABI; distname буде замінено назвою дистрибутива модуля, який встановлюється. Крапки та великі літери важливі в шляхах; наприклад, значення, яке використовує python3.2 в UNIX, зазвичай використовуватиме Python32 у Windows.

Якщо ви не бажаєте встановлювати модулі у стандартне розташування або якщо у вас немає дозволу на запис у цьому місці, вам потрібно прочитати про альтернативні встановлення в розділі Альтернативна інсталяція. Якщо ви бажаєте суттєвіше налаштувати ваші каталоги встановлення, див. розділ Вибіркова установка про нестандартне встановлення.

Альтернативна інсталяція

Часто необхідно або бажано встановити модулі в інше місце, ніж стандартне розташування для сторонніх модулів Python. Наприклад, у системі Unix ви можете не мати дозволу на запис у стандартний каталог сторонніх модулів. Або ви можете спробувати модуль перед тим, як зробити його стандартною частиною локальної інсталяції Python. Це особливо актуально під час оновлення наявного дистрибутива: ви хочете переконатися, що ваша існуюча база сценаріїв все ще працює з новою версією, перш ніж фактично оновлювати.

Команда Distutils install призначена для простого та безболісного встановлення дистрибутивів модулів до альтернативного розташування. Основна ідея полягає в тому, що ви вказуєте базовий каталог для інсталяції, а команда install вибирає набір каталогів (званий схемою інсталяції) у цьому базовому каталозі, у який потрібно інсталювати файли. Деталі відрізняються для різних платформ, тому прочитайте той із наступних розділів, який вам підходить.

Зауважте, що різні альтернативні схеми встановлення є взаємовиключними: ви можете передати --user, --home, --prefix і --exec-prefix, або --install-base і --install-platbase, але ви не можете змішувати ці групи.

Альтернативна установка: схема користувача

Ця схема розроблена як найзручніше рішення для користувачів, які не мають дозволу на запис до глобального каталогу пакетів сайтів або не хочуть встановлювати в нього. Це вмикається простим параметром:

python setup.py install --user

Files will be installed into subdirectories of site.USER_BASE (written as userbase hereafter). This scheme installs pure Python modules and extension modules in the same location (also known as site.USER_SITE). Here are the values for UNIX, including macOS:

Тип файлу	Каталог встановлення
модулі	userbase/lib/pythonX.Y/site-packages
сценарії	userbase/bin
даних	userbase
C заголовки	userbase/include/pythonX.Yabiflags/distname

А ось значення, які використовуються в Windows:

Тип файлу	Каталог встановлення
модулі	userbase\PythonXY\site-packages
сценарії	userbase\PythonXY\Сценарії
даних	userbase
C заголовки	userbase\PythonXY\Include{distname}

Перевага використання цієї схеми порівняно з іншими, описаними нижче, полягає в тому, що каталог пакетів сайту користувача за звичайних умов завжди включається в sys.path (див. site для отримання додаткової інформації), що означає, що після запуску сценарію setup.py для завершення встановлення не потрібно виконувати жодних додаткових кроків.

Команда build_ext також має опцію --user, щоб додати userbase/include до шляху пошуку компілятора для файлів заголовків і userbase/lib до шляху пошуку компілятора для бібліотек, а також до шляху пошуку під час виконання для спільних бібліотек C (rpath).

Альтернативна установка: домашня схема

Ідея «домашньої схеми» полягає в тому, що ви створюєте та підтримуєте особистий запас модулів Python. Назва цієї схеми походить від ідеї «домашнього» каталогу в Unix, оскільки для користувачів Unix не є незвичайним зробити свій домашній каталог макетом, подібним до /usr/ або /usr /локальний/. Цю схему може використовувати будь-хто, незалежно від операційної системи, для якої він встановлюється.

Встановити новий дистрибутив модуля так само просто, як:

python setup.py install --home=<dir>

де ви можете вказати будь-який каталог для опції --home. В Unix ліниві друкарки можуть просто ввести тильду (~); команда install розширить це до вашого домашнього каталогу:

python setup.py install --home=~

To make Python find the distributions installed with this scheme, you may have to modify Python’s search path or edit sitecustomize (see site) to call site.addsitedir() or edit sys.path.

Параметр --home визначає базовий каталог встановлення. Файли встановлюються в такі каталоги в базі інсталяції наступним чином:

Тип файлу	Каталог встановлення
модулі	home/lib/python
сценарії	home/bin
даних	home
C заголовки	home/include/python/distname

(Подумки замініть скісні риски на зворотні скісні риски, якщо ви використовуєте Windows.)

Альтернативна інсталяція: Unix (префіксна схема)

«Схема префіксів» корисна, коли ви бажаєте використовувати одну інсталяцію Python для виконання побудови/інсталяції (тобто для запуску сценарію інсталяції), але інсталювати модулі в каталог модулів сторонніх розробників іншої інсталяції Python (або щось, що виглядає як інша інсталяція Python). Якщо це звучить трішки незвично, це—тому користувальницька та домашня схеми стоять раніше. Однак є принаймні два відомі випадки, коли префіксна схема буде корисною.

По-перше, врахуйте, що багато дистрибутивів Linux розміщують Python у /usr, а не в більш традиційному /usr/local. Це цілком доречно, оскільки в таких випадках Python є частиною «системи», а не локальним додатком. Однак, якщо ви встановлюєте модулі Python із джерела, ви, ймовірно, хочете, щоб вони містилися в /usr/local/lib/python2.X, а не в /usr/lib/python2.X . Це можна зробити за допомогою

/usr/bin/python setup.py install --prefix=/usr/local

Іншою можливістю є мережева файлова система, де ім’я, що використовується для запису у віддалений каталог, відрізняється від імені, яке використовується для його читання: наприклад, інтерпретатор Python, доступ до якого здійснюється як /usr/local/bin/python, може шукати модулі в /usr/local/lib/python2.X, але ці модулі мають бути встановлені, скажімо, у /mnt/@server/export/lib/python2. X. Це можна зробити за допомогою

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export

У будь-якому випадку параметр --prefix визначає базу інсталяції, а параметр --exec-prefix визначає базу інсталяції для певної платформи, яка використовується для файлів певної платформи. . (Наразі це означає лише розповсюдження нечистих модулів, але може бути розширено до бібліотек C, двійкових виконуваних файлів тощо.) Якщо --exec-prefix не вказано, за умовчанням буде --префікс. Файли встановлюються наступним чином:

Тип файлу	Каталог встановлення
Модулі Python	префікс/lib/pythonX.Y/site-packages
модулі розширення	exec-prefix/lib/pythonX.Y/site-packages
сценарії	prefix/bin
даних	prefix
C заголовки	префікс/include/pythonX.Yabiflags/distname

Немає вимоги, щоб --prefix або --exec-prefix справді вказували на альтернативну установку Python; якщо перелічені вище каталоги ще не існують, вони створюються під час встановлення.

До речі, справжня причина важливості схеми префіксів полягає просто в тому, що стандартна інсталяція Unix використовує схему префіксів, але з --prefix і --exec-prefix, що надаються самим Python як sys.prefix і sys.exec_prefix. Таким чином, ви можете подумати, що ніколи не використовуватимете схему префіксів, але кожного разу, коли ви запускаєте python setup.py install без будь-яких інших параметрів, ви використовуєте її.

Зауважте, що встановлення розширень до альтернативної інсталяції Python не впливає на те, як створено ці розширення: зокрема, файли заголовків Python (Python.h і друзі), встановлені за допомогою інтерпретатора Python, який використовується для запуску сценарію налаштування, будуть використовувати для компіляції розширень. Ви несете відповідальність за те, щоб інтерпретатор, який використовується для запуску встановлених таким чином розширень, був сумісний з інтерпретатором, який використовується для їх створення. Найкращий спосіб зробити це — переконатися, що два інтерпретатори є однаковою версією Python (можливо, різними збірками або, можливо, копіями однієї збірки). (Звичайно, якщо ваші --prefix і --exec-prefix навіть не вказують на альтернативну інсталяцію Python, це не має значення.)

Альтернативна установка: Windows (префіксна схема)

Windows не має концепції домашнього каталогу користувача, і оскільки стандартна інсталяція Python у Windows є простішою, ніж у Unix, опція --prefix традиційно використовується для інсталяції додаткових пакетів в окремих місцях у Windows.

python setup.py install --prefix="\Temp\Python"

для встановлення модулів у каталог \Temp\Python на поточному диску.

База встановлення визначається параметром --prefix; параметр --exec-prefix не підтримується в Windows, що означає, що чисті модулі Python і модулі розширення встановлені в одному місці. Файли встановлюються наступним чином:

Тип файлу	Каталог встановлення
модулі	prefix\Lib\site-packages
сценарії	prefix\Сценарії
даних	prefix
C заголовки	prefix\Включити{distname}

Вибіркова установка

Іноді альтернативні схеми встановлення, описані в розділі Альтернативна інсталяція, просто не роблять того, що ви хочете. Можливо, ви захочете налаштувати лише один або два каталоги, зберігаючи все в одному базовому каталозі, або ви можете повністю перевизначити схему встановлення. У будь-якому випадку ви створюєте спеціальну схему встановлення.

Щоб створити спеціальну схему встановлення, ви починаєте з однієї з альтернативних схем і замінюєте деякі каталоги встановлення, які використовуються для різних типів файлів, використовуючи ці параметри:

Тип файлу	Опція перевизначення
Модулі Python	--install-purelib
модулі розширення	--install-platlib
всі модулі	--install-lib
сценарії	--install-scripts
даних	--install-data
C заголовки	--install-headers

Ці параметри заміни можуть бути відносними, абсолютними або явно визначеними в термінах одного з базових каталогів встановлення. (Існує два базові каталоги встановлення, і зазвичай вони однакові — вони відрізняються лише тоді, коли ви використовуєте «префіксну схему» Unix і надаєте різні параметри --prefix і --exec-prefix ; використання --install-lib замінить значення, обчислені або надані для --install-purelib і --install-platlib, і рекомендовано для схем, які не мають значення між Python і модулями розширення.)

Наприклад, скажімо, ви встановлюєте дистрибутив модуля у свій домашній каталог під Unix — але ви хочете, щоб сценарії містилися в ~/scripts, а не в ~/bin. Як і слід було очікувати, ви можете замінити цей каталог опцією --install-scripts; у цьому випадку має сенс надати відносний шлях, який інтерпретуватиметься відносно основного каталогу інсталяції (у цьому випадку вашого домашнього каталогу):

python setup.py install --home=~ --install-scripts=scripts

Інший приклад Unix: припустімо, що вашу інсталяцію Python було зібрано та встановлено з префіксом /usr/local/python, тому за стандартної інсталяції сценарії з’являться у /usr/local/python/bin. Якщо ви хочете, щоб вони були в /usr/local/bin замість цього, ви повинні вказати цей абсолютний каталог для параметра --install-scripts:

python setup.py install --install-scripts=/usr/local/bin

(Це виконує інсталяцію за допомогою «схеми префіксів», де префіксом є те, що було встановлено вашим інтерпретатором Python — /usr/local/python у цьому випадку.)

Якщо ви підтримуєте Python у Windows, можливо, ви захочете, щоб модулі сторонніх розробників знаходилися в підкаталозі prefix, а не безпосередньо в prefix. Це майже так само просто, як налаштувати каталог встановлення сценарію — вам потрібно лише пам’ятати, що є два типи модулів, про які варто турбуватися, Python і модулі розширення, якими зручно керувати одним параметром:

python setup.py install --install-lib=Site

Указаний каталог встановлення відноситься до prefix. Звичайно, ви також повинні переконатися, що цей каталог знаходиться в шляху пошуку модуля Python, наприклад, помістивши файл .pth в каталог сайту (див. site). Перегляньте розділ Зміна шляху пошуку Python, щоб дізнатися, як змінити шлях пошуку Python.

Якщо ви бажаєте визначити повну схему встановлення, вам просто потрібно вказати всі параметри каталогу встановлення. Рекомендований спосіб зробити це — надати відносні шляхи; наприклад, якщо ви хочете підтримувати всі файли, пов’язані з модулями Python, у python у вашому домашньому каталозі, і вам потрібен окремий каталог для кожної платформи, з якої ви використовуєте свій домашній каталог, ви можете визначити наступну схему встановлення

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data

або, еквівалентно,

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data

$PLAT не є (обов’язково) змінною середовища — вона буде розширена за допомогою Distutils під час аналізу ваших параметрів командного рядка, так само, як це робиться під час аналізу ваших конфігураційних файлів.

Очевидно, що вказувати всю схему встановлення кожного разу, коли ви встановлюєте новий дистрибутив модуля, було б дуже виснажливо. Таким чином, ви можете розмістити ці параметри у вашому конфігураційному файлі Distutils (див. розділ Файли конфігурації Distutils):

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data

або, те саме,

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data

Зауважте, що ці два не еквівалентні, якщо ви вказуєте інший базовий каталог встановлення під час запуску сценарію налаштування. Наприклад,

python setup.py install --install-base=/tmp

встановить чисті модулі до /tmp/python/lib у першому випадку та до /tmp/lib у другому випадку. (Для другого випадку ви, ймовірно, захочете надати базу встановлення /tmp/python.)

Можливо, ви помітили використання $HOME і $PLAT у зразку вхідних даних файлу конфігурації. Це змінні конфігурації Distutils, які дуже схожі на змінні середовища. Фактично, ви можете використовувати змінні середовища у файлах конфігурації на платформах, які мають таке поняття, але Distutils додатково визначає кілька додаткових змінних, яких може не бути у вашому середовищі, наприклад $PLAT. (Звичайно, у системах, які не мають змінних середовища, наприклад Mac OS 9, змінні конфігурації, надані Distutils, є єдиними, які ви можете використовувати.) Перегляньте розділ Файли конфігурації Distutils для деталі.

Примітка

Коли активовано віртуальне середовище, будь-які параметри, які змінюють шлях інсталяції, ігноруватимуться в усіх конфігураційних файлах distutils, щоб запобігти випадковому встановленню проектів за межами віртуального середовища.

Зміна шляху пошуку Python

Коли інтерпретатор Python виконує оператор import, він шукає як код Python, так і модулі розширення вздовж шляху пошуку. Значення за замовчуванням для шляху налаштовується у двійковий файл Python під час створення інтерпретатора. Ви можете визначити шлях, імпортувавши модуль sys і надрукувавши значення sys.path.

$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>

Нульовий рядок у sys.path представляє поточний робочий каталог.

Очікувана умова для локально встановлених пакунків полягає в тому, щоб розмістити їх у каталозі .../site-packages/, але ви можете встановити модулі Python у будь-який довільний каталог. Наприклад, ваш сайт може зберігати все програмне забезпечення, пов’язане з веб-сервером, у /www. Додаткові модулі Python можуть належати до /www/python, і щоб імпортувати їх, цей каталог потрібно додати до sys.path. Є кілька різних способів додати каталог.

Найзручніший спосіб — додати файл конфігурації шляху до каталогу, який уже є на шляху Python, зазвичай до каталогу .../site-packages/. Файли конфігурації шляху мають розширення .pth, і кожен рядок має містити один шлях, який буде додано до sys.path. (Оскільки нові шляхи додаються до sys.path, модулі в доданих каталогах не замінять стандартні модулі. Це означає, що ви не можете використовувати цей механізм для встановлення фіксованих версій стандартних модулів.)

Шляхи можуть бути абсолютними або відносними, і в цьому випадку вони відносяться до каталогу, що містить файл .pth. Дивіться документацію модуля site для отримання додаткової інформації.

Трохи менш зручний спосіб – редагувати файл site.py у стандартній бібліотеці Python і змінити sys.path. site.py автоматично імпортується під час виконання інтерпретатора Python, якщо не встановлено перемикач -S для придушення такої поведінки. Тож ви можете просто відредагувати site.py і додати до нього два рядки:

import sys
sys.path.append('/www/python/')

However, if you reinstall the same minor version of Python (perhaps when upgrading from 2.2 to 2.2.2, for example) site.py will be overwritten by the stock version. You’d have to remember that it was modified and save a copy before doing the installation.

Є дві змінні середовища, які можуть змінювати sys.path. PYTHONHOME встановлює альтернативне значення для префікса встановлення Python. Наприклад, якщо PYTHONHOME встановлено на /www/python, шлях пошуку буде встановлено на ['', '/www/python/lib/pythonX.Y/', ' /www/python/lib/pythonX.Y/plat-linux2', ...].

Для змінної PYTHONPATH можна встановити список шляхів, які будуть додані на початок sys.path. Наприклад, якщо для PYTHONPATH встановлено значення /www/python:/opt/py, шлях пошуку починатиметься з ['/www/python', '/opt/py']. (Зауважте, що каталоги мають існувати, щоб їх можна було додати до sys.path; модуль site видаляє шляхи, яких не існує.)

Нарешті, sys.path — це звичайний список Python, тому будь-яка програма Python може змінити його, додаючи або видаляючи записи.

Файли конфігурації Distutils

Як згадувалося вище, ви можете використовувати конфігураційні файли Distutils для запису особистих налаштувань або параметрів сайту для будь-яких параметрів Distutils. Тобто будь-яку опцію будь-якої команди можна зберегти в одному з двох або трьох (залежно від вашої платформи) конфігураційних файлів, які будуть перевірені перед аналізом командного рядка. Це означає, що файли конфігурації замінять значення за замовчуванням, а командний рядок, у свою чергу, замінить файли конфігурації. Крім того, якщо застосовуються кілька файлів конфігурації, значення з «попередніх» файлів замінюються «пізнішими».

Розташування та назви конфігураційних файлів

Імена та розташування конфігураційних файлів дещо відрізняються на різних платформах. В Unix і macOS три файли конфігурації (у порядку їх обробки):

Тип файлу	Розташування та назва файлу	Примітки
система	prefix/lib/pythonver/distutils/distutils.cfg	(1)
особистий	$HOME/.pydistutils.cfg	(2)
місцевий	setup.cfg	(3)

А в Windows конфігураційні файли:

Тип файлу	Розташування та назва файлу	Примітки
система	prefix\Lib\distutils\distutils.cfg	(4)
особистий	%HOME%\pydistutils.cfg	(5)
місцевий	setup.cfg	(3)

On all platforms, the «personal» file can be temporarily disabled by passing the --no-user-cfg option.

Примітки:

1. Власне кажучи, загальносистемний файл конфігурації знаходиться в каталозі, де встановлено Distutils; під Python 1.6 і пізніше в Unix, це як показано. Для Python 1.5.2 Distutils зазвичай встановлюється в prefix/lib/python1.5/site-packages/distutils, тому файл конфігурації системи слід розміщувати туди під Python 1.5.2.

2. On Unix, if the HOME environment variable is not defined, the user’s home directory will be determined with the getpwuid() function from the standard pwd module. This is done by the os.path.expanduser() function used by Distutils.

3. Тобто в поточному каталозі (зазвичай місце розташування сценарію налаштування).

4. (Див. також примітку (1).) У Python 1.6 і пізніших версіях стандартним «префіксом встановлення» Python є C:\Python, тому файл конфігурації системи зазвичай має вигляд C:\PythonLib\distutils\distutils.cfg. У Python 1.5.2 префікс за замовчуванням був C:\Program Files\Python, а Distutils не були частиною стандартної бібліотеки — тому файл конфігурації системи мав би виглядати як C :\Program Files\Python\distutils\distutils.cfg у стандартній установці Python 1.5.2 під Windows.

5. У Windows, якщо змінна середовища HOME не визначена, USERPROFILE, то HOMEDRIVE і HOMEPATH будуть спробовані. Це робиться за допомогою функції os.path.expanduser(), яку використовує Distutils.

Синтаксис конфігураційних файлів

Усі конфігураційні файли Distutils мають однаковий синтаксис. Файли конфігурації згруповані в розділи. Існує один розділ для кожної команди Distutils, а також розділ global для глобальних параметрів, які впливають на кожну команду. Кожен розділ складається з одного параметра на рядок, визначеного як option=value.

Наприклад, нижче наведено повний файл конфігурації, який просто змушує всі команди виконуватися тихо за замовчуванням:

[global]
verbose=0

Якщо це встановлено як файл конфігурації системи, це вплине на всю обробку будь-якого розповсюдження модуля Python будь-яким користувачем у поточній системі. Якщо його встановлено як ваш особистий конфігураційний файл (у системах, які їх підтримують), він впливатиме лише на розповсюдження модулів, які ви обробляєте. І якщо він використовується як setup.cfg для певного дистрибутива модуля, він впливає лише на цей дистрибутив.

Ви можете перевизначити типовий каталог «build base» і змусити команди build* завжди примусово перезбирати всі файли за допомогою наступного:

[build]
build-base=blib
force=1

який відповідає аргументам командного рядка

python setup.py build --build-base=blib --force

за винятком того, що включення команди build до командного рядка означає, що команда буде виконана. Включення конкретної команди до конфігураційних файлів не має такого значення; це лише означає, що якщо команду запущено, будуть застосовані параметри у файлі конфігурації. (Або якщо запускаються інші команди, які отримують значення з нього, вони використовуватимуть значення у файлі конфігурації.)

Ви можете знайти повний список параметрів для будь-якої команди за допомогою параметра --help, наприклад:

python setup.py build --help

і ви можете дізнатися повний список глобальних параметрів, використовуючи --help без команди:

python setup.py --help

Дивіться також розділ «Довідка» посібника «Розповсюдження модулів Python».

Будівництво прибудов: поради та підказки

Коли це можливо, Distutils намагаються використовувати інформацію про конфігурацію, надану інтерпретатором Python, який використовується для запуску сценарію setup.py. Наприклад, ті самі прапорці компілятора та компонувальника, що використовуються для компіляції Python, також використовуватимуться для компіляції розширень. Зазвичай це добре працює, але в складних ситуаціях це може бути недоречним. У цьому розділі обговорюється, як змінити звичайну поведінку Distutils.

Налаштування прапорів компілятора/лінкера

Компіляція розширення Python, написаного на C або C++, іноді потребує вказівки спеціальних прапорів для компілятора та компонувальника, щоб використовувати певну бібліотеку або створювати особливий тип об’єктного коду. Це особливо вірно, якщо розширення не було протестовано на вашій платформі або якщо ви намагаєтеся крос-компілювати Python.

У найзагальнішому випадку автор розширення міг передбачити, що компіляція розширень буде складною, і надав файл Setup для редагування. Ймовірно, це буде зроблено, лише якщо дистрибутив модуля містить багато окремих модулів розширення, або якщо вони часто вимагають складних наборів прапорів компілятора для роботи.

Файл Setup, якщо він є, аналізується, щоб отримати список розширень для створення. Кожен рядок у Setup описує окремий модуль. Лінії мають таку структуру:

module ... [sourcefile ...] [cpparg ...] [library ...]

Розглянемо по черзі кожне з полів.

• module — це ім’я модуля розширення, який потрібно створити, і має бути дійсним ідентифікатором Python. Ви не можете просто змінити це, щоб перейменувати модуль (також буде потрібно редагування вихідного коду), тому це слід залишити.

• sourcefile — це все, що ймовірно є файлом вихідного коду, принаймні судячи з назви файлу. Передбачається, що назви файлів, що закінчуються на .c, написані на C, а назви файлів, що закінчуються на .C, .cc і .c++, — на C++ , а імена файлів, що закінчуються на .m або .mm, вважаються такими, що належать до Objective C.

• cpparg — це аргумент для препроцесора C і все, що починається з -I, -D, -U або -C.

• бібліотека — це все, що закінчується на .a або починається на -l чи -L.

Якщо певна платформа потребує спеціальної бібліотеки на вашій платформі, ви можете додати її, відредагувавши файл Setup і запустивши python setup.py build. Наприклад, якщо модуль, визначений рядком

foo foomodule.c

має бути пов’язано з математичною бібліотекою libm.a на вашій платформі, просто додайте -lm до рядка:

foo foomodule.c -lm

Довільні перемикачі, призначені для компілятора або компонувальника, можуть бути забезпечені параметрами -Xcompiler arg і -Xlinker arg:

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

Наступний параметр після -Xcompiler і -Xlinker буде додано до відповідного командного рядка, тому у наведеному вище прикладі компілятору буде передано параметр -o32 , і компонувальнику буде передано -shared. Якщо параметр компілятора потребує аргументу, вам доведеться надати кілька параметрів -Xcompiler; наприклад, щоб передати -x c++ файл Setup повинен містити -Xcompiler -x -Xcompiler c++.

Прапори компілятора також можна надати через встановлення змінної середовища CFLAGS. Якщо встановлено, вміст CFLAGS буде додано до позначок компілятора, указаних у файлі Setup.

Використання компіляторів не від Microsoft у Windows

Borland/CodeGear C++

У цьому підрозділі описано необхідні кроки для використання Distutils із компілятором Borland C++ версії 5.5. По-перше, ви повинні знати, що формат об’єктного файлу Borland (OMF) відрізняється від формату, який використовується версією Python, яку можна завантажити з веб-сайту Python або ActiveState. (Python побудовано з Microsoft Visual C++, який використовує COFF як формат об’єктного файлу.) З цієї причини вам потрібно конвертувати бібліотеку Python python25.lib у формат Borland. Ви можете зробити це наступним чином:

coff2omf python25.lib python25_bcpp.lib

Програма coff2omf постачається разом із компілятором Borland. Файл python25.lib знаходиться в каталозі Libs вашого встановлення Python. Якщо ваше розширення використовує інші бібліотеки (zlib, …), їх також потрібно конвертувати.

Перетворені файли мають зберігатися в тих самих каталогах, що й звичайні бібліотеки.

Як Distutils вдається використовувати ці бібліотеки зі зміненими назвами? Якщо для розширення потрібна бібліотека (наприклад, foo), Distutils спочатку перевіряє, чи знайде бібліотеку з суфіксом _bcpp (наприклад, foo_bcpp.lib), а потім використовує цю бібліотеку. У випадку, якщо він не знаходить такої спеціальної бібліотеки, він використовує назву за замовчуванням (foo.lib.) [1]

Щоб дозволити Distutils скомпілювати ваше розширення за допомогою Borland C++, вам тепер потрібно ввести:

python setup.py build --compiler=bcpp

Якщо ви хочете використовувати компілятор Borland C++ за замовчуванням, ви можете вказати це у своєму особистому або системному файлі конфігурації для Distutils (див. розділ Файли конфігурації Distutils.)

Дивись також

Компілятор C++Builder

Інформація про безкоштовний компілятор C++ від Borland, включаючи посилання на сторінки завантаження.

Створення розширень Python за допомогою безкоштовного компілятора Borland

Документ, що описує, як використовувати безкоштовний компілятор командного рядка Borland C++ для створення Python.

GNU C / Cygwin / MinGW

У цьому розділі описано необхідні кроки для використання Distutils із компіляторами GNU C/C++ у їхніх дистрибутивах Cygwin та MinGW. [2] Для інтерпретатора Python, створеного за допомогою Cygwin, усе повинно працювати без будь-якого з цих кроків.

Не всі розширення можна створити за допомогою MinGW або Cygwin, але багато з них можуть. Швидше за все не працюють розширення, які використовують C++ або залежать від розширень Microsoft Visual C.

Щоб дозволити Distutils скомпілювати ваше розширення за допомогою Cygwin, вам потрібно ввести:

python setup.py build --compiler=cygwin

і для Cygwin у режимі без Cygwin [3] або для типу MinGW:

python setup.py build --compiler=mingw32

Якщо ви хочете використовувати будь-який із цих параметрів/компіляторів за замовчуванням, вам слід записати його у свій особистий або загальносистемний файл конфігурації для Distutils (див. розділ Файли конфігурації Distutils.)

Старіші версії Python і MinGW

Наступні вказівки застосовуються, лише якщо ви використовуєте версію Python нижчу за 2.4.1 із MinGW нижчою за 3.0.0 (з binutils-2.13.90-20030111-1).

Для цих компіляторів потрібні спеціальні бібліотеки. Це завдання більш складне, ніж для C++ від Borland, оскільки немає програми для перетворення бібліотеки. Спочатку вам потрібно створити список символів, які експортує DLL Python. (Ви можете знайти хорошу програму для цього завдання на https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).

pexports python25.dll >python25.def

Розташування встановленого python25.dll залежатиме від параметрів встановлення, версії та мови Windows. Під час встановлення «тільки для мене» він з’явиться в кореневому каталозі встановлення. У спільній установці він буде розташований у системному каталозі.

Тоді ви можете створити з цієї інформації бібліотеку імпорту для gcc.

/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

Отриману бібліотеку потрібно розмістити в тому ж каталозі, що й python25.lib. (Має бути каталог libs у вашому каталозі встановлення Python.)

Якщо ваше розширення використовує інші бібліотеки (zlib,…), вам, можливо, доведеться конвертувати їх також. Перетворені файли мають зберігатися в тих самих каталогах, що й звичайні бібліотеки.

Дивись також

Building Python modules on MS Windows platform with MinGW

Інформація про створення необхідних бібліотек для середовища MinGW.

Виноски

[1]

Це також означає, що ви можете замінити всі існуючі COFF-бібліотеки бібліотеками OMF з такою ж назвою.

[2]

Перегляньте https://www.sourceware.org/cygwin/ для отримання додаткової інформації

[3]

Тоді вам не доступна емуляція POSIX, але вам також не потрібен cygwin1.dll.