index.md

1> **Источник:** https://python-all.ru/3.5/install/index.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Установка модулей Python (устаревшая версия)89| Автор: | Greg Ward |10| --- | --- |1112> **См. также**13>14> **[Установка модулей Python](https://python-all.ru/3.5/installing/index.html#installing-index)**15>16> Актуальная документация по установке модулей1718В этом документе описываются утилиты распространения Python (Distutils) с точки зрения конечного пользователя: как расширить возможности стандартной установки Python, собрав и установив сторонние модули и расширения Python.1920> **Примечание**21>22> Это руководство охватывает только основные инструменты для сборки и распространения расширений, входящие в состав этой версии Python. Сторонние инструменты предлагают более простые и безопасные альтернативы. Для получения дополнительной информации обратитесь к [разделу с краткими рекомендациями](https://python-all.ru/3.5/install/index.html) в руководстве пользователя по упаковке Python.2324## Введение2526Хотя обширная стандартная библиотека Python покрывает многие потребности программирования, часто наступает момент, когда необходимо добавить новую функциональность в установку Python в виде сторонних модулей. Это может понадобиться для поддержки собственных программ или для использования приложения, написанного на Python.2728В прошлом было мало поддержки для добавления сторонних модулей в существующую установку Python. С появлением утилит распространения Python (сокращённо Distutils) в Python 2.0 это изменилось.2930Этот документ предназначен в первую очередь для тех, кому нужно установить сторонние модули Python: конечных пользователей и системных администраторов, которым просто нужно запустить какое-нибудь Python-приложение, а также опытных программистов Python, желающих добавить новые инструменты в свой арсенал. Для чтения этого документа не требуется знать Python; будут лишь краткие экскурсы в интерактивный режим Python для изучения вашей установки, но не более. Если вы ищете информацию о том, как распространять собственные модули Python, чтобы другие могли их использовать, обратитесь к руководству [Distributing Python Modules (Legacy version)](https://python-all.ru/3.5/distutils/index.html#distutils-index). Также может быть полезна [отладка сценария установки](https://python-all.ru/3.5/distutils/setupscript.html#debug-setup-script).3132### Идеальный случай: простая установка3334В идеальном случае кто-то подготовит специальную версию распространяемого модуля, который вы хотите установить, ориентированную именно на вашу платформу, и устанавливаемую как любое другое программное обеспечение на вашей платформе. Например, разработчик модуля может предоставить исполняемый установщик для пользователей Windows, пакет RPM для пользователей Linux-систем на основе RPM (Red Hat, SuSE, Mandrake и многих других), пакет Debian для пользователей систем на основе Debian и так далее.3536В этом случае вы загрузите установщик, подходящий для вашей платформы, и сделаете очевидное: запустите его, если это исполняемый установщик, `rpm --install` его, если это RPM, и т.д. Вам не нужно запускать Python или сценарий установки, не нужно ничего компилировать – возможно, вам даже не придётся читать какие-либо инструкции (хотя всегда полезно это сделать).3738Конечно, не всегда всё так просто. Возможно, вас заинтересует распространяемый модуль, для которого нет простого установщика для вашей платформы. В этом случае придётся начать с исходного дистрибутива, выпущенного автором или сопровождающим модуля. Установка из исходного дистрибутива не слишком сложна, если модули упакованы стандартным образом. Основная часть этого документа посвящена сборке и установке модулей из стандартных исходных дистрибутивов.3940### Новый стандарт: Distutils4142Если вы загружаете исходный дистрибутив модуля, можно довольно быстро понять, был ли он упакован и распространён стандартным способом, то есть с помощью Distutils. Во-первых, имя дистрибутива и номер версии будут чётко указаны в имени загружаемого архива, например, `foo-1.0.tar.gz` или `widget-0.9.7.zip`. Затем архив распакуется в каталог с похожим именем: `foo-1.0` или `widget-0.9.7`. Кроме того, дистрибутив будет содержать скрипт установки `setup.py` и файл с именем `README.txt` или возможно просто `README`, в котором будет объяснено, что сборка и установка дистрибутива модуля сводится к выполнению одной команды в терминале:4344```text45python setup.py install46```4748Для Windows эту команду следует запускать из окна командной строки (Пуск ‣ Стандартные):4950```text51setup.py install52```5354Если всё это верно, то вы уже знаете, как собрать и установить только что загруженные модули: просто выполните указанную выше команду. Если вам не нужно устанавливать что-либо нестандартным способом или настраивать процесс сборки, эта документация вам по большому счёту не понадобится. Вернее, приведённая выше команда – это всё, что нужно, чтобы обойтись без этого руководства.5556## Стандартная сборка и установка5758Как описано в разделе [Новый стандарт: Distutils](https://python-all.ru/3.5/install/index.html#inst-new-standard), сборка и установка распространяемого модуля с помощью Distutils обычно сводится к одной простой команде, выполняемой из терминала:5960```text61python setup.py install62```6364### Различия по платформам6566Команду setup всегда следует выполнять из корневого каталога дистрибутива, то есть из каталога верхнего уровня, в который распакован дистрибутив исходных кодов модуля. Например, если вы только что загрузили дистрибутив исходных кодов модуля `foo-1.0.tar.gz` в системе Unix, обычные действия таковы:6768```text69gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.070cd foo-1.071python setup.py install72```7374В Windows вы, вероятно, загрузите `foo-1.0.zip`. Если архивный файл загружен в `C:\Temp`, то он распакуется в `C:\Temp\foo-1.0`. Для распаковки архива можно использовать программу с графическим интерфейсом (например, WinZip) или утилиту командной строки (например, **unzip** или **pkunzip**). Затем откройте окно командной строки и выполните:7576```text77cd c:\Temp\foo-1.078python setup.py install79```8081### Разделение процесса на этапы8283Запуск `setup.py install` собирает и устанавливает все модули за один раз. Если вы предпочитаете работать поэтапно – это особенно полезно при настройке процесса сборки или при возникновении проблем – вы можете использовать сценарий setup для выполнения по одной задаче за раз. Это особенно удобно, когда сборка и установка выполняются разными пользователями: например, вы можете собрать дистрибутив модуля и передать его системному администратору для установки (или установить самостоятельно, имея права суперпользователя).8485Например, можно выполнить сборку на первом шаге, а установку – на втором, вызвав сценарий setup дважды:8687```text88python setup.py build89python setup.py install90```9192Если вы так сделаете, то заметите, что команда **install** сначала запускает команду **build**, которая в этом случае быстро обнаруживает, что ей ничего не нужно делать, так как всё в каталоге `build` уже актуально.9394Возможно, разбиение на этапы не понадобится, если вы только устанавливаете модули, загруженные из сети, но это очень удобно для более сложных задач. Если вы начнёте распространять собственные модули и расширения Python, вам придётся часто запускать отдельные команды Distutils самостоятельно.9596### Как работает сборка9798Как уже было сказано, команда **build** отвечает за помещение устанавливаемых файлов в *каталог сборки*. По умолчанию это `build` в корне дистрибутива; если вы слишком обеспокоены скоростью или хотите сохранить исходное дерево в чистоте, вы можете изменить каталог сборки с помощью опции `--build-base`. Например:99100```text101python setup.py build --build-base=/path/to/pybuild/foo-1.0102```103104(Или это можно сделать постоянно с помощью директивы в системном или личном конфигурационном файле Distutils; см. раздел [Конфигурационные файлы Distutils](https://python-all.ru/3.5/install/index.html#inst-config-files).) Обычно в этом нет необходимости.105106Структура дерева сборки по умолчанию выглядит следующим образом:107108```text109--- build/ --- lib/110or111--- build/ --- lib.<plat>/112               temp.<plat>/113```114115где `<plat>` раскрывается в краткое описание текущей ОС/аппаратной платформы и версии Python. Первая форма, только с каталогом `lib`, используется для «дистрибутивов чистых модулей» – то есть для дистрибутивов, содержащих только чистые модули Python. Если дистрибутив модуля содержит расширения (модули на C/C++), то используется вторая форма – с двумя каталогами `<plat>`. В этом случае каталог `temp.plat` содержит временные файлы, создаваемые в процессе компиляции/компоновки, которые фактически не устанавливаются. В любом случае каталог `lib` (или `lib.plat`) содержит все модули Python (чистые и расширения), которые будут установлены.116117В будущем будут добавлены дополнительные каталоги для размещения скриптов Python, документации, исполняемых файлов и всего остального, что необходимо для установки модулей и приложений Python.118119### Как работает установка120121После выполнения команды **build** (явно или автоматически командой **install**) работа команды **install** становится относительно простой: ей остаётся только скопировать всё содержимое из `build/lib` (или `build/lib.plat`) в выбранный каталог установки.122123Если не указать каталог установки (то есть просто запустить `setup.py install`), то команда **install** устанавливает модули в стандартный каталог для сторонних модулей Python. Этот каталог зависит от платформы и от того, как собран или установлен сам Python. На Unix (и Mac OS X, которая также основана на Unix) это также зависит от того, является ли устанавливаемый дистрибутив модуля чисто Python или содержит расширения («нечистый»):124125| Платформа | Стандартное расположение установки | Значение по умолчанию | Примечания |126| --- | --- | --- | --- |127| Unix (чистый) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |128| Unix (не чистый) | `exec-prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |129| Windows | `prefix\Lib\site-packages` | `C:\PythonXY\Lib\site-packages` | (2) |130131Примечания:1321331. Большинство дистрибутивов Linux включают Python как стандартную часть системы, поэтому `prefix` и `exec-prefix` обычно оба равны `/usr` в Linux. Если вы собираете Python самостоятельно в Linux (или любой Unix-подобной системе), то значения по умолчанию для `prefix` и `exec-prefix` – `/usr/local`.1342. Каталог установки по умолчанию в Windows был `C:\Program Files\Python` в Python 1.6a1, 1.5.2 и более ранних версиях.135136`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`:137138```text139Python 2.4 (#26, Aug  7 2004, 17:19:02)140Type "help", "copyright", "credits" or "license" for more information.141>>> import sys142>>> sys.prefix143'/usr'144>>> sys.exec_prefix145'/usr'146```147148В этом документе используются и другие заполнители: `X.Y` обозначает версию Python, например `3.2`; `abiflags` заменяется на значение [`sys.abiflags`](https://python-all.ru/3.5/library/sys.html#sys.abiflags) или пустую строку для платформ, не определяющих флаги ABI; `distname` заменяется на имя устанавливаемого дистрибутива модуля. Точки и регистр букв важны в путях; например, значение, использующее `python3.2` в UNIX, в Windows обычно имеет вид `Python32`.149150Если вы не хотите устанавливать модули в стандартное расположение или у вас нет прав на запись туда, обратитесь к разделу [Альтернативная установка](https://python-all.ru/3.5/install/index.html#inst-alt-install). Если вы хотите более глубоко настроить каталоги установки, см. раздел [Пользовательская установка](https://python-all.ru/3.5/install/index.html#inst-custom-install).151152## Альтернативная установка153154Часто необходимо или желательно устанавливать модули в расположение, отличное от стандартного для сторонних модулей Python. Например, в системе Unix у вас может не быть прав на запись в стандартный каталог сторонних модулей. Или вы можете захотеть опробовать модуль, прежде чем делать его стандартной частью вашей локальной установки Python. Это особенно актуально при обновлении уже установленного дистрибутива: вы хотите убедиться, что существующая база скриптов продолжает работать с новой версией, прежде чем выполнять обновление.155156Команда **install** из пакета Distutils предназначена для простой и безболезненной установки дистрибутивов модулей в альтернативное расположение. Основная идея: указывается базовый каталог для установки, а команда **install** выбирает набор каталогов (называемый *схемой установки*) внутри этого базового каталога, куда будут установлены файлы. Детали различаются в зависимости от платформы, поэтому следует прочитать соответствующий раздел.157158Обратите внимание, что различные альтернативные схемы установки являются взаимоисключающими: можно указать `--user`, или `--home`, или `--prefix` и `--exec-prefix`, или `--install-base` и `--install-platbase`, но нельзя смешивать варианты из этих групп.159160### Альтернативная установка: схема пользователя161162Эта схема предназначена для наиболее удобного решения для пользователей, у которых нет прав на запись в глобальный каталог site-packages или которые не хотят в него устанавливать. Она включается простым параметром:163164```text165python setup.py install --user166```167168Файлы будут установлены в подкаталоги каталога [`site.USER_BASE`](https://python-all.ru/3.5/library/site.html#site.USER_BASE) (далее обозначается как `userbase`). Эта схема устанавливает чистые модули Python и модули расширений в одно и то же место (также известное как [`site.USER_SITE`](https://python-all.ru/3.5/library/site.html#site.USER_SITE)). Вот значения для UNIX, включая Mac OS X:169170| Тип файла | Каталог установки |171| --- | --- |172| Модули | `userbase/lib/pythonX.Y/site-packages` |173| Скрипты | `userbase/bin` |174| Данные | `userbase` |175| Заголовочные файлы C | `userbase/include/pythonX.Yabiflags/distname` |176177А вот значения, используемые в Windows:178179| Тип файла | Каталог установки |180| --- | --- |181| Модули | `userbase\PythonXY\site-packages` |182| Скрипты | `userbase\PythonXY\Scripts` |183| Данные | `userbase` |184| Заголовочные файлы C | `userbase\PythonXY\Include{distname}` |185186Преимущество использования этой схемы по сравнению с другими, описанными ниже, заключается в том, что каталог пользовательских site-packages в обычных условиях всегда включён в [`sys.path`](https://python-all.ru/3.5/library/sys.html#sys.path) (см. [`site`](https://python-all.ru/3.5/library/site.html#module-site) для получения дополнительной информации), а значит, после запуска скрипта `setup.py` для завершения установки не требуется выполнять никаких дополнительных действий.187188Команда **build\_ext** также имеет параметр `--user` для добавления `userbase/include` в путь поиска компилятора для заголовочных файлов и `userbase/lib` в путь поиска компилятора для библиотек, а также в путь поиска времени выполнения для разделяемых C-библиотек (rpath).189190### Альтернативная установка: схема home191192Идея «домашней схемы» заключается в том, что вы создаёте и поддерживаете личную коллекцию модулей Python. Название этой схемы происходит от идеи «домашнего» каталога в Unix, поскольку пользователи Unix нередко делают свой домашний каталог похожим на `/usr/` или `/usr/local/`. Эту схему может использовать кто угодно, независимо от операционной системы, для которой выполняется установка.193194Установка нового дистрибутива модуля так же проста, как195196```text197python setup.py install --home=<dir>198```199200где для параметра `--home` можно указать любой каталог. В Unix ленивые могут просто ввести тильду (`~`); команда **install** развернёт её в домашний каталог:201202```text203python setup.py install --home=~204```205206Чтобы Python находил дистрибутивы, установленные с помощью этой схемы, может потребоваться [изменить путь поиска Python](https://python-all.ru/3.5/install/index.html#inst-search-path) или отредактировать `sitecustomize` (см. [`site`](https://python-all.ru/3.5/library/site.html#module-site)) для вызова [`site.addsitedir()`](https://python-all.ru/3.5/library/site.html#site.addsitedir) или редактирования [`sys.path`](https://python-all.ru/3.5/library/sys.html#sys.path).207208Параметр `--home` определяет базовый каталог установки. Файлы устанавливаются в следующие каталоги внутри базового каталога установки:209210| Тип файла | Каталог установки |211| --- | --- |212| Модули | `home/lib/python` |213| Скрипты | `home/bin` |214| Данные | `home` |215| Заголовочные файлы C | `home/include/python/distname` |216217(Мысленно замените косые черты на обратные, если вы работаете в Windows.)218219### Альтернативная установка: Unix (схема prefix)220221Префиксная схема полезна, если вы хотите использовать одну установку Python для сборки/установки (т.е. для запуска setup-скрипта), но устанавливать модули в каталог сторонних модулей другой установки Python (или того, что выглядит как другая установка Python). Если это звучит немного необычно – так и есть, поэтому сначала идут схемы пользователя и домашняя. Однако есть как минимум два известных случая, где префиксная схема окажется полезной.222223Во-первых, учтите, что многие дистрибутивы Linux помещают Python в `/usr`, а не в более традиционный `/usr/local`. Это совершенно оправданно, поскольку в таких случаях Python является частью «системы», а не локальным дополнением. Однако если вы устанавливаете модули Python из исходных кодов, вы, вероятно, захотите поместить их в `/usr/local/lib/python2.X`, а не в `/usr/lib/python2.X`. Это можно сделать с помощью224225```text226/usr/bin/python setup.py install --prefix=/usr/local227```228229Другая возможность – сетевая файловая система, где имя, используемое для записи в удалённый каталог, отличается от имени, используемого для его чтения: например, интерпретатор Python, доступный как `/usr/local/bin/python`, может искать модули в `/usr/local/lib/python2.X`, но эти модули должны быть установлены, скажем, в `/mnt/@server/export/lib/python2.X`. Это можно было бы сделать с помощью230231```text232/usr/local/bin/python setup.py install --prefix=/mnt/@server/export233```234235В любом случае параметр `--prefix` задаёт базовый каталог установки, а параметр `--exec-prefix` – базовый каталог для платформозависимой установки, который используется для файлов, зависящих от платформы. (Сейчас это относится только к неплатформенным дистрибутивам модулей, но может быть расширено на библиотеки C, исполняемые файлы и т.д.) Если `--exec-prefix` не указан, по умолчанию он равен `--prefix`. Файлы устанавливаются следующим образом:236237| Тип файла | Каталог установки |238| --- | --- |239| Модули Python | `prefix/lib/pythonX.Y/site-packages` |240| Модули расширения | `exec-prefix/lib/pythonX.Y/site-packages` |241| Скрипты | `prefix/bin` |242| Данные | `prefix` |243| Заголовочные файлы C | `prefix/include/pythonX.Yabiflags/distname` |244245Не требуется, чтобы `--prefix` или `--exec-prefix` обязательно указывали на другую установку Python. Если перечисленные выше каталоги ещё не существуют, они создаются во время установки.246247Кстати, настоящая причина, по которой важна префиксная схема, просто в том, что стандартная установка Unix использует префиксную схему, но с `--prefix` и `--exec-prefix`, которые Python задаёт сам как `sys.prefix` и `sys.exec_prefix`. Поэтому может показаться, что префиксная схема никогда не понадобится, но каждый раз, когда вы запускаете `python setup.py install` без других параметров, вы её используете.248249Обратите внимание, что установка расширений в другую установку Python не влияет на то, как эти расширения собираются: в частности, при компиляции расширений используются заголовочные файлы Python (`Python.h` и другие) из интерпретатора, который запускает сценарий установки. Именно вы отвечаете за то, чтобы интерпретатор, используемый для запуска установленных таким образом расширений, был совместим с тем, на котором они собирались. Лучший способ это сделать – убедиться, что оба интерпретатора относятся к одной версии Python (возможны разные сборки или просто копии одной и той же сборки). (Разумеется, если ваши `--prefix` и `--exec-prefix` вообще не указывают на другую установку Python, это не имеет значения.)250251### Альтернативная установка: Windows (префиксная схема)252253В Windows нет понятия домашнего каталога пользователя, и поскольку стандартная установка Python в Windows проще, чем в Unix, параметр `--prefix` традиционно используется для установки дополнительных пакетов в отдельные каталоги.254255```text256python setup.py install --prefix="\Temp\Python"257```258259для установки модулей в каталог `\Temp\Python` на текущем диске.260261Базовый каталог установки задаётся параметром `--prefix`. Параметр `--exec-prefix` в Windows не поддерживается, поэтому чистые модули Python и модули расширения устанавливаются в одно и то же место. Файлы устанавливаются следующим образом:262263| Тип файла | Каталог установки |264| --- | --- |265| Модули | `prefix\Lib\site-packages` |266| Скрипты | `prefix\Scripts` |267| Данные | `prefix` |268| Заголовочные файлы C | `prefix\Include{distname}` |269270## Пользовательская установка271272Иногда описанные в разделе [Alternate Installation](https://python-all.ru/3.5/install/index.html#inst-alt-install) схемы альтернативной установки не делают того, что нужно. Возможно, вы хотите подправить всего один-два каталога, оставив всё остальное в том же базовом каталоге, или полностью переопределить схему установки. В любом случае вы создаёте *пользовательскую схему установки*.273274Чтобы создать пользовательскую схему установки, возьмите одну из альтернативных схем и переопределите некоторые каталоги установки для разных типов файлов с помощью следующих параметров:275276| Тип файла | Переопределяющий параметр |277| --- | --- |278| Модули Python | `--install-purelib` |279| Модули расширения | `--install-platlib` |280| Все модули | `--install-lib` |281| Скрипты | `--install-scripts` |282| Данные | `--install-data` |283| Заголовочные файлы C | `--install-headers` |284285Эти опции переопределения могут быть относительными, абсолютными, или явно заданными в терминах одного из базовых каталогов установки. (Существует два базовых каталога установки, и обычно они совпадают – они различаются только при использовании схемы префиксов Unix и указании различных `--prefix` и `--exec-prefix`; использование `--install-lib` переопределит значения, вычисленные или заданные для `--install-purelib` и `--install-platlib`, и рекомендуется для схем, которые не делают различий между модулями Python и модулями расширения.)286287Например, вы устанавливаете дистрибутив модулей в свой домашний каталог в Unix, но хотите, чтобы скрипты помещались в `~/scripts`, а не в `~/bin`. Как и следовало ожидать, это можно сделать с помощью параметра `--install-scripts`. В данном случае разумнее всего указать относительный путь, который будет интерпретироваться относительно базового каталога установки (в данном случае – вашего домашнего каталога):288289```text290python setup.py install --home=~ --install-scripts=scripts291```292293Другой пример для Unix: допустим, установка Python была собрана и установлена с префиксом `/usr/local/python`, поэтому при стандартной установке скрипты окажутся в `/usr/local/python/bin`. Чтобы поместить их в `/usr/local/bin`, следует указать этот абсолютный путь для параметра `--install-scripts`:294295```text296python setup.py install --install-scripts=/usr/local/bin297```298299(Выполняется установка с использованием «схемы префикса», где префикс – это путь установки интерпретатора Python – `/usr/local/python` в данном случае.)300301Если вы сопровождаете Python в Windows, вам может потребоваться, чтобы сторонние модули располагались в подкаталоге `prefix`, а не прямо в самом `prefix`. Это почти так же просто, как настройка каталога установки скриптов – вам просто нужно помнить, что есть два типа модулей, о которых стоит беспокоиться, модули Python и модули расширения, которые удобно можно контролировать одной опцией:302303```text304python setup.py install --install-lib=Site305```306307Указанный каталог установки указывается относительно `prefix`. Разумеется, также нужно убедиться, что этот каталог находится в пути поиска модулей Python, например, поместив файл `.pth` в site-каталог (см. [`site`](https://python-all.ru/3.5/library/site.html#module-site)). О том, как изменить путь поиска Python, рассказано в разделе [Изменение пути поиска Python](https://python-all.ru/3.5/install/index.html#inst-search-path).308309Если требуется определить полную схему установки, нужно просто указать все параметры каталогов установки. Рекомендуется задавать относительные пути; например, если все файлы, связанные с модулями Python, должны находиться в каталоге `python` в вашем домашнем каталоге, и для каждой платформы, с которой этот домашний каталог используется, нужен отдельный каталог, можно определить следующую схему установки:310311```text312python setup.py install --home=~ \313                        --install-purelib=python/lib \314                        --install-platlib=python/lib.$PLAT \315                        --install-scripts=python/scripts316                        --install-data=python/data317```318319или, что то же самое,320321```text322python setup.py install --home=~/python \323                        --install-purelib=lib \324                        --install-platlib='lib.$PLAT' \325                        --install-scripts=scripts326                        --install-data=data327```328329`$PLAT` не (обязательно) является переменной окружения – он будет развёрнут Distutils при разборе параметров командной строки, так же как и при разборе файлов конфигурации.330331Очевидно, указывать полную схему установки при каждой установке нового дистрибутива модуля было бы очень утомительно. Поэтому эти параметры можно поместить в файл конфигурации Distutils (см. раздел [Файлы конфигурации Distutils](https://python-all.ru/3.5/install/index.html#inst-config-files)):332333```text334[install]335install-base=$HOME336install-purelib=python/lib337install-platlib=python/lib.$PLAT338install-scripts=python/scripts339install-data=python/data340```341342или, что то же самое,343344```text345[install]346install-base=$HOME/python347install-purelib=lib348install-platlib=lib.$PLAT349install-scripts=scripts350install-data=data351```352353Обратите внимание, что эти два варианта *не* эквивалентны, если при запуске скрипта setup указать другой базовый каталог установки. Например,354355```text356python setup.py install --install-base=/tmp357```358359установит чистые модули в `/tmp/python/lib` в первом случае и в `/tmp/lib` во втором. (Для второго случая, вероятно, следует указать базовый каталог установки `/tmp/python`.)360361Вероятно, вы заметили использование `$HOME` и `$PLAT` в примере входного файла конфигурации. Это переменные конфигурации Distutils, которые сильно напоминают переменные окружения. На самом деле, переменные окружения можно использовать в файлах конфигурации на платформах, где они есть, но Distutils дополнительно определяет несколько дополнительных переменных, которых может не быть в вашем окружении, например `$PLAT`. (И, конечно, в системах без переменных окружения, таких как Mac OS 9, переменные конфигурации, предоставляемые Distutils, являются единственными, которые можно использовать.) Подробнее см. раздел [Файлы конфигурации Distutils](https://python-all.ru/3.5/install/index.html#inst-config-files).362363> **Примечание**364>365> Когда [виртуальное окружение](https://python-all.ru/3.5/library/venv.html#venv-def) активировано, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.366367### Изменение пути поиска Python368369Когда интерпретатор Python выполняет инструкцию [`import`](https://python-all.ru/3.5/reference/simple_stmts.html#import), он ищет как код Python, так и модули расширения по пути поиска. Значение пути по умолчанию задаётся в двоичном файле Python при сборке интерпретатора. Узнать этот путь можно, импортировав модуль [`sys`](https://python-all.ru/3.5/library/sys.html#module-sys) и выведя значение `sys.path`.370371```text372$ python373Python 2.2 (#11, Oct  3 2002, 13:31:27)374[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2375Type "help", "copyright", "credits" or "license" for more information.376>>> import sys377>>> sys.path378['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',379 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',380 '/usr/local/lib/python2.3/site-packages']381>>>382```383384Пустая строка в `sys.path` обозначает текущий рабочий каталог.385386Обычная практика для локально установленных пакетов – помещать их в каталог `…/site-packages/`, но может потребоваться установить Python-модули в произвольный каталог. Например, на вашем сайте может быть принято хранить всё программное обеспечение, связанное с веб-сервером, в каталоге `/www`. Тогда дополнительные модули Python могут находиться в `/www/python`, и чтобы импортировать их, этот каталог должен быть добавлен в `sys.path`. Есть несколько различных способов добавить каталог.387388Самый удобный способ – добавить файл конфигурации пути в каталог, уже находящийся в пути поиска Python, обычно в каталог `.../site-packages/`. Файлы конфигурации пути имеют расширение `.pth`, и каждая строка должна содержать один путь, который будет добавлен в `sys.path`. (Поскольку новые пути добавляются в `sys.path`, модули в добавленных каталогах не переопределяют стандартные модули. Это означает, что этот механизм нельзя использовать для установки фиксированных версий стандартных модулей.)389390Пути могут быть абсолютными или относительными; в последнем случае они задаются относительно каталога, содержащего файл `.pth`. Дополнительную информацию см. в документации модуля [`site`](https://python-all.ru/3.5/library/site.html#module-site).391392Чуть менее удобный способ – отредактировать файл `site.py` в стандартной библиотеке Python и изменить `sys.path`. `site.py` автоматически импортируется при запуске интерпретатора Python, если не указан ключ [`-S`](https://python-all.ru/3.5/using/cmdline.html#id3), отключающий это поведение. Поэтому можно просто отредактировать `site.py` и добавить в него две строки:393394```text395import sys396sys.path.append('/www/python/')397```398399Однако если переустановить ту же самую мажорную версию Python (например, при обновлении с 2.2 до 2.2.2), `site.py` будет перезаписан стандартной версией. Перед выполнением установки придётся запомнить, что он был изменён, и сохранить копию.400401Существуют две переменные окружения, которые могут изменить `sys.path`. [`PYTHONHOME`](https://python-all.ru/3.5/using/cmdline.html#envvar-PYTHONHOME) задаёт альтернативное значение префикса установки Python. Например, если [`PYTHONHOME`](https://python-all.ru/3.5/using/cmdline.html#envvar-PYTHONHOME) установлена в `/www/python`, путь поиска будет установлен в `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`.402403Переменная [`PYTHONPATH`](https://python-all.ru/3.5/using/cmdline.html#envvar-PYTHONPATH) может быть установлена в список путей, которые будут добавлены в начало `sys.path`. Например, если [`PYTHONPATH`](https://python-all.ru/3.5/using/cmdline.html#envvar-PYTHONPATH) установлена в `/www/python:/opt/py`, путь поиска начнётся с `['/www/python', '/opt/py']`. (Обратите внимание: каталоги должны существовать, чтобы быть добавленными в `sys.path`; модуль [`site`](https://python-all.ru/3.5/library/site.html#module-site) удаляет несуществующие пути.)404405Наконец, `sys.path` – это обычный список Python, поэтому любое приложение Python может изменять его, добавляя или удаляя записи.406407## Файлы конфигурации Distutils408409Как упоминалось выше, файлы конфигурации Distutils можно использовать для сохранения личных настроек или настроек сайта для любых параметров Distutils. То есть любой параметр любой команды может быть сохранён в одном из двух или трёх (в зависимости от платформы) файлов конфигурации, которые будут обрабатываться до разбора командной строки. Это означает, что файлы конфигурации переопределяют значения по умолчанию, а командная строка, в свою очередь, переопределяет файлы конфигурации. Кроме того, если применяется несколько файлов конфигурации, значения из «более ранних» файлов переопределяются «более поздними».410411### Расположение и имена файлов конфигурации412413Имена и расположение конфигурационных файлов немного различаются в зависимости от платформы. На Unix и Mac OS X три конфигурационных файла (в порядке их обработки):414415| Тип файла | Расположение и имя файла | Примечания |416| --- | --- | --- |417| системный | `prefix/lib/pythonver/distutils/distutils.cfg` | (1) |418| личный | `$HOME/.pydistutils.cfg` | (2) |419| локальный | `setup.cfg` | (3) |420421А в Windows файлы конфигурации:422423| Тип файла | Расположение и имя файла | Примечания |424| --- | --- | --- |425| системный | `prefix\Lib\distutils\distutils.cfg` | (4) |426| личный | `%HOME%\pydistutils.cfg` | (5) |427| локальный | `setup.cfg` | (3) |428429На всех платформах «личный» файл можно временно отключить, передав параметр *–no-user-cfg*.430431Примечания:4324331. Строго говоря, общесистемный файл конфигурации находится в каталоге, где установлен Distutils; в Python 1.6 и новее в Unix это так, как показано. В Python 1.5.2 Distutils обычно устанавливается в `prefix/lib/python1.5/site-packages/distutils`, поэтому при использовании Python 1.5.2 системный файл конфигурации следует размещать там.4342. В Unix, если переменная окружения `HOME` не определена, домашний каталог пользователя определяется с помощью функции `getpwuid()` из стандартного модуля [`pwd`](https://python-all.ru/3.5/library/pwd.html#module-pwd). Это делает функция [`os.path.expanduser()`](https://python-all.ru/3.5/library/os.path.html#os.path.expanduser), используемая в Distutils.4353. То есть в текущем каталоге (обычно там, где находится сценарий setup).4364. (См. также примечание (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.4375. В Windows, если переменная окружения `HOME` не определена, то перебираются `USERPROFILE`, `HOMEDRIVE` и `HOMEPATH`. Это делается функцией [`os.path.expanduser()`](https://python-all.ru/3.5/library/os.path.html#os.path.expanduser), используемой в Distutils.438439### Синтаксис файлов конфигурации440441Все файлы конфигурации Distutils имеют одинаковый синтаксис. Файлы конфигурации разбиты на разделы. Для каждой команды Distutils есть отдельный раздел, плюс раздел `global` для глобальных параметров, влияющих на все команды. Каждый раздел содержит по одному параметру на строку, задаваемому в формате `option=value`.442443Например, ниже приведён полный файл конфигурации, который заставляет все команды по умолчанию работать в тихом режиме:444445```text446[global]447verbose=0448```449450Если этот файл установлен как системный конфигурационный, он влияет на обработку любых дистрибутивов модулей Python любым пользователем в данной системе. Если установлен как ваш личный конфигурационный файл (в системах, которые это поддерживают), он влияет только на дистрибутивы модулей, обрабатываемые вами. А если используется как `setup.cfg` для конкретного дистрибутива модуля, то влияет только на этот дистрибутив.451452Можно переопределить каталог «build base» по умолчанию и заставить команды **build\*** всегда принудительно пересобирать все файлы следующим образом:453454```text455[build]456build-base=blib457force=1458```459460что соответствует аргументам командной строки461462```text463python setup.py build --build-base=blib --force464```465466за исключением того, что указание команды **build** в командной строке означает, что эта команда будет выполнена. Включение конкретной команды в файлы конфигурации не имеет такого смысла; это лишь означает, что если команда будет выполнена, то будут применены параметры из файла конфигурации. (Или если будут выполнены другие команды, которые используют её значения, они возьмут значения из файла конфигурации.)467468Полный список параметров для любой команды можно узнать с помощью опции `--help`, например:469470```text471python setup.py build --help472```473474а полный список глобальных параметров – с помощью `--help` без указания команды:475476```text477python setup.py --help478```479480См. также раздел «Справочник» в руководстве «Распространение модулей Python».481482## Сборка расширений: советы и хитрости483484По возможности Distutils стараются использовать информацию о конфигурации, предоставляемую интерпретатором Python, который запускает сценарий `setup.py`. Например, те же флаги компилятора и компоновщика, которые использовались для сборки Python, будут использоваться и для компиляции расширений. Обычно это работает хорошо, но в сложных ситуациях может быть неприемлемо. В этом разделе рассматривается, как переопределить стандартное поведение Distutils.485486### Настройка флагов компилятора/компоновщика487488Компиляция расширения Python, написанного на C или C++, иногда требует указания пользовательских флагов для компилятора и компоновщика, чтобы использовать конкретную библиотеку или создать особый вид объектного кода. Особенно это актуально, если расширение не тестировалось на вашей платформе или вы пытаетесь кросс-компилировать Python.489490В самом общем случае автор расширения мог предвидеть, что компиляция расширений будет сложной, и предоставил файл `Setup` для редактирования. Скорее всего, это делается только тогда, когда дистрибутив модуля содержит много отдельных модулей расширения или они часто требуют сложных наборов флагов компилятора для работы.491492Файл `Setup`, если присутствует, разбирается для получения списка расширений для сборки. Каждая строка в `Setup` описывает один модуль. Строки имеют следующую структуру:493494```text495module ... [sourcefile ...] [cpparg ...] [library ...]496```497498Рассмотрим каждое поле по порядку.499500- *module* – это имя собираемого модуля расширения, и оно должно быть корректным идентификатором Python. Просто изменить его, чтобы переименовать модуль, нельзя (потребуется также править исходный код), поэтому его следует оставить как есть.501- *sourcefile* – это любой файл, который, по крайней мере судя по имени, может быть исходным кодом. Файлы с расширением `.c` считаются написанными на C, файлы с расширениями `.C`, `.cc` и `.c++` – на C++, а файлы с расширениями `.m` или `.mm` – на Objective C.502- *cpparg* – это аргумент для препроцессора C, и им может быть всё, что начинается с `-I`, `-D`, `-U` или `-C`.503- *library* – это всё, что заканчивается на `.a` или начинается с `-l` или `-L`.504505Если для вашей платформы требуется особая библиотека, её можно добавить, отредактировав файл `Setup` и запустив `python setup.py build`. Например, если модуль, заданный строкой506507```text508foo foomodule.c509```510511должен быть слинкован с математической библиотекой `libm.a` на вашей платформе, просто добавьте `-lm` в строку:512513```text514foo foomodule.c -lm515```516517Произвольные опции для компилятора или компоновщика можно передать с помощью опций `-Xcompiler` *аргумент* и `-Xlinker` *аргумент*:518519```text520foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm521```522523Следующая после `-Xcompiler` и `-Xlinker` опция будет добавлена в соответствующую командную строку, поэтому в приведённом примере компилятор получит опцию `-o32`, а компоновщик – `-shared`. Если опция компилятора требует аргумента, придётся указать несколько опций `-Xcompiler`; например, чтобы передать `-x c++`, файл `Setup` должен содержать `-Xcompiler -x -Xcompiler c++`.524525Флаги компилятора можно также задать через переменную окружения `CFLAGS`. Если она установлена, содержимое `CFLAGS` будет добавлено к флагам компилятора, указанным в файле `Setup`.526527### Использование компиляторов не от Microsoft в Windows528529#### Borland/CodeGear C++530531В этом подразделе описаны необходимые шаги для использования Distutils с компилятором Borland C++ версии 5.5. Прежде всего, необходимо знать, что формат объектных файлов Borland (OMF) отличается от формата, используемого в версии Python, которую можно загрузить с веб-сайтов Python или ActiveState. (Python собирается с помощью Microsoft Visual C++, который использует COFF в качестве формата объектных файлов.) По этой причине необходимо преобразовать библиотеку Python `python25.lib` в формат Borland. Это можно сделать следующим образом:532533```text534coff2omf python25.lib python25_bcpp.lib535```536537Программа `coff2omf` поставляется с компилятором Borland. Файл `python25.lib` находится в каталоге `Libs` вашей установки Python. Если ваше расширение использует другие библиотеки (zlib, …), их тоже нужно преобразовать.538539Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.540541Как Distutils умудряется использовать эти библиотеки с изменёнными именами? Если расширению нужна библиотека (например, `foo`), Distutils сначала проверяет, найдётся ли библиотека с суффиксом `_bcpp` (например, `foo_bcpp.lib`), и использует её. Если такой специальной библиотеки нет, используется имя по умолчанию (`foo.lib`). [\[1\]](https://python-all.ru/3.5/install/index.html#id4)542543Чтобы Distutils собрал ваше расширение с Borland C++, введите:544545```text546python setup.py build --compiler=bcpp547```548549Если вы хотите использовать компилятор Borland C++ по умолчанию, это можно указать в вашем личном или общесистемном конфигурационном файле Distutils (см. раздел [Distutils Configuration Files](https://python-all.ru/3.5/install/index.html#inst-config-files)).550551> **См. также**552>553> **[Компилятор C++Builder](https://python-all.ru/3.5/install/index.html)**554>555> Информация о бесплатном компиляторе C++ от Borland, включая ссылки на страницы загрузки.556>557> **[Создание расширений Python с помощью бесплатного компилятора Borland](https://python-all.ru/3.5/install/index.html)**558>559> Документ, описывающий, как использовать бесплатный компилятор C++ командной строки Borland для сборки Python.560561#### GNU C / Cygwin / MinGW562563В этом разделе описаны необходимые шаги для использования Distutils с компиляторами GNU C/C++ в дистрибутивах Cygwin и MinGW. [\[2\]](https://python-all.ru/3.5/install/index.html#id5) Для интерпретатора Python, собранного с помощью Cygwin, всё должно работать без каких-либо дополнительных действий.564565Не все расширения можно собрать с MinGW или Cygwin, но многие можно. Вероятнее всего, не будут работать расширения, использующие C++ или зависящие от расширений Microsoft Visual C.566567Чтобы Distutils собрал ваше расширение с Cygwin, введите:568569```text570python setup.py build --compiler=cygwin571```572573а для Cygwin в режиме no-cygwin [\[3\]](https://python-all.ru/3.5/install/index.html#id6) или для MinGW введите:574575```text576python setup.py build --compiler=mingw32577```578579Если вы хотите использовать любую из этих опций/компиляторов по умолчанию, стоит записать это в ваш личный или общесистемный конфигурационный файл Distutils (см. раздел [Distutils Configuration Files](https://python-all.ru/3.5/install/index.html#inst-config-files)).580581##### Старые версии Python и MinGW582583Следующие инструкции применимы только в том случае, если вы используете версию Python ниже 2.4.1 с MinGW ниже 3.0.0 (с binutils-2.13.90-20030111-1).584585Эти компиляторы требуют некоторых специальных библиотек. Эта задача сложнее, чем для Borland C++, потому что нет программы для преобразования библиотеки. Сначала нужно создать список символов, которые экспортирует DLL Python. (Хорошую программу для этой задачи можно найти на [https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/](https://python-all.ru/3.5/install/index.html)).586587```text588pexports python25.dll >python25.def589```590591Расположение установленного `python25.dll` зависит от параметров установки, версии и языка Windows. При установке «только для меня» он будет находиться в корневом каталоге установки. При общей установке – в системном каталоге.592593Затем на основе этой информации можно создать импортную библиотеку для gcc.594595```text596/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a597```598599Полученную библиотеку нужно поместить в тот же каталог, что и `python25.lib`. (Обычно это каталог `libs` в каталоге установки Python.)600601Если ваше расширение использует другие библиотеки (zlib,…), их, возможно, тоже придётся преобразовать. Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.602603> **См. также**604>605> **[Сборка модулей Python на платформе MS Windows с помощью MinGW](https://python-all.ru/3.5/install/index.html)**606>607> Информация о сборке необходимых библиотек для окружения MinGW.608609Сноски610611| [\[1\]](https://python-all.ru/3.5/install/index.html#id1) | Это также означает, что можно заменить все существующие COFF-библиотеки на OMF-библиотеки с теми же именами. |612| --- | --- |613614| [\[2\]](https://python-all.ru/3.5/install/index.html#id2) | Проверьте [https://www.sourceware.org/cygwin/](https://python-all.ru/3.5/install/index.html) и [http://www.mingw.org/](https://python-all.ru/3.5/install/index.html) для получения дополнительной информации |615| --- | --- |616617| [\[3\]](https://python-all.ru/3.5/install/index.html#id3) | В этом случае эмуляция POSIX недоступна, но и необходимость в `cygwin1.dll` отпадает. |618| --- | --- |619