index.md
1> **Источник:** https://python-all.ru/3.6/install/index.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Установка модулей Python (устаревшая версия)89**Автор**1011Greg Ward1213> **См. также**14>15> **[Установка модулей Python](https://python-all.ru/3.6/installing/index.html#installing-index)**16>17> Актуальная документация по установке модулей1819В этом документе описываются утилиты распространения Python (Distutils) с точки зрения конечного пользователя: как расширить возможности стандартной установки Python, собрав и установив сторонние модули и расширения Python.2021> **Примечание**22>23> Это руководство охватывает только основные инструменты для сборки и распространения расширений, входящие в состав этой версии Python. Сторонние инструменты предлагают более простые и безопасные альтернативы. Для получения дополнительной информации обратитесь к [разделу с краткими рекомендациями](https://python-all.ru/3.6/install/index.html) в руководстве пользователя по упаковке Python.2425## Введение2627Хотя обширная стандартная библиотека Python покрывает многие потребности программирования, часто наступает момент, когда необходимо добавить новую функциональность в установку Python в виде сторонних модулей. Это может понадобиться для поддержки собственных программ или для использования приложения, написанного на Python.2829В прошлом было мало поддержки для добавления сторонних модулей в существующую установку Python. С появлением утилит распространения Python (сокращённо Distutils) в Python 2.0 это изменилось.3031Этот документ предназначен в первую очередь для тех, кому нужно установить сторонние модули Python: конечных пользователей и системных администраторов, которым просто нужно запустить какое-нибудь Python-приложение, а также опытных программистов Python, желающих добавить новые инструменты в свой арсенал. Для чтения этого документа не требуется знать Python; будут лишь краткие экскурсы в интерактивный режим Python для изучения вашей установки, но не более. Если вы ищете информацию о том, как распространять собственные модули Python, чтобы другие могли их использовать, обратитесь к руководству [Distributing Python Modules (Legacy version)](https://python-all.ru/3.6/distutils/index.html#distutils-index). Также может быть полезна [отладка сценария установки](https://python-all.ru/3.6/distutils/setupscript.html#debug-setup-script).3233### Идеальный случай: простая установка3435В идеальном случае кто-то подготовит специальную версию распространяемого модуля, который вы хотите установить, ориентированную именно на вашу платформу, и устанавливаемую как любое другое программное обеспечение на вашей платформе. Например, разработчик модуля может предоставить исполняемый установщик для пользователей Windows, пакет RPM для пользователей Linux-систем на основе RPM (Red Hat, SuSE, Mandrake и многих других), пакет Debian для пользователей систем на основе Debian и так далее.3637В этом случае вы загрузите установщик, подходящий для вашей платформы, и сделаете очевидное: запустите его, если это исполняемый установщик, `rpm --install` его, если это RPM, и т.д. Вам не нужно запускать Python или сценарий установки, не нужно ничего компилировать – возможно, вам даже не придётся читать какие-либо инструкции (хотя всегда полезно это сделать).3839Конечно, не всегда всё так просто. Возможно, вас заинтересует распространяемый модуль, для которого нет простого установщика для вашей платформы. В этом случае придётся начать с исходного дистрибутива, выпущенного автором или сопровождающим модуля. Установка из исходного дистрибутива не слишком сложна, если модули упакованы стандартным образом. Основная часть этого документа посвящена сборке и установке модулей из стандартных исходных дистрибутивов.4041### Новый стандарт: Distutils4243Если вы загружаете исходный дистрибутив модуля, можно довольно быстро понять, был ли он упакован и распространён стандартным способом, то есть с помощью Distutils. Во-первых, имя дистрибутива и номер версии будут чётко указаны в имени загружаемого архива, например, `foo-1.0.tar.gz` или `widget-0.9.7.zip`. Затем архив распакуется в каталог с похожим именем: `foo-1.0` или `widget-0.9.7`. Кроме того, дистрибутив будет содержать скрипт установки `setup.py` и файл с именем `README.txt` или возможно просто `README`, в котором будет объяснено, что сборка и установка дистрибутива модуля сводится к выполнению одной команды в терминале:4445```text46python setup.py install47```4849Для Windows эту команду следует запускать из окна командной строки (Пуск ‣ Стандартные):5051```text52setup.py install53```5455Если всё это верно, то вы уже знаете, как собрать и установить только что загруженные модули: просто выполните указанную выше команду. Если вам не нужно устанавливать что-либо нестандартным способом или настраивать процесс сборки, эта документация вам по большому счёту не понадобится. Вернее, приведённая выше команда – это всё, что нужно, чтобы обойтись без этого руководства.5657## Стандартная сборка и установка5859Как описано в разделе [Новый стандарт: Distutils](https://python-all.ru/3.6/install/index.html#inst-new-standard), сборка и установка распространяемого модуля с помощью Distutils обычно сводится к одной простой команде, выполняемой из терминала:6061```text62python setup.py install63```6465### Различия по платформам6667Команду setup всегда следует выполнять из корневого каталога дистрибутива, то есть из каталога верхнего уровня, в который распакован дистрибутив исходных кодов модуля. Например, если вы только что загрузили дистрибутив исходных кодов модуля `foo-1.0.tar.gz` в системе Unix, обычные действия таковы:6869```text70gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.071cd foo-1.072python setup.py install73```7475В Windows вы, вероятно, загрузите `foo-1.0.zip`. Если архивный файл загружен в `C:\Temp`, то он распакуется в `C:\Temp\foo-1.0`. Для распаковки архива можно использовать программу с графическим интерфейсом (например, WinZip) или утилиту командной строки (например, **unzip** или **pkunzip**). Затем откройте окно командной строки и выполните:7677```text78cd c:\Temp\foo-1.079python setup.py install80```8182### Разделение процесса на этапы8384Запуск `setup.py install` собирает и устанавливает все модули за один раз. Если вы предпочитаете работать поэтапно – это особенно полезно при настройке процесса сборки или при возникновении проблем – вы можете использовать сценарий setup для выполнения по одной задаче за раз. Это особенно удобно, когда сборка и установка выполняются разными пользователями: например, вы можете собрать дистрибутив модуля и передать его системному администратору для установки (или установить самостоятельно, имея права суперпользователя).8586Например, можно выполнить сборку на первом шаге, а установку – на втором, вызвав сценарий setup дважды:8788```text89python setup.py build90python setup.py install91```9293Если вы так сделаете, то заметите, что команда **install** сначала запускает команду **build**, которая в этом случае быстро обнаруживает, что ей ничего не нужно делать, так как всё в каталоге `build` уже актуально.9495Возможно, разбиение на этапы не понадобится, если вы только устанавливаете модули, загруженные из сети, но это очень удобно для более сложных задач. Если вы начнёте распространять собственные модули и расширения Python, вам придётся часто запускать отдельные команды Distutils самостоятельно.9697### Как работает сборка9899Как уже было сказано, команда **build** отвечает за помещение устанавливаемых файлов в *каталог сборки*. По умолчанию это `build` в корне дистрибутива; если вы слишком обеспокоены скоростью или хотите сохранить исходное дерево в чистоте, вы можете изменить каталог сборки с помощью опции `--build-base`. Например:100101```text102python setup.py build --build-base=/path/to/pybuild/foo-1.0103```104105(Или это можно сделать постоянно с помощью директивы в системном или личном конфигурационном файле Distutils; см. раздел [Конфигурационные файлы Distutils](https://python-all.ru/3.6/install/index.html#inst-config-files).) Обычно в этом нет необходимости.106107Структура дерева сборки по умолчанию выглядит следующим образом:108109```text110--- build/ --- lib/111or112--- build/ --- lib.<plat>/113 temp.<plat>/114```115116где `<plat>` раскрывается в краткое описание текущей ОС/аппаратной платформы и версии Python. Первая форма, только с каталогом `lib`, используется для «дистрибутивов чистых модулей» – то есть для дистрибутивов, содержащих только чистые модули Python. Если дистрибутив модуля содержит расширения (модули на C/C++), то используется вторая форма – с двумя каталогами `<plat>`. В этом случае каталог `temp.plat` содержит временные файлы, создаваемые в процессе компиляции/компоновки, которые фактически не устанавливаются. В любом случае каталог `lib` (или `lib.plat`) содержит все модули Python (чистые и расширения), которые будут установлены.117118В будущем будут добавлены дополнительные каталоги для размещения скриптов Python, документации, исполняемых файлов и всего остального, что необходимо для установки модулей и приложений Python.119120### Как работает установка121122После выполнения команды **build** (явно или автоматически командой **install**) работа команды **install** становится относительно простой: ей остаётся только скопировать всё содержимое из `build/lib` (или `build/lib.plat`) в выбранный каталог установки.123124Если не указать каталог установки (то есть просто запустить `setup.py install`), то команда **install** устанавливает модули в стандартный каталог для сторонних модулей Python. Этот каталог зависит от платформы и от того, как собран или установлен сам Python. На Unix (и Mac OS X, которая также основана на Unix) это также зависит от того, является ли устанавливаемый дистрибутив модуля чисто Python или содержит расширения («нечистый»):125126| Платформа | Стандартное расположение установки | Значение по умолчанию | Примечания |127| --- | --- | --- | --- |128| Unix (чистый) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |129| Unix (не чистый) | `exec-prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |130| Windows | `prefix\Lib\site-packages` | `C:\PythonXY\Lib\site-packages` | (2) |131132Примечания:1331341. Большинство дистрибутивов Linux включают Python как стандартную часть системы, поэтому `prefix` и `exec-prefix` обычно оба равны `/usr` в Linux. Если вы собираете Python самостоятельно в Linux (или любой Unix-подобной системе), то значения по умолчанию для `prefix` и `exec-prefix` – `/usr/local`.1352. Каталог установки по умолчанию в Windows был `C:\Program Files\Python` в Python 1.6a1, 1.5.2 и более ранних версиях.136137`prefix` и `exec-prefix` обозначают каталоги, в которые установлен Python и где он ищет библиотеки во время выполнения. Под Windows они всегда одинаковы, а под Unix и Mac OS X – чаще всего одинаковы. Узнать, какие значения использует установка Python для `prefix` и `exec-prefix`, можно, запустив Python в интерактивном режиме и введя несколько простых команд. Под Unix просто введите `python` в командной строке. Под Windows выберите Пуск ‣ Программы ‣ Python X.Y ‣ Python (командная строка). После запуска интерпретатора введите код Python в приглашении. Например, в моей системе Linux я ввожу три оператора Python, показанные ниже, и получаю вывод, как показано, чтобы узнать мои `prefix` и `exec-prefix`:138139```pycon140Python 2.4 (#26, Aug 7 2004, 17:19:02)141Type "help", "copyright", "credits" or "license" for more information.142>>> import sys143>>> sys.prefix144'/usr'145>>> sys.exec_prefix146'/usr'147```148149В этом документе используются и другие заполнители: `X.Y` обозначает версию Python, например `3.2`; `abiflags` заменяется на значение [`sys.abiflags`](https://python-all.ru/3.6/library/sys.html#sys.abiflags) или пустую строку для платформ, не определяющих флаги ABI; `distname` заменяется на имя устанавливаемого дистрибутива модуля. Точки и регистр букв важны в путях; например, значение, использующее `python3.2` в UNIX, в Windows обычно имеет вид `Python32`.150151Если вы не хотите устанавливать модули в стандартное расположение или у вас нет прав на запись туда, обратитесь к разделу [Альтернативная установка](https://python-all.ru/3.6/install/index.html#inst-alt-install). Если вы хотите более глубоко настроить каталоги установки, см. раздел [Пользовательская установка](https://python-all.ru/3.6/install/index.html#inst-custom-install).152153## Альтернативная установка154155Часто необходимо или желательно устанавливать модули в расположение, отличное от стандартного для сторонних модулей Python. Например, в системе Unix у вас может не быть прав на запись в стандартный каталог сторонних модулей. Или вы можете захотеть опробовать модуль, прежде чем делать его стандартной частью вашей локальной установки Python. Это особенно актуально при обновлении уже установленного дистрибутива: вы хотите убедиться, что существующая база скриптов продолжает работать с новой версией, прежде чем выполнять обновление.156157Команда **install** из пакета Distutils предназначена для простой и безболезненной установки дистрибутивов модулей в альтернативное расположение. Основная идея: указывается базовый каталог для установки, а команда **install** выбирает набор каталогов (называемый *схемой установки*) внутри этого базового каталога, куда будут установлены файлы. Детали различаются в зависимости от платформы, поэтому следует прочитать соответствующий раздел.158159Обратите внимание, что различные альтернативные схемы установки являются взаимоисключающими: можно указать `--user`, или `--home`, или `--prefix` и `--exec-prefix`, или `--install-base` и `--install-platbase`, но нельзя смешивать варианты из этих групп.160161### Альтернативная установка: схема пользователя162163Эта схема предназначена для наиболее удобного решения для пользователей, у которых нет прав на запись в глобальный каталог site-packages или которые не хотят в него устанавливать. Она включается простым параметром:164165```text166python setup.py install --user167```168169Файлы будут установлены в подкаталоги каталога [`site.USER_BASE`](https://python-all.ru/3.6/library/site.html#site.USER_BASE) (далее обозначается как `userbase`). Эта схема устанавливает чистые модули Python и модули расширений в одно и то же место (также известное как [`site.USER_SITE`](https://python-all.ru/3.6/library/site.html#site.USER_SITE)). Вот значения для UNIX, включая Mac OS X:170171| Тип файла | Каталог установки |172| --- | --- |173| Модули | `userbase/lib/pythonX.Y/site-packages` |174| Скрипты | `userbase/bin` |175| Данные | `userbase` |176| Заголовочные файлы C | `userbase/include/pythonX.Yabiflags/distname` |177178А вот значения, используемые в Windows:179180| Тип файла | Каталог установки |181| --- | --- |182| Модули | `userbase\PythonXY\site-packages` |183| Скрипты | `userbase\PythonXY\Scripts` |184| Данные | `userbase` |185| Заголовочные файлы C | `userbase\PythonXY\Include{distname}` |186187Преимущество использования этой схемы по сравнению с другими, описанными ниже, заключается в том, что каталог пользовательских site-packages в обычных условиях всегда включён в [`sys.path`](https://python-all.ru/3.6/library/sys.html#sys.path) (см. [`site`](https://python-all.ru/3.6/library/site.html#module-site) для получения дополнительной информации), а значит, после запуска скрипта `setup.py` для завершения установки не требуется выполнять никаких дополнительных действий.188189Команда **build\_ext** также имеет параметр `--user` для добавления `userbase/include` в путь поиска компилятора для заголовочных файлов и `userbase/lib` в путь поиска компилятора для библиотек, а также в путь поиска времени выполнения для разделяемых C-библиотек (rpath).190191### Альтернативная установка: схема home192193Идея «домашней схемы» заключается в том, что вы создаёте и поддерживаете личную коллекцию модулей Python. Название этой схемы происходит от идеи «домашнего» каталога в Unix, поскольку пользователи Unix нередко делают свой домашний каталог похожим на `/usr/` или `/usr/local/`. Эту схему может использовать кто угодно, независимо от операционной системы, для которой выполняется установка.194195Установка нового дистрибутива модуля так же проста, как196197```text198python setup.py install --home=<dir>199```200201где для параметра `--home` можно указать любой каталог. В Unix ленивые могут просто ввести тильду (`~`); команда **install** развернёт её в домашний каталог:202203```text204python setup.py install --home=~205```206207Чтобы Python находил дистрибутивы, установленные с помощью этой схемы, может потребоваться [изменить путь поиска Python](https://python-all.ru/3.6/install/index.html#inst-search-path) или отредактировать `sitecustomize` (см. [`site`](https://python-all.ru/3.6/library/site.html#module-site)) для вызова [`site.addsitedir()`](https://python-all.ru/3.6/library/site.html#site.addsitedir) или редактирования [`sys.path`](https://python-all.ru/3.6/library/sys.html#sys.path).208209Параметр `--home` определяет базовый каталог установки. Файлы устанавливаются в следующие каталоги внутри базового каталога установки:210211| Тип файла | Каталог установки |212| --- | --- |213| Модули | `home/lib/python` |214| Скрипты | `home/bin` |215| Данные | `home` |216| Заголовочные файлы C | `home/include/python/distname` |217218(Мысленно замените косые черты на обратные, если вы работаете в Windows.)219220### Альтернативная установка: Unix (схема prefix)221222Префиксная схема полезна, если вы хотите использовать одну установку Python для сборки/установки (т.е. для запуска setup-скрипта), но устанавливать модули в каталог сторонних модулей другой установки Python (или того, что выглядит как другая установка Python). Если это звучит немного необычно – так и есть, поэтому сначала идут схемы пользователя и домашняя. Однако есть как минимум два известных случая, где префиксная схема окажется полезной.223224Во-первых, учтите, что многие дистрибутивы Linux помещают Python в `/usr`, а не в более традиционный `/usr/local`. Это совершенно оправданно, поскольку в таких случаях Python является частью «системы», а не локальным дополнением. Однако если вы устанавливаете модули Python из исходных кодов, вы, вероятно, захотите поместить их в `/usr/local/lib/python2.X`, а не в `/usr/lib/python2.X`. Это можно сделать с помощью225226```text227/usr/bin/python setup.py install --prefix=/usr/local228```229230Другая возможность – сетевая файловая система, где имя, используемое для записи в удалённый каталог, отличается от имени, используемого для его чтения: например, интерпретатор Python, доступный как `/usr/local/bin/python`, может искать модули в `/usr/local/lib/python2.X`, но эти модули должны быть установлены, скажем, в `/mnt/@server/export/lib/python2.X`. Это можно было бы сделать с помощью231232```text233/usr/local/bin/python setup.py install --prefix=/mnt/@server/export234```235236В любом случае параметр `--prefix` задаёт базовый каталог установки, а параметр `--exec-prefix` – базовый каталог для платформозависимой установки, который используется для файлов, зависящих от платформы. (Сейчас это относится только к неплатформенным дистрибутивам модулей, но может быть расширено на библиотеки C, исполняемые файлы и т.д.) Если `--exec-prefix` не указан, по умолчанию он равен `--prefix`. Файлы устанавливаются следующим образом:237238| Тип файла | Каталог установки |239| --- | --- |240| Модули Python | `prefix/lib/pythonX.Y/site-packages` |241| Модули расширения | `exec-prefix/lib/pythonX.Y/site-packages` |242| Скрипты | `prefix/bin` |243| Данные | `prefix` |244| Заголовочные файлы C | `prefix/include/pythonX.Yabiflags/distname` |245246Не требуется, чтобы `--prefix` или `--exec-prefix` обязательно указывали на другую установку Python. Если перечисленные выше каталоги ещё не существуют, они создаются во время установки.247248Кстати, настоящая причина, по которой важна префиксная схема, просто в том, что стандартная установка Unix использует префиксную схему, но с `--prefix` и `--exec-prefix`, которые Python задаёт сам как `sys.prefix` и `sys.exec_prefix`. Поэтому может показаться, что префиксная схема никогда не понадобится, но каждый раз, когда вы запускаете `python setup.py install` без других параметров, вы её используете.249250Обратите внимание, что установка расширений в другую установку Python не влияет на то, как эти расширения собираются: в частности, при компиляции расширений используются заголовочные файлы Python (`Python.h` и другие) из интерпретатора, который запускает сценарий установки. Именно вы отвечаете за то, чтобы интерпретатор, используемый для запуска установленных таким образом расширений, был совместим с тем, на котором они собирались. Лучший способ это сделать – убедиться, что оба интерпретатора относятся к одной версии Python (возможны разные сборки или просто копии одной и той же сборки). (Разумеется, если ваши `--prefix` и `--exec-prefix` вообще не указывают на другую установку Python, это не имеет значения.)251252### Альтернативная установка: Windows (префиксная схема)253254В Windows нет понятия домашнего каталога пользователя, и поскольку стандартная установка Python в Windows проще, чем в Unix, параметр `--prefix` традиционно используется для установки дополнительных пакетов в отдельные каталоги.255256```text257python setup.py install --prefix="\Temp\Python"258```259260для установки модулей в каталог `\Temp\Python` на текущем диске.261262Базовый каталог установки задаётся параметром `--prefix`. Параметр `--exec-prefix` в Windows не поддерживается, поэтому чистые модули Python и модули расширения устанавливаются в одно и то же место. Файлы устанавливаются следующим образом:263264| Тип файла | Каталог установки |265| --- | --- |266| Модули | `prefix\Lib\site-packages` |267| Скрипты | `prefix\Scripts` |268| Данные | `prefix` |269| Заголовочные файлы C | `prefix\Include{distname}` |270271## Пользовательская установка272273Иногда описанные в разделе [Alternate Installation](https://python-all.ru/3.6/install/index.html#inst-alt-install) схемы альтернативной установки не делают того, что нужно. Возможно, вы хотите подправить всего один-два каталога, оставив всё остальное в том же базовом каталоге, или полностью переопределить схему установки. В любом случае вы создаёте *пользовательскую схему установки*.274275Чтобы создать пользовательскую схему установки, возьмите одну из альтернативных схем и переопределите некоторые каталоги установки для разных типов файлов с помощью следующих параметров:276277| Тип файла | Переопределяющий параметр |278| --- | --- |279| Модули Python | `--install-purelib` |280| Модули расширения | `--install-platlib` |281| Все модули | `--install-lib` |282| Скрипты | `--install-scripts` |283| Данные | `--install-data` |284| Заголовочные файлы C | `--install-headers` |285286Эти переопределяющие параметры могут быть относительными, абсолютными или явно заданными через один из базовых каталогов установки. (Базовых каталогов два, и обычно они совпадают – различие появляется только при использовании префиксной схемы Unix с разными значениями `--prefix` и `--exec-prefix`; использование `--install-lib` переопределяет значения, вычисленные или заданные для `--install-purelib` и `--install-platlib`, и рекомендуется для схем, где нет различий между модулями Python и расширениями.)287288Например, вы устанавливаете дистрибутив модулей в свой домашний каталог в Unix, но хотите, чтобы скрипты помещались в `~/scripts`, а не в `~/bin`. Как и следовало ожидать, это можно сделать с помощью параметра `--install-scripts`. В данном случае разумнее всего указать относительный путь, который будет интерпретироваться относительно базового каталога установки (в данном случае – вашего домашнего каталога):289290```text291python setup.py install --home=~ --install-scripts=scripts292```293294Другой пример для Unix: допустим, установка Python была собрана и установлена с префиксом `/usr/local/python`, поэтому при стандартной установке скрипты окажутся в `/usr/local/python/bin`. Чтобы поместить их в `/usr/local/bin`, следует указать этот абсолютный путь для параметра `--install-scripts`:295296```text297python setup.py install --install-scripts=/usr/local/bin298```299300(Выполняется установка с использованием «схемы префикса», где префикс – это путь установки интерпретатора Python – `/usr/local/python` в данном случае.)301302Если вы сопровождаете Python в Windows, возможно, требуется, чтобы сторонние модули располагались в подкаталоге `prefix`, а не прямо в самом `prefix`. Это почти так же просто, как настройка каталога установки скриптов – нужно лишь помнить, что существует два типа модулей: Python-модули и модули расширения, которыми удобно управлять с помощью одного параметра:303304```text305python setup.py install --install-lib=Site306```307308Указанный каталог установки указывается относительно `prefix`. Разумеется, также нужно убедиться, что этот каталог находится в пути поиска модулей Python, например, поместив файл `.pth` в site-каталог (см. [`site`](https://python-all.ru/3.6/library/site.html#module-site)). О том, как изменить путь поиска Python, рассказано в разделе [Изменение пути поиска Python](https://python-all.ru/3.6/install/index.html#inst-search-path).309310Если требуется определить полную схему установки, нужно просто указать все параметры каталогов установки. Рекомендуется задавать относительные пути; например, если все файлы, связанные с модулями Python, должны находиться в каталоге `python` в вашем домашнем каталоге, и для каждой платформы, с которой этот домашний каталог используется, нужен отдельный каталог, можно определить следующую схему установки:311312```text313python setup.py install --home=~ \314 --install-purelib=python/lib \315 --install-platlib=python/lib.$PLAT \316 --install-scripts=python/scripts317 --install-data=python/data318```319320или, что то же самое,321322```text323python setup.py install --home=~/python \324 --install-purelib=lib \325 --install-platlib='lib.$PLAT' \326 --install-scripts=scripts327 --install-data=data328```329330`$PLAT` не (обязательно) является переменной окружения – он будет развёрнут Distutils при разборе параметров командной строки, так же как и при разборе файлов конфигурации.331332Очевидно, указывать полную схему установки при каждой установке нового дистрибутива модуля было бы очень утомительно. Поэтому эти параметры можно поместить в файл конфигурации Distutils (см. раздел [Файлы конфигурации Distutils](https://python-all.ru/3.6/install/index.html#inst-config-files)):333334```ini335[install]336install-base=$HOME337install-purelib=python/lib338install-platlib=python/lib.$PLAT339install-scripts=python/scripts340install-data=python/data341```342343или, что то же самое,344345```ini346[install]347install-base=$HOME/python348install-purelib=lib349install-platlib=lib.$PLAT350install-scripts=scripts351install-data=data352```353354Обратите внимание, что эти два варианта *не* эквивалентны, если при запуске скрипта setup указать другой базовый каталог установки. Например,355356```text357python setup.py install --install-base=/tmp358```359360установит чистые модули в `/tmp/python/lib` в первом случае и в `/tmp/lib` во втором. (Для второго случая, вероятно, следует указать базовый каталог установки `/tmp/python`.)361362Вероятно, вы заметили использование `$HOME` и `$PLAT` в примере входного файла конфигурации. Это переменные конфигурации Distutils, которые сильно напоминают переменные окружения. На самом деле, переменные окружения можно использовать в файлах конфигурации на платформах, где они есть, но Distutils дополнительно определяет несколько дополнительных переменных, которых может не быть в вашем окружении, например `$PLAT`. (И, конечно, в системах без переменных окружения, таких как Mac OS 9, переменные конфигурации, предоставляемые Distutils, являются единственными, которые можно использовать.) Подробнее см. раздел [Файлы конфигурации Distutils](https://python-all.ru/3.6/install/index.html#inst-config-files).363364> **Примечание**365>366> Когда [виртуальное окружение](https://python-all.ru/3.6/library/venv.html#venv-def) активировано, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.367368### Изменение пути поиска Python369370Когда интерпретатор Python выполняет инструкцию [`import`](https://python-all.ru/3.6/reference/simple_stmts.html#import), он ищет как код Python, так и модули расширения по пути поиска. Значение пути по умолчанию задаётся в двоичном файле Python при сборке интерпретатора. Узнать этот путь можно, импортировав модуль [`sys`](https://python-all.ru/3.6/library/sys.html#module-sys) и выведя значение `sys.path`.371372```text373$ python374Python 2.2 (#11, Oct 3 2002, 13:31:27)375[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2376Type "help", "copyright", "credits" or "license" for more information.377>>> import sys378>>> sys.path379['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',380 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',381 '/usr/local/lib/python2.3/site-packages']382>>>383```384385Пустая строка в `sys.path` обозначает текущий рабочий каталог.386387Обычная практика для локально установленных пакетов – помещать их в каталог `…/site-packages/`, но может потребоваться установить Python-модули в произвольный каталог. Например, на вашем сайте может быть принято хранить всё программное обеспечение, связанное с веб-сервером, в каталоге `/www`. Тогда дополнительные модули Python могут находиться в `/www/python`, и чтобы импортировать их, этот каталог должен быть добавлен в `sys.path`. Есть несколько различных способов добавить каталог.388389Самый удобный способ – добавить файл конфигурации пути в каталог, уже находящийся в пути поиска Python, обычно в каталог `.../site-packages/`. Файлы конфигурации пути имеют расширение `.pth`, и каждая строка должна содержать один путь, который будет добавлен в `sys.path`. (Поскольку новые пути добавляются в `sys.path`, модули в добавленных каталогах не переопределяют стандартные модули. Это означает, что этот механизм нельзя использовать для установки фиксированных версий стандартных модулей.)390391Пути могут быть абсолютными или относительными; в последнем случае они задаются относительно каталога, содержащего файл `.pth`. Дополнительную информацию см. в документации модуля [`site`](https://python-all.ru/3.6/library/site.html#module-site).392393Чуть менее удобный способ – отредактировать файл `site.py` в стандартной библиотеке Python и изменить `sys.path`. `site.py` автоматически импортируется при запуске интерпретатора Python, если не указан ключ [`-S`](https://python-all.ru/3.6/using/cmdline.html#id3), отключающий это поведение. Поэтому можно просто отредактировать `site.py` и добавить в него две строки:394395```python396import sys397sys.path.append('/www/python/')398```399400Однако если переустановить ту же самую мажорную версию Python (например, при обновлении с 2.2 до 2.2.2), `site.py` будет перезаписан стандартной версией. Перед выполнением установки придётся запомнить, что он был изменён, и сохранить копию.401402Существуют две переменные окружения, которые могут изменить `sys.path`. [`PYTHONHOME`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONHOME) задаёт альтернативное значение префикса установки Python. Например, если [`PYTHONHOME`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONHOME) установлена в `/www/python`, путь поиска будет установлен в `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`.403404Переменная [`PYTHONPATH`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONPATH) может быть установлена в список путей, которые будут добавлены в начало `sys.path`. Например, если [`PYTHONPATH`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONPATH) установлена в `/www/python:/opt/py`, путь поиска начнётся с `['/www/python', '/opt/py']`. (Обратите внимание: каталоги должны существовать, чтобы быть добавленными в `sys.path`; модуль [`site`](https://python-all.ru/3.6/library/site.html#module-site) удаляет несуществующие пути.)405406Наконец, `sys.path` – это обычный список Python, поэтому любое приложение Python может изменять его, добавляя или удаляя записи.407408## Файлы конфигурации Distutils409410Как упоминалось выше, файлы конфигурации Distutils можно использовать для сохранения личных настроек или настроек сайта для любых параметров Distutils. То есть любой параметр любой команды может быть сохранён в одном из двух или трёх (в зависимости от платформы) файлов конфигурации, которые будут обрабатываться до разбора командной строки. Это означает, что файлы конфигурации переопределяют значения по умолчанию, а командная строка, в свою очередь, переопределяет файлы конфигурации. Кроме того, если применяется несколько файлов конфигурации, значения из «более ранних» файлов переопределяются «более поздними».411412### Расположение и имена файлов конфигурации413414Имена и расположение конфигурационных файлов немного различаются в зависимости от платформы. На Unix и Mac OS X три конфигурационных файла (в порядке их обработки):415416| Тип файла | Расположение и имя файла | Примечания |417| --- | --- | --- |418| системный | `prefix/lib/pythonver/distutils/distutils.cfg` | (1) |419| личный | `$HOME/.pydistutils.cfg` | (2) |420| локальный | `setup.cfg` | (3) |421422А в Windows файлы конфигурации:423424| Тип файла | Расположение и имя файла | Примечания |425| --- | --- | --- |426| системный | `prefix\Lib\distutils\distutils.cfg` | (4) |427| личный | `%HOME%\pydistutils.cfg` | (5) |428| локальный | `setup.cfg` | (3) |429430На всех платформах «личный» файл можно временно отключить, передав параметр *–no-user-cfg*.431432Примечания:4334341. Строго говоря, общесистемный файл конфигурации находится в каталоге, где установлен Distutils; в Python 1.6 и новее в Unix это так, как показано. В Python 1.5.2 Distutils обычно устанавливается в `prefix/lib/python1.5/site-packages/distutils`, поэтому при использовании Python 1.5.2 системный файл конфигурации следует размещать там.4352. В Unix, если переменная окружения `HOME` не определена, домашний каталог пользователя определяется с помощью функции `getpwuid()` из стандартного модуля [`pwd`](https://python-all.ru/3.6/library/pwd.html#module-pwd). Это делает функция [`os.path.expanduser()`](https://python-all.ru/3.6/library/os.path.html#os.path.expanduser), используемая в Distutils.4363. То есть в текущем каталоге (обычно там, где находится сценарий setup).4374. (См. также примечание (1).) В Python 1.6 и новее префикс установки Python по умолчанию – `C:\Python`, поэтому системный файл конфигурации обычно находится в `C:\Python\Lib\distutils\distutils.cfg`. В Python 1.5.2 префикс по умолчанию был `C:\Program Files\Python`, а Distutils не входили в стандартную библиотеку, поэтому системный файл конфигурации находился бы в `C:\Program Files\Python\distutils\distutils.cfg` в стандартной установке Python 1.5.2 в Windows.4385. В Windows, если переменная окружения `HOME` не определена, то перебираются `USERPROFILE`, `HOMEDRIVE` и `HOMEPATH`. Это делается функцией [`os.path.expanduser()`](https://python-all.ru/3.6/library/os.path.html#os.path.expanduser), используемой в Distutils.439440### Синтаксис файлов конфигурации441442Все файлы конфигурации Distutils имеют одинаковый синтаксис. Файлы конфигурации разбиты на разделы. Для каждой команды Distutils есть отдельный раздел, плюс раздел `global` для глобальных параметров, влияющих на все команды. Каждый раздел содержит по одному параметру на строку, задаваемому в формате `option=value`.443444Например, ниже приведён полный файл конфигурации, который заставляет все команды по умолчанию работать в тихом режиме:445446```ini447[global]448verbose=0449```450451Если этот файл установлен как системный конфигурационный, он влияет на обработку любых дистрибутивов модулей Python любым пользователем в данной системе. Если установлен как ваш личный конфигурационный файл (в системах, которые это поддерживают), он влияет только на дистрибутивы модулей, обрабатываемые вами. А если используется как `setup.cfg` для конкретного дистрибутива модуля, то влияет только на этот дистрибутив.452453Можно переопределить каталог «build base» по умолчанию и заставить команды **build\*** всегда принудительно пересобирать все файлы следующим образом:454455```ini456[build]457build-base=blib458force=1459```460461что соответствует аргументам командной строки462463```text464python setup.py build --build-base=blib --force465```466467за исключением того, что указание команды **build** в командной строке означает, что эта команда будет выполнена. Включение конкретной команды в файлы конфигурации не имеет такого смысла; это лишь означает, что если команда будет выполнена, то будут применены параметры из файла конфигурации. (Или если будут выполнены другие команды, которые используют её значения, они возьмут значения из файла конфигурации.)468469Полный список параметров для любой команды можно узнать с помощью опции `--help`, например:470471```text472python setup.py build --help473```474475а полный список глобальных параметров – с помощью `--help` без указания команды:476477```text478python setup.py --help479```480481См. также раздел «Справочник» в руководстве «Распространение модулей Python».482483## Сборка расширений: советы и хитрости484485По возможности Distutils стараются использовать информацию о конфигурации, предоставляемую интерпретатором Python, который запускает сценарий `setup.py`. Например, те же флаги компилятора и компоновщика, которые использовались для сборки Python, будут использоваться и для компиляции расширений. Обычно это работает хорошо, но в сложных ситуациях может быть неприемлемо. В этом разделе рассматривается, как переопределить стандартное поведение Distutils.486487### Настройка флагов компилятора/компоновщика488489Компиляция расширения Python, написанного на C или C++, иногда требует указания пользовательских флагов для компилятора и компоновщика, чтобы использовать конкретную библиотеку или создать особый вид объектного кода. Особенно это актуально, если расширение не тестировалось на вашей платформе или вы пытаетесь кросс-компилировать Python.490491В самом общем случае автор расширения мог предвидеть, что компиляция расширений будет сложной, и предоставил файл `Setup` для редактирования. Скорее всего, это делается только тогда, когда дистрибутив модуля содержит много отдельных модулей расширения или они часто требуют сложных наборов флагов компилятора для работы.492493Файл `Setup`, если присутствует, разбирается для получения списка расширений для сборки. Каждая строка в `Setup` описывает один модуль. Строки имеют следующую структуру:494495```text496module ... [sourcefile ...] [cpparg ...] [library ...]497```498499Рассмотрим каждое поле по порядку.500501- *module* – это имя собираемого модуля расширения, и оно должно быть корректным идентификатором Python. Просто изменить его, чтобы переименовать модуль, нельзя (потребуется также править исходный код), поэтому его следует оставить как есть.502- *sourcefile* – это любой файл, который, по крайней мере судя по имени, может быть исходным кодом. Файлы с расширением `.c` считаются написанными на C, файлы с расширениями `.C`, `.cc` и `.c++` – на C++, а файлы с расширениями `.m` или `.mm` – на Objective C.503- *cpparg* – это аргумент для препроцессора C, и им может быть всё, что начинается с `-I`, `-D`, `-U` или `-C`.504- *library* – это всё, что заканчивается на `.a` или начинается с `-l` или `-L`.505506Если для вашей платформы требуется особая библиотека, её можно добавить, отредактировав файл `Setup` и запустив `python setup.py build`. Например, если модуль, заданный строкой507508```text509foo foomodule.c510```511512должен быть слинкован с математической библиотекой `libm.a` на вашей платформе, просто добавьте `-lm` в строку:513514```text515foo foomodule.c -lm516```517518Произвольные опции для компилятора или компоновщика можно передать с помощью опций `-Xcompiler` *аргумент* и `-Xlinker` *аргумент*:519520```text521foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm522```523524Следующая после `-Xcompiler` и `-Xlinker` опция будет добавлена в соответствующую командную строку, поэтому в приведённом примере компилятор получит опцию `-o32`, а компоновщик – `-shared`. Если опция компилятора требует аргумента, придётся указать несколько опций `-Xcompiler`; например, чтобы передать `-x c++`, файл `Setup` должен содержать `-Xcompiler -x -Xcompiler c++`.525526Флаги компилятора можно также задать через переменную окружения `CFLAGS`. Если она установлена, содержимое `CFLAGS` будет добавлено к флагам компилятора, указанным в файле `Setup`.527528### Использование компиляторов не от Microsoft в Windows529530#### Borland/CodeGear C++531532В этом подразделе описаны необходимые шаги для использования Distutils с компилятором Borland C++ версии 5.5. Прежде всего, необходимо знать, что формат объектных файлов Borland (OMF) отличается от формата, используемого в версии Python, которую можно загрузить с веб-сайтов Python или ActiveState. (Python собирается с помощью Microsoft Visual C++, который использует COFF в качестве формата объектных файлов.) По этой причине необходимо преобразовать библиотеку Python `python25.lib` в формат Borland. Это можно сделать следующим образом:533534```text535coff2omf python25.lib python25_bcpp.lib536```537538Программа `coff2omf` поставляется с компилятором Borland. Файл `python25.lib` находится в каталоге `Libs` вашей установки Python. Если ваше расширение использует другие библиотеки (zlib, …), их тоже нужно преобразовать.539540Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.541542Как Distutils умудряется использовать эти библиотеки с изменёнными именами? Если расширению нужна библиотека (например, `foo`), Distutils сначала проверяет, найдётся ли библиотека с суффиксом `_bcpp` (например, `foo_bcpp.lib`), и использует её. Если такой специальной библиотеки нет, используется имя по умолчанию (`foo.lib`). [1](https://python-all.ru/3.6/install/index.html#id4)543544Чтобы Distutils собрал ваше расширение с Borland C++, введите:545546```text547python setup.py build --compiler=bcpp548```549550Если вы хотите использовать компилятор Borland C++ по умолчанию, это можно указать в вашем личном или общесистемном конфигурационном файле Distutils (см. раздел [Distutils Configuration Files](https://python-all.ru/3.6/install/index.html#inst-config-files)).551552> **См. также**553>554> **[Компилятор C++Builder](https://python-all.ru/3.6/install/index.html)**555>556> Информация о бесплатном компиляторе C++ от Borland, включая ссылки на страницы загрузки.557>558> **[Создание расширений Python с помощью бесплатного компилятора Borland](https://python-all.ru/3.6/install/index.html)**559>560> Документ, описывающий, как использовать бесплатный компилятор C++ командной строки Borland для сборки Python.561562#### GNU C / Cygwin / MinGW563564В этом разделе описаны необходимые шаги для использования Distutils с компиляторами GNU C/C++ в дистрибутивах Cygwin и MinGW. [2](https://python-all.ru/3.6/install/index.html#id5) Для интерпретатора Python, собранного с помощью Cygwin, всё должно работать без каких-либо дополнительных действий.565566Не все расширения можно собрать с MinGW или Cygwin, но многие можно. Вероятнее всего, не будут работать расширения, использующие C++ или зависящие от расширений Microsoft Visual C.567568Чтобы Distutils собрал ваше расширение с Cygwin, введите:569570```text571python setup.py build --compiler=cygwin572```573574а для Cygwin в режиме no-cygwin [3](https://python-all.ru/3.6/install/index.html#id6) или для MinGW введите:575576```text577python setup.py build --compiler=mingw32578```579580Если вы хотите использовать любую из этих опций/компиляторов по умолчанию, стоит записать это в ваш личный или общесистемный конфигурационный файл Distutils (см. раздел [Distutils Configuration Files](https://python-all.ru/3.6/install/index.html#inst-config-files)).581582##### Старые версии Python и MinGW583584Следующие инструкции применимы только в том случае, если вы используете версию Python ниже 2.4.1 с MinGW ниже 3.0.0 (с binutils-2.13.90-20030111-1).585586Эти компиляторы требуют некоторых специальных библиотек. Эта задача сложнее, чем для Borland C++, потому что нет программы для преобразования библиотеки. Сначала нужно создать список символов, которые экспортирует DLL Python. (Хорошую программу для этой задачи можно найти на [https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/](https://python-all.ru/3.6/install/index.html)).587588```text589pexports python25.dll >python25.def590```591592Расположение установленного `python25.dll` зависит от параметров установки, версии и языка Windows. При установке «только для меня» он будет находиться в корневом каталоге установки. При общей установке – в системном каталоге.593594Затем на основе этой информации можно создать импортную библиотеку для gcc.595596```text597/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a598```599600Полученную библиотеку нужно поместить в тот же каталог, что и `python25.lib`. (Обычно это каталог `libs` в каталоге установки Python.)601602Если ваше расширение использует другие библиотеки (zlib,…), их, возможно, тоже придётся преобразовать. Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.603604> **См. также**605>606> **[Сборка модулей Python на платформе MS Windows с помощью MinGW](https://python-all.ru/3.6/install/index.html)**607>608> Информация о сборке необходимых библиотек для окружения MinGW.609610Сноски611612**[1](https://python-all.ru/3.6/install/index.html#id1)**613614Это также означает, что можно заменить все существующие COFF-библиотеки на OMF-библиотеки с теми же именами.615616**[2](https://python-all.ru/3.6/install/index.html#id2)**617618Проверьте [https://www.sourceware.org/cygwin/](https://python-all.ru/3.6/install/index.html) и [http://www.mingw.org/](https://python-all.ru/3.6/install/index.html) для получения дополнительной информации619620**[3](https://python-all.ru/3.6/install/index.html#id3)**621622В этом случае эмуляция POSIX недоступна, но и необходимость в `cygwin1.dll` отпадает.623