index.md
1> **Источник:** https://python-all.ru/3.4/install/index.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Установка модулей Python (устаревшая версия)89| Автор: | Greg Ward |10| --- | --- |1112В этом документе описываются утилиты распространения Python (Distutils) с точки зрения конечного пользователя: как расширить возможности стандартной установки Python, собрав и установив сторонние модули и расширения Python.1314> **Примечание**15>16> Это руководство охватывает только основные инструменты для сборки и распространения расширений, входящие в состав этой версии Python. Сторонние инструменты предлагают более простые и безопасные альтернативы. Для получения дополнительной информации обратитесь к [разделу с краткими рекомендациями](https://python-all.ru/3.4/install/index.html) в руководстве пользователя по упаковке Python.1718## Введение1920Хотя обширная стандартная библиотека Python покрывает многие потребности программирования, часто наступает момент, когда необходимо добавить новую функциональность в установку Python в виде сторонних модулей. Это может понадобиться для поддержки собственных программ или для использования приложения, написанного на Python.2122В прошлом было мало поддержки для добавления сторонних модулей в существующую установку Python. С появлением утилит распространения Python (сокращённо Distutils) в Python 2.0 это изменилось.2324Этот документ предназначен в первую очередь для тех, кому нужно установить сторонние модули Python: конечных пользователей и системных администраторов, которым просто нужно запустить какое-нибудь Python-приложение, а также опытных программистов Python, желающих добавить новые инструменты в свой арсенал. Для чтения этого документа не требуется знать Python; будут лишь краткие экскурсы в интерактивный режим Python для изучения вашей установки, но не более. Если вы ищете информацию о том, как распространять собственные модули Python, чтобы другие могли их использовать, обратитесь к руководству [*Distributing Python Modules (Legacy version)*](https://python-all.ru/3.4/distutils/index.html#distutils-index). Также может быть полезна [*отладка сценария установки*](https://python-all.ru/3.4/distutils/setupscript.html#debug-setup-script).2526### Идеальный случай: простая установка2728В идеальном случае кто-то подготовит специальную версию распространяемого модуля, который вы хотите установить, ориентированную именно на вашу платформу, и устанавливаемую как любое другое программное обеспечение на вашей платформе. Например, разработчик модуля может предоставить исполняемый установщик для пользователей Windows, пакет RPM для пользователей Linux-систем на основе RPM (Red Hat, SuSE, Mandrake и многих других), пакет Debian для пользователей систем на основе Debian и так далее.2930В таком случае вы загружаете установщик, подходящий для вашей платформы, и делаете очевидное: запускаете его, если это исполняемый установщик, `rpm --install`, если это RPM, и т.д. Вам не нужно запускать Python или сценарий установки, не нужно ничего компилировать – возможно, вам даже не придётся читать инструкции (хотя это всегда полезно).3132Конечно, не всегда всё так просто. Возможно, вас заинтересует распространяемый модуль, для которого нет простого установщика для вашей платформы. В этом случае придётся начать с исходного дистрибутива, выпущенного автором или сопровождающим модуля. Установка из исходного дистрибутива не слишком сложна, если модули упакованы стандартным образом. Основная часть этого документа посвящена сборке и установке модулей из стандартных исходных дистрибутивов.3334### Новый стандарт: Distutils3536Если вы загружаете дистрибутив исходного кода модуля, вы довольно быстро можете определить, упакован ли он и распространён стандартным способом, т.е. с помощью Distutils. Во-первых, имя и номер версии дистрибутива будут prominently указаны в имени загруженного архива, например `foo-1.0.tar.gz` или `widget-0.9.7.zip`. Затем архив распакуется в каталог с аналогичным именем: `foo-1.0` или `widget-0.9.7`. Кроме того, дистрибутив будет содержать сценарий установки `setup.py` и файл с именем `README.txt` или, возможно, просто `README`, в котором должно быть объяснено, что сборка и установка дистрибутива модуля – это просто запуск одной команды из терминала:3738```text39python setup.py install40```4142Для Windows эту команду следует запускать из окна командной строки (*Пуск ‣ Стандартные*):4344```text45setup.py install46```4748Если всё это верно, то вы уже знаете, как собрать и установить только что загруженные модули: просто выполните указанную выше команду. Если вам не нужно устанавливать что-либо нестандартным способом или настраивать процесс сборки, эта документация вам по большому счёту не понадобится. Вернее, приведённая выше команда – это всё, что нужно, чтобы обойтись без этого руководства.4950## Стандартная сборка и установка5152Как описано в разделе [*Новый стандарт: Distutils*](https://python-all.ru/3.4/install/index.html#inst-new-standard), сборка и установка распространяемого модуля с помощью Distutils обычно сводится к одной простой команде, выполняемой из терминала:5354```text55python setup.py install56```5758### Различия по платформам5960Команду setup следует всегда запускать из корневого каталога дистрибутива, т.е. из верхнего подкаталога, в который распаковывается дистрибутив исходного кода модуля. Например, если вы только что загрузили дистрибутив исходного кода модуля `foo-1.0.tar.gz` на систему Unix, стандартные действия таковы:6162```text63gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.064cd foo-1.065python setup.py install66```6768На Windows вы, вероятно, загрузите `foo-1.0.zip`. Если вы загрузили архивный файл в `C:\Temp`, то он распакуется в `C:\Temp\foo-1.0`; для распаковки архива можно использовать либо менеджер архивов с графическим интерфейсом (например, WinZip), либо инструмент командной строки (например, **unzip** или **pkunzip**). Затем откройте окно командной строки и выполните:6970```text71cd c:\Temp\foo-1.072python setup.py install73```7475### Разделение процесса на этапы7677Запуск `setup.py install` выполняет сборку и установку всех модулей за один запуск. Если вы предпочитаете работать пошагово – это особенно полезно, когда вы хотите настроить процесс сборки или когда что-то идёт не так, – вы можете использовать сценарий установки для выполнения по одному действию за раз. Это особенно полезно, когда сборку и установку выполняют разные пользователи – например, вы можете собрать дистрибутив модуля и передать его системному администратору для установки (или сделать это самостоятельно, имея привилегии суперпользователя).7879Например, можно выполнить сборку на первом шаге, а установку – на втором, вызвав сценарий setup дважды:8081```text82python setup.py build83python setup.py install84```8586Если вы сделаете это, то заметите, что команда **install** сначала запускает команду **build**, которая в данном случае быстро обнаруживает, что ей нечего делать, поскольку всё в каталоге `build` уже актуально.8788Возможно, разбиение на этапы не понадобится, если вы только устанавливаете модули, загруженные из сети, но это очень удобно для более сложных задач. Если вы начнёте распространять собственные модули и расширения Python, вам придётся часто запускать отдельные команды Distutils самостоятельно.8990### Как работает сборка9192Как было сказано выше, команда **build** отвечает за помещение файлов для установки в *каталог сборки*. По умолчанию это `build` в корне дистрибутива; если вы чрезмерно заботитесь о скорости или хотите сохранить исходное дерево в первозданном виде, вы можете изменить каталог сборки с помощью опции *--build-base*. Например:9394```text95python setup.py build --build-base=/path/to/pybuild/foo-1.096```9798(Или это можно сделать постоянно с помощью директивы в системном или личном конфигурационном файле Distutils; см. раздел [*Конфигурационные файлы Distutils*](https://python-all.ru/3.4/install/index.html#inst-config-files).) Обычно в этом нет необходимости.99100Структура дерева сборки по умолчанию выглядит следующим образом:101102```text103--- build/ --- lib/104or105--- build/ --- lib.<plat>/106 temp.<plat>/107```108109где `<plat>` разворачивается в краткое описание текущей ОС/аппаратной платформы и версии Python. Первая форма, только с каталогом `lib`, используется для «чистых дистрибутивов модулей» – то есть дистрибутивов модулей, содержащих только чистые модули Python. Если дистрибутив модуля содержит какие-либо расширения (модули, написанные на C/C++), то используется вторая форма, с двумя каталогами `<plat>`. В этом случае каталог `temp.plat` содержит временные файлы, созданные в процессе компиляции/компоновки, которые фактически не устанавливаются. В любом случае, каталог `lib` (или `lib.plat`) содержит все модули Python (чистые Python и расширения), которые будут установлены.110111В будущем будут добавлены дополнительные каталоги для размещения скриптов Python, документации, исполняемых файлов и всего остального, что необходимо для установки модулей и приложений Python.112113### Как работает установка114115После выполнения команды **build** (независимо от того, запускаете ли вы её явно, или команда **install** делает это за вас) работа команды **install** относительно проста: всё, что ей нужно сделать, – скопировать всё из `build/lib` (или `build/lib.plat`) в выбранный вами каталог установки.116117Если вы не указываете каталог установки – т.е. просто запускаете `setup.py install`, – то команда **install** устанавливает в стандартное расположение для сторонних модулей Python. Это расположение зависит от платформы и от того, как вы собрали/установили сам Python. На Unix (и Mac OS X, которая также основана на Unix) оно также зависит от того, является ли устанавливаемый дистрибутив модуля чистым Python или содержит расширения («нечистый»):118119| Платформа | Стандартное расположение установки | Значение по умолчанию | Примечания |120| --- | --- | --- | --- |121| Unix (чистый) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |122| Unix (не чистый) | `exec-prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1) |123| Windows | `prefix\Lib\site-packages` | `C:\PythonXY\Lib\site-packages` | (2) |124125Примечания:1261271. Большинство дистрибутивов Linux включают Python как стандартную часть системы, поэтому `prefix` и `exec-prefix` обычно оба равны `/usr` на Linux. Если вы собираете Python самостоятельно на Linux (или любой Unix-подобной системе), значения по умолчанию для `prefix` и `exec-prefix` равны `/usr/local`.1282. Каталог установки по умолчанию на Windows был `C:\Program Files\Python` в Python 1.6a1, 1.5.2 и более ранних версиях.129130`prefix` и `exec-prefix` обозначают каталоги, в которые установлен Python и где он ищет свои библиотеки во время выполнения. Они всегда одинаковы в Windows и очень часто одинаковы в Unix и Mac OS X. Вы можете узнать, какие значения `prefix` и `exec-prefix` использует ваша установка Python, запустив Python в интерактивном режиме и введя несколько простых команд. В Unix просто введите `python` в приглашении оболочки. В Windows выберите *Пуск ‣ Программы ‣ Python X.Y ‣ Python (командная строка)*. После запуска интерпретатора введите код Python в приглашении. Например, в моей системе Linux я ввожу три оператора Python, показанные ниже, и получаю вывод, как показано, чтобы узнать свои `prefix` и `exec-prefix`:131132```text133Python 2.4 (#26, Aug 7 2004, 17:19:02)134Type "help", "copyright", "credits" or "license" for more information.135>>> import sys136>>> sys.prefix137'/usr'138>>> sys.exec_prefix139'/usr'140```141142В этом документе используются несколько других плейсхолдеров: `X.Y` обозначает версию Python, например `3.2`; `abiflags` будет заменён на значение [`sys.abiflags`](https://python-all.ru/3.4/library/sys.html#sys.abiflags) или пустую строку для платформ, не определяющих флаги ABI; `distname` будет заменён на имя устанавливаемого дистрибутива модуля. Точки и регистр важны в путях; например, значение, использующее `python3.2` в UNIX, обычно использует `Python32` в Windows.143144Если вы не хотите устанавливать модули в стандартное расположение или у вас нет прав на запись туда, обратитесь к разделу [*Альтернативная установка*](https://python-all.ru/3.4/install/index.html#inst-alt-install). Если вы хотите более глубоко настроить каталоги установки, см. раздел [*Пользовательская установка*](https://python-all.ru/3.4/install/index.html#inst-custom-install).145146## Альтернативная установка147148Часто необходимо или желательно устанавливать модули в расположение, отличное от стандартного для сторонних модулей Python. Например, в системе Unix у вас может не быть прав на запись в стандартный каталог сторонних модулей. Или вы можете захотеть опробовать модуль, прежде чем делать его стандартной частью вашей локальной установки Python. Это особенно актуально при обновлении уже установленного дистрибутива: вы хотите убедиться, что существующая база скриптов продолжает работать с новой версией, прежде чем выполнять обновление.149150Команда **install** из пакета Distutils предназначена для простой и безболезненной установки дистрибутивов модулей в альтернативное расположение. Основная идея: указывается базовый каталог для установки, а команда **install** выбирает набор каталогов (называемый *схемой установки*) внутри этого базового каталога, куда будут установлены файлы. Детали различаются в зависимости от платформы, поэтому следует прочитать соответствующий раздел.151152Обратите внимание, что различные альтернативные схемы установки являются взаимоисключающими: вы можете передать `--user`, или `--home`, или `--prefix` и `--exec-prefix`, или `--install-base` и `--install-platbase`, но нельзя комбинировать параметры из разных групп.153154### Альтернативная установка: схема пользователя155156Эта схема предназначена для наиболее удобного решения для пользователей, у которых нет прав на запись в глобальный каталог site-packages или которые не хотят в него устанавливать. Она включается простым параметром:157158```text159python setup.py install --user160```161162Файлы будут установлены в подкаталоги [`site.USER_BASE`](https://python-all.ru/3.4/library/site.html#site.USER_BASE) (далее обозначаемый как `userbase`). Эта схема устанавливает чистые модули Python и модули-расширения в одно и то же место (также известное как [`site.USER_SITE`](https://python-all.ru/3.4/library/site.html#site.USER_SITE)). Ниже приведены значения для UNIX, включая Mac OS X:163164| Тип файла | Каталог установки |165| --- | --- |166| Модули | `userbase/lib/pythonX.Y/site-packages` |167| Скрипты | `userbase/bin` |168| Данные | `userbase` |169| Заголовочные файлы C | `userbase/include/pythonX.Yabiflags/distname` |170171А вот значения, используемые в Windows:172173| Тип файла | Каталог установки |174| --- | --- |175| Модули | `userbase\PythonXY\site-packages` |176| Скрипты | `userbase\Scripts` |177| Данные | `userbase` |178| Заголовочные файлы C | `userbase\PythonXY\Include\distname` |179180Преимущество использования этой схемы по сравнению с другими, описанными ниже, заключается в том, что каталог site-packages пользователя при нормальных условиях всегда включён в [`sys.path`](https://python-all.ru/3.4/library/sys.html#sys.path) (см. [`site`](https://python-all.ru/3.4/library/site.html#module-site) для дополнительной информации), а это значит, что после запуска сценария `setup.py` не требуется выполнять никаких дополнительных действий для завершения установки.181182Команда **build\_ext** также имеет опцию `--user`, которая добавляет `userbase/include` в путь поиска компилятора для заголовочных файлов и `userbase/lib` в путь поиска компилятора для библиотек, а также в путь поиска во время выполнения для разделяемых C-библиотек (rpath).183184### Альтернативная установка: схема home185186Идея «домашней схемы» (home scheme) заключается в том, что вы создаёте и поддерживаете личное хранилище модулей Python. Название этой схемы происходит от идеи «домашнего» каталога в Unix, поскольку для пользователя Unix нередко сделать свой домашний каталог похожим по структуре на `/usr/` или `/usr/local/`. Эта схема может использоваться кем угодно, независимо от операционной системы, для которой производится установка.187188Установка нового дистрибутива модуля так же проста, как189190```text191python setup.py install --home=<dir>192```193194где можно указать любой каталог для опции *--home*. В Unix ленивые наборщики могут просто ввести тильду (`~`); команда **install** раскроет её в домашний каталог:195196```text197python setup.py install --home=~198```199200Чтобы Python мог найти дистрибутивы, установленные с помощью этой схемы, возможно, потребуется [*изменить путь поиска Python*](https://python-all.ru/3.4/install/index.html#inst-search-path) или отредактировать `sitecustomize` (см. [`site`](https://python-all.ru/3.4/library/site.html#module-site)) для вызова [`site.addsitedir()`](https://python-all.ru/3.4/library/site.html#site.addsitedir) или изменить [`sys.path`](https://python-all.ru/3.4/library/sys.html#sys.path).201202Опция *--home* задаёт базовый каталог установки. Файлы устанавливаются в следующие подкаталоги относительно базового каталога:203204| Тип файла | Каталог установки |205| --- | --- |206| Модули | `home/lib/python` |207| Скрипты | `home/bin` |208| Данные | `home` |209| Заголовочные файлы C | `home/include/python/distname` |210211(Мысленно замените косые черты на обратные, если вы работаете в Windows.)212213### Альтернативная установка: Unix (схема prefix)214215Префиксная схема полезна, если вы хотите использовать одну установку Python для сборки/установки (т.е. для запуска setup-скрипта), но устанавливать модули в каталог сторонних модулей другой установки Python (или того, что выглядит как другая установка Python). Если это звучит немного необычно – так и есть, поэтому сначала идут схемы пользователя и домашняя. Однако есть как минимум два известных случая, где префиксная схема окажется полезной.216217Во-первых, учтите, что многие дистрибутивы Linux помещают Python в `/usr`, а не в более традиционный `/usr/local`. Это вполне оправданно, поскольку в таких случаях Python является частью «системы», а не локальным дополнением. Однако при установке модулей Python из исходных кодов, вероятно, потребуется поместить их в `/usr/local/lib/python2.X`, а не в `/usr/lib/python2.X`. Это можно сделать с помощью218219```text220/usr/bin/python setup.py install --prefix=/usr/local221```222223Другая возможность – сетевая файловая система, где имя, используемое для записи в удалённый каталог, отличается от имени, используемого для чтения. Например, интерпретатор Python, доступный как `/usr/local/bin/python`, может искать модули в `/usr/local/lib/python2.X`, но эти модули придётся устанавливать, скажем, в `/mnt/@server/export/lib/python2.X`. Это можно сделать с помощью224225```text226/usr/local/bin/python setup.py install --prefix=/mnt/@server/export227```228229В любом случае, опция *--prefix* задаёт базовый каталог установки, а опция *--exec-prefix* – платформенно-зависимый базовый каталог установки, который используется для платформенно-зависимых файлов. (В настоящее время это касается только дистрибутивов модулей, не являющихся чисто Python-модулями, но может быть расширено на C-библиотеки, бинарные исполняемые файлы и т.д.) Если *--exec-prefix* не указан, он по умолчанию равен *--prefix*. Файлы устанавливаются следующим образом:230231| Тип файла | Каталог установки |232| --- | --- |233| Модули Python | `prefix/lib/pythonX.Y/site-packages` |234| Модули расширения | `exec-prefix/lib/pythonX.Y/site-packages` |235| Скрипты | `prefix/bin` |236| Данные | `prefix` |237| Заголовочные файлы C | `prefix/include/pythonX.Yabiflags/distname` |238239Не требуется, чтобы *--prefix* или *--exec-prefix* обязательно указывали на альтернативную установку Python; если перечисленные выше каталоги ещё не существуют, они будут созданы во время установки.240241Кстати, настоящая причина, по которой схема префиксов важна, заключается просто в том, что стандартная установка Unix использует схему префиксов, но с *--prefix* и *--exec-prefix*, предоставляемыми самим Python как `sys.prefix` и `sys.exec_prefix`. Таким образом, можно подумать, что схема префиксов никогда не понадобится, но каждый раз при запуске `python setup.py install` без дополнительных опций она используется.242243Обратите внимание, что установка расширений в альтернативную установку Python не влияет на то, как эти расширения собираются. В частности, заголовочные файлы Python (`Python.h` и другие), установленные вместе с интерпретатором Python, используемым для запуска сценария setup, будут использоваться при компиляции расширений. Ответственность за обеспечение совместимости интерпретатора, используемого для запуска расширений, установленных таким образом, с интерпретатором, используемым для их сборки, лежит на вас. Лучший способ сделать это – убедиться, что оба интерпретатора являются одной версией Python (возможно, разными сборками или копиями одной сборки). (Разумеется, если ваши *--prefix* и *--exec-prefix* вовсе не указывают на альтернативную установку Python, это не имеет значения.)244245### Альтернативная установка: Windows (префиксная схема)246247В Windows нет понятия домашнего каталога пользователя, и поскольку стандартная установка Python в Windows проще, чем в Unix, опция *--prefix* традиционно используется для установки дополнительных пакетов в отдельные расположения в Windows.248249```text250python setup.py install --prefix="\Temp\Python"251```252253для установки модулей в каталог `\Temp\Python` на текущем диске.254255Базовый каталог установки задаётся опцией *--prefix*; опция *--exec-prefix* в Windows не поддерживается, что означает, что чистые модули Python и модули расширений устанавливаются в одно и то же место. Файлы устанавливаются следующим образом:256257| Тип файла | Каталог установки |258| --- | --- |259| Модули | `prefix\Lib\site-packages` |260| Скрипты | `prefix\Scripts` |261| Данные | `prefix` |262| Заголовочные файлы C | `prefix\Include\distname` |263264## Пользовательская установка265266Иногда описанные в разделе [*Alternate Installation*](https://python-all.ru/3.4/install/index.html#inst-alt-install) схемы альтернативной установки не делают того, что нужно. Возможно, вы хотите подправить всего один-два каталога, оставив всё остальное в том же базовом каталоге, или полностью переопределить схему установки. В любом случае вы создаёте *пользовательскую схему установки*.267268Чтобы создать пользовательскую схему установки, возьмите одну из альтернативных схем и переопределите некоторые каталоги установки для разных типов файлов с помощью следующих параметров:269270| Тип файла | Переопределяющий параметр |271| --- | --- |272| Модули Python | `--install-purelib` |273| Модули расширения | `--install-platlib` |274| Все модули | `--install-lib` |275| Скрипты | `--install-scripts` |276| Данные | `--install-data` |277| Заголовочные файлы C | `--install-headers` |278279Эти опции переопределения могут быть относительными, абсолютными или явно заданными через одну из базовых директорий установки. (Существует две базовые директории установки, и обычно они совпадают – они различаются только при использовании Unix-схемы «prefix» и при задании разных опций `--prefix` и `--exec-prefix`; использование `--install-lib` переопределяет значения, вычисленные или заданные для `--install-purelib` и `--install-platlib`, и рекомендуется для схем, которые не делают различий между модулями Python и модулями расширения.)280281Например, вы устанавливаете дистрибутив модуля в свою домашнюю директорию в Unix, но хотите, чтобы скрипты оказались в `~/scripts`, а не в `~/bin`. Как и следовало ожидать, эту директорию можно переопределить с помощью опции *--install-scripts*; в данном случае наиболее разумно указать относительный путь, который будет интерпретироваться относительно базовой директории установки (в данном случае вашей домашней директории):282283```text284python setup.py install --home=~ --install-scripts=scripts285```286287Ещё один пример Unix: предположим, ваша установка Python была собрана и установлена с префиксом `/usr/local/python`, так что при стандартной установке скрипты окажутся в `/usr/local/python/bin`. Если вы хотите, чтобы они были в `/usr/local/bin`, нужно указать этот абсолютный путь для опции *--install-scripts*:288289```text290python setup.py install --install-scripts=/usr/local/bin291```292293(Это выполняет установку с использованием «схемы prefix», где префикс соответствует тому, с чем был установлен ваш интерпретатор Python – в данном случае `/usr/local/python`.)294295Если вы поддерживаете Python в Windows, возможно, вы захотите, чтобы сторонние модули находились в поддиректории `prefix`, а не прямо в самом `prefix`. Это почти так же просто, как настройка директории установки скриптов – нужно только помнить, что есть два типа модулей, о которых стоит беспокоиться: модули Python и модули расширения, и оба они удобно управляются одной опцией:296297```text298python setup.py install --install-lib=Site299```300301Указанная директория установки задаётся относительно `prefix`. Разумеется, необходимо также убедиться, что эта директория находится в пути поиска модулей Python, например, поместив файл `.pth` в директорию site (см. [`site`](https://python-all.ru/3.4/library/site.html#module-site)). О том, как изменить путь поиска Python, рассказано в разделе [*Изменение пути поиска Python*](https://python-all.ru/3.4/install/index.html#inst-search-path).302303Если вы хотите определить полную схему установки, достаточно указать все опции директорий установки. Рекомендуется указывать относительные пути; например, если вы хотите хранить все файлы, связанные с модулями Python, в директории `python` в вашей домашней директории и иметь отдельную директорию для каждой платформы, с которой вы используете домашнюю директорию, можно определить следующую схему установки:304305```text306python setup.py install --home=~ \307 --install-purelib=python/lib \308 --install-platlib=python/lib.$PLAT \309 --install-scripts=python/scripts310 --install-data=python/data311```312313или, что то же самое,314315```text316python setup.py install --home=~/python \317 --install-purelib=lib \318 --install-platlib='lib.$PLAT' \319 --install-scripts=scripts320 --install-data=data321```322323`$PLAT` не обязательно является переменной окружения – она будет раскрыта Distutils при разборе ваших опций командной строки, точно так же, как при разборе ваших файлов конфигурации.324325Очевидно, указывать полную схему установки при каждой установке нового дистрибутива модуля было бы очень утомительно. Поэтому эти параметры можно поместить в файл конфигурации Distutils (см. раздел [*Файлы конфигурации Distutils*](https://python-all.ru/3.4/install/index.html#inst-config-files)):326327```text328[install]329install-base=$HOME330install-purelib=python/lib331install-platlib=python/lib.$PLAT332install-scripts=python/scripts333install-data=python/data334```335336или, что то же самое,337338```text339[install]340install-base=$HOME/python341install-purelib=lib342install-platlib=lib.$PLAT343install-scripts=scripts344install-data=data345```346347Обратите внимание, что эти два варианта *не* эквивалентны, если при запуске скрипта setup указать другой базовый каталог установки. Например,348349```text350python setup.py install --install-base=/tmp351```352353установит чистые модули в `/tmp/python/lib` в первом случае и в `/tmp/lib` во втором. (Для второго случая, вероятно, нужно указать базовую директорию установки `/tmp/python`.)354355Вы, вероятно, заметили использование `$HOME` и `$PLAT` в примере входного файла конфигурации. Это переменные конфигурации Distutils, которые очень похожи на переменные окружения. На самом деле вы можете использовать переменные окружения в файлах конфигурации на платформах, где они есть, но Distutils дополнительно определяет несколько дополнительных переменных, которых может не быть в вашем окружении, например, `$PLAT`. (И, конечно, в системах без переменных окружения, таких как Mac OS 9, можно использовать только переменные конфигурации, предоставляемые Distutils.) Подробнее см. в разделе [*Файлы конфигурации Distutils*](https://python-all.ru/3.4/install/index.html#inst-config-files).356357> **Примечание**358>359> Когда [*виртуальное окружение*](https://python-all.ru/3.4/library/venv.html#venv-def) активировано, любые параметры, изменяющие путь установки, будут игнорироваться во всех файлах конфигурации distutils, чтобы предотвратить случайную установку проектов за пределами виртуального окружения.360361### Изменение пути поиска Python362363Когда интерпретатор Python выполняет инструкцию [`import`](https://python-all.ru/3.4/reference/simple_stmts.html#import), он ищет как код Python, так и модули расширения по пути поиска. Значение пути по умолчанию настраивается в двоичном файле Python при сборке интерпретатора. Узнать этот путь можно, импортировав модуль [`sys`](https://python-all.ru/3.4/library/sys.html#module-sys) и выведя значение `sys.path`.364365```text366$ python367Python 2.2 (#11, Oct 3 2002, 13:31:27)368[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2369Type "help", "copyright", "credits" or "license" for more information.370>>> import sys371>>> sys.path372['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',373 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',374 '/usr/local/lib/python2.3/site-packages']375>>>376```377378Пустая строка в `sys.path` обозначает текущую рабочую директорию.379380Обычно для локально устанавливаемых пакетов принято помещать их в директорию `.../site-packages/`, но вы можете захотеть установить модули Python в произвольную директорию. Например, в вашей организации может быть принято хранить всё программное обеспечение, связанное с веб-сервером, в `/www`. Дополнительные модули Python тогда могут размещаться в `/www/python`, и для их импорта эту директорию необходимо добавить в `sys.path`. Существует несколько способов добавить директорию.381382Самый удобный способ – добавить файл конфигурации путей в директорию, которая уже находится в пути Python, обычно в директорию `.../site-packages/`. Файлы конфигурации путей имеют расширение `.pth`, и каждая строка должна содержать один путь, который будет добавлен в `sys.path`. (Поскольку новые пути добавляются в конец `sys.path`, модули из добавленных директорий не переопределяют стандартные модули. Это означает, что этот механизм нельзя использовать для установки фиксированных версий стандартных модулей.)383384Пути могут быть абсолютными или относительными; в последнем случае они указываются относительно директории, содержащей файл `.pth`. Дополнительную информацию см. в документации модуля [`site`](https://python-all.ru/3.4/library/site.html#module-site).385386Чуть менее удобный способ – отредактировать файл `site.py` в стандартной библиотеке Python и изменить `sys.path`. Файл `site.py` автоматически импортируется при запуске интерпретатора Python, если только не указан ключ [*-S*](https://python-all.ru/3.4/using/cmdline.html#cmdoption-S), отключающий это поведение. Таким образом, можно просто отредактировать `site.py` и добавить в него две строки:387388```text389import sys390sys.path.append('/www/python/')391```392393Однако при переустановке той же основной версии Python (например, при обновлении с 2.2 до 2.2.2) файл `site.py` будет перезаписан стандартной версией. Придётся помнить, что он был изменён, и сохранить копию перед установкой.394395Существует две переменные окружения, которые могут изменять `sys.path`. [`PYTHONHOME`](https://python-all.ru/3.4/using/cmdline.html#envvar-PYTHONHOME) задаёт альтернативное значение префикса установки Python. Например, если [`PYTHONHOME`](https://python-all.ru/3.4/using/cmdline.html#envvar-PYTHONHOME) установлена в `/www/python`, путь поиска будет установлен в `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`.396397Переменная [`PYTHONPATH`](https://python-all.ru/3.4/using/cmdline.html#envvar-PYTHONPATH) может быть установлена в список путей, которые будут добавлены в начало `sys.path`. Например, если [`PYTHONPATH`](https://python-all.ru/3.4/using/cmdline.html#envvar-PYTHONPATH) установлена в `/www/python:/opt/py`, путь поиска начнётся с `['/www/python', '/opt/py']`. (Обратите внимание, что директории должны существовать, чтобы быть добавленными в `sys.path`; модуль [`site`](https://python-all.ru/3.4/library/site.html#module-site) удаляет несуществующие пути.)398399Наконец, `sys.path` – это обычный список Python, поэтому любое приложение Python может изменять его, добавляя или удаляя элементы.400401## Файлы конфигурации Distutils402403Как упоминалось выше, файлы конфигурации Distutils можно использовать для сохранения личных настроек или настроек сайта для любых параметров Distutils. То есть любой параметр любой команды может быть сохранён в одном из двух или трёх (в зависимости от платформы) файлов конфигурации, которые будут обрабатываться до разбора командной строки. Это означает, что файлы конфигурации переопределяют значения по умолчанию, а командная строка, в свою очередь, переопределяет файлы конфигурации. Кроме того, если применяется несколько файлов конфигурации, значения из «более ранних» файлов переопределяются «более поздними».404405### Расположение и имена файлов конфигурации406407Имена и расположение конфигурационных файлов немного различаются в зависимости от платформы. На Unix и Mac OS X три конфигурационных файла (в порядке их обработки):408409| Тип файла | Расположение и имя файла | Примечания |410| --- | --- | --- |411| системный | `prefix/lib/pythonver/distutils/distutils.cfg` | (1) |412| личный | `$HOME/.pydistutils.cfg` | (2) |413| локальный | `setup.cfg` | (3) |414415А в Windows файлы конфигурации:416417| Тип файла | Расположение и имя файла | Примечания |418| --- | --- | --- |419| системный | `prefix\Lib\distutils\distutils.cfg` | (4) |420| личный | `%HOME%\pydistutils.cfg` | (5) |421| локальный | `setup.cfg` | (3) |422423На всех платформах «личный» файл можно временно отключить, передав параметр *–no-user-cfg*.424425Примечания:4264271. Строго говоря, общесистемный файл конфигурации находится в директории, где установлены Distutils; в Python 1.6 и новее в Unix это показано. В Python 1.5.2 Distutils обычно устанавливаются в `prefix/lib/python1.5/site-packages/distutils`, поэтому в Python 1.5.2 файл системной конфигурации следует помещать туда.4282. В Unix, если переменная окружения `HOME` не определена, домашняя директория пользователя определяется с помощью функции `getpwuid()` из стандартного модуля [`pwd`](https://python-all.ru/3.4/library/pwd.html#module-pwd). Это делается функцией [`os.path.expanduser()`](https://python-all.ru/3.4/library/os.path.html#os.path.expanduser), используемой Distutils.4293. То есть в текущем каталоге (обычно там, где находится сценарий setup).4304. (См. также примечание (1).) В Python 1.6 и новее «префикс установки» по умолчанию – `C:\Python`, поэтому системный файл конфигурации обычно находится по пути `C:\Python\Lib\distutils\distutils.cfg`. В Python 1.5.2 префиксом по умолчанию был `C:\Program Files\Python`, и Distutils не входили в стандартную библиотеку – поэтому в стандартной установке Python 1.5.2 в Windows системный файл конфигурации находился бы в `C:\Program Files\Python\distutils\distutils.cfg`.4315. На Windows, если не определена переменная окружения `HOME`,\\n`USERPROFILE`, затем `HOMEDRIVE` и `HOMEPATH` будут\\nиспользованы. Это делается с помощью функции [`os.path.expanduser()`](https://python-all.ru/3.4/library/os.path.html#os.path.expanduser), используемой Distutils.432433### Синтаксис файлов конфигурации434435Все конфигурационные файлы Distutils имеют одинаковый синтаксис. Файлы конфигурации\\nсгруппированы в разделы. Для каждой команды Distutils есть свой раздел,\\nплюс раздел `global` для глобальных параметров, влияющих на все команды. Каждый\\nраздел состоит из одного параметра на строку, указываемого в виде `option=value`.436437Например, ниже приведён полный файл конфигурации, который заставляет все команды по умолчанию работать в тихом режиме:438439```text440[global]441verbose=0442```443444Если этот файл установлен как системный конфигурационный файл, он будет влиять на обработку\\nлюбого дистрибутива модулей Python любым пользователем на текущей системе. Если он\\nустановлен как личный конфигурационный файл (в системах, которые это поддерживают), он будет\\nвлиять только на дистрибутивы модулей, обрабатываемые этим пользователем. А если он используется как\\n`setup.cfg` для конкретного дистрибутива модулей, он влияет только на этот\\nдистрибутив.445446Можно переопределить каталог «build base» по умолчанию и заставить команды **build\*** всегда принудительно пересобирать все файлы следующим образом:447448```text449[build]450build-base=blib451force=1452```453454что соответствует аргументам командной строки455456```text457python setup.py build --build-base=blib --force458```459460за исключением того, что указание команды **build** в командной строке означает, что эта команда будет выполнена. Включение конкретной команды в файлы конфигурации не имеет такого смысла; это лишь означает, что если команда будет выполнена, то будут применены параметры из файла конфигурации. (Или если будут выполнены другие команды, которые используют её значения, они возьмут значения из файла конфигурации.)461462Полный список опций для любой команды можно получить с помощью\\nопции [*--help*](https://python-all.ru/3.4/using/cmdline.html#cmdoption--help), например:463464```text465python setup.py build --help466```467468а полный список глобальных опций можно получить, используя\\n[*--help*](https://python-all.ru/3.4/using/cmdline.html#cmdoption--help) без указания команды:469470```text471python setup.py --help472```473474См. также раздел «Справочник» в руководстве «Распространение модулей Python».475476## Сборка расширений: советы и хитрости477478По возможности Distutils старается использовать конфигурационную информацию,\\nпредоставляемую интерпретатором Python, который используется для запуска скрипта `setup.py`.\\nНапример, те же флаги компилятора и компоновщика, которые использовались для компиляции Python, будут\\nиспользованы и для компиляции расширений. Обычно это работает хорошо, но в\\nсложных ситуациях это может быть неуместно. В этом разделе обсуждается, как\\nпереопределить стандартное поведение Distutils.479480### Настройка флагов компилятора/компоновщика481482Компиляция расширения Python, написанного на C или C++, иногда требует указания пользовательских флагов для компилятора и компоновщика, чтобы использовать конкретную библиотеку или создать особый вид объектного кода. Особенно это актуально, если расширение не тестировалось на вашей платформе или вы пытаетесь кросс-компилировать Python.483484В самом общем случае автор расширения мог предвидеть, что\\nкомпиляция расширений будет сложной, и предоставил файл `Setup`\\nдля редактирования. Скорее всего, это делается только в том случае, если дистрибутив модулей\\nсодержит много отдельных модулей расширения, или если для их работы часто требуются\\nсложные наборы флагов компилятора.485486Файл `Setup`, если он присутствует, разбирается для получения списка расширений,\\nкоторые нужно собрать. Каждая строка в `Setup` описывает один модуль. Строки имеют\\nследующую структуру:487488```text489module ... [sourcefile ...] [cpparg ...] [library ...]490```491492Рассмотрим каждое поле по порядку.493494- *module* – это имя собираемого модуля расширения, и оно должно быть корректным идентификатором Python. Просто изменить его, чтобы переименовать модуль, нельзя (потребуется также править исходный код), поэтому его следует оставить как есть.495- *sourcefile* – это то, что, по крайней мере судя по имени файла, вероятно, является файлом исходного кода. Предполагается, что файлы с именами, оканчивающимися на `.c`, написаны на C, файлы с именами, оканчивающимися на `.C`, `.cc` и `.c++` – на C++, а файлы с именами, оканчивающимися на `.m` или `.mm` – на Objective C.496- *cpparg* – это аргумент для препроцессора C; это всё, что начинается с\\n[*-I*](https://python-all.ru/3.4/using/cmdline.html#cmdoption-I), *-D*, *-U* или *-C*.497- *library* – это всё, что заканчивается на `.a` или начинается с [*-l*](https://python-all.ru/3.4/library/tarfile.html#cmdoption-l) или\\n*-L*.498499Если конкретная платформа требует специальной библиотеки, её можно\\nдобавить, отредактировав файл `Setup` и запустив `python setup.py build`.\\nНапример, если модуль, определённый строкой500501```text502foo foomodule.c503```504505должен быть слинкован с математической библиотекой `libm.a` на данной платформе; достаточно добавить\\n*-lm* в строку:506507```text508foo foomodule.c -lm509```510511Произвольные ключи, предназначенные для компилятора или компоновщика, можно задать с помощью\\nопций *-Xcompiler* *arg* и *-Xlinker* *arg*:512513```text514foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm515```516517Следующая опция после *-Xcompiler* и *-Xlinker* будет\\nдобавлена к соответствующей командной строке, так что в приведённом выше примере компилятору будет\\nпередана опция *-o32*, а компоновщику –\\n*-shared*. Если опция компилятора требует аргумента, придётся\\nуказать несколько опций *-Xcompiler*; например, чтобы передать `-x c++`,\\nфайл `Setup` должен содержать `-Xcompiler -x -Xcompiler c++`.518519Флаги компилятора также можно задать через установку переменной окружения `CFLAGS`.\\nЕсли она установлена, содержимое `CFLAGS` будет добавлено к\\nфлагам компилятора, указанным в файле `Setup`.520521### Использование компиляторов не от Microsoft в Windows522523#### Borland/CodeGear C++524525В этом подразделе описаны шаги, необходимые для использования Distutils с компилятором Borland C++ версии 5.5. Учтите, что формат объектных файлов Borland (OMF) отличается от формата, используемого в версии Python, которую можно скачать с сайта Python или ActiveState. (Python собран с помощью Microsoft Visual C++, который использует формат COFF для объектных файлов.) Поэтому библиотеку Python `python25.lib` нужно преобразовать в формат Borland. Это можно сделать следующим образом:526527```text528coff2omf python25.lib python25_bcpp.lib529```530531Программа `coff2omf` поставляется с компилятором Borland. Файл\\n`python25.lib` находится в каталоге `Libs` установки Python.\\nЕсли расширение использует другие библиотеки (zlib, ...), их также необходимо\\nпреобразовать.532533Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.534535Как Distutils удаётся использовать эти библиотеки с их изменёнными именами? Если\\nрасширению требуется библиотека (например, `foo`), Distutils сначала проверяет, найдёт ли он\\nбиблиотеку с суффиксом `_bcpp` (например, `foo_bcpp.lib`), и затем\\nиспользует эту библиотеку. Если такой специальной библиотеки не найдено, используется\\nимя по умолчанию (`foo.lib`.) [\[1\]](https://python-all.ru/3.4/install/index.html#id4)536537Чтобы Distutils собрал ваше расширение с Borland C++, введите:538539```text540python setup.py build --compiler=bcpp541```542543Если вы хотите использовать компилятор Borland C++ по умолчанию, это можно указать в вашем личном или общесистемном конфигурационном файле Distutils (см. раздел [*Distutils Configuration Files*](https://python-all.ru/3.4/install/index.html#inst-config-files)).544545> **См. также**546>547> **[Компилятор C++Builder](https://python-all.ru/3.4/install/index.html)**548>549> Информация о бесплатном компиляторе C++ от Borland, включая ссылки на страницы загрузки.550>551> **[Создание расширений Python с помощью бесплатного компилятора Borland](https://python-all.ru/3.4/install/index.html)**552>553> Документ, описывающий, как использовать бесплатный компилятор C++ командной строки Borland для сборки Python.554555#### GNU C / Cygwin / MinGW556557В этом разделе описаны необходимые шаги для использования Distutils с компиляторами GNU C/C++ в дистрибутивах Cygwin и MinGW. [\[2\]](https://python-all.ru/3.4/install/index.html#id5) Для интерпретатора Python, собранного с помощью Cygwin, всё должно работать без каких-либо дополнительных действий.558559Не все расширения можно собрать с MinGW или Cygwin, но многие можно. Вероятнее всего, не будут работать расширения, использующие C++ или зависящие от расширений Microsoft Visual C.560561Чтобы Distutils собрал ваше расширение с Cygwin, введите:562563```text564python setup.py build --compiler=cygwin565```566567а для Cygwin в режиме no-cygwin [\[3\]](https://python-all.ru/3.4/install/index.html#id6) или для MinGW введите:568569```text570python setup.py build --compiler=mingw32571```572573Если вы хотите использовать любую из этих опций/компиляторов по умолчанию, стоит записать это в ваш личный или общесистемный конфигурационный файл Distutils (см. раздел [*Distutils Configuration Files*](https://python-all.ru/3.4/install/index.html#inst-config-files)).574575##### Старые версии Python и MinGW576577Следующие инструкции применимы только в том случае, если вы используете версию Python ниже 2.4.1 с MinGW ниже 3.0.0 (с binutils-2.13.90-20030111-1).578579Этим компиляторам требуются некоторые специальные библиотеки. Эта задача сложнее, чем\\nдля Borland C++, потому что нет программы для преобразования библиотеки. Сначала\\nнеобходимо создать список символов, которые экспортирует DLL Python. (Хорошую программу для этой задачи можно найти по адресу\\n[http://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/](https://python-all.ru/3.4/install/index.html)).580581```text582pexports python25.dll >python25.def583```584585Расположение установленного `python25.dll` зависит от\\nпараметров установки, а также от версии и языка Windows. При установке «только для меня»\\nон будет находиться в корневом каталоге установки. При\\nобщей установке он будет расположен в системном каталоге.586587Затем на основе этой информации можно создать импортную библиотеку для gcc.588589```text590/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a591```592593Результирующая библиотека должна быть помещена в тот же каталог, что и\\n`python25.lib`. (Должен быть каталог `libs` в каталоге установки Python.)594595Если расширение использует другие библиотеки (zlib,...), возможно, потребуется также\\nпреобразовать их. Преобразованные файлы должны находиться в тех же каталогах, что и\\nобычные библиотеки.596597> **См. также**598>599> **[Сборка модулей Python на платформе MS Windows с помощью MinGW](https://python-all.ru/3.4/install/index.html)**600>601> Информация о сборке необходимых библиотек для окружения MinGW.602603Сноски604605| [\[1\]](https://python-all.ru/3.4/install/index.html#id1) | Это также означает, что можно заменить все существующие COFF-библиотеки на OMF-библиотеки с теми же именами. |606| --- | --- |607608| [\[2\]](https://python-all.ru/3.4/install/index.html#id2) | См. [http://www.sourceware.org/cygwin/](https://python-all.ru/3.4/install/index.html) и [http://www.mingw.org/](https://python-all.ru/3.4/install/index.html) для получения дополнительной\\nинформации |609| --- | --- |610611| [\[3\]](https://python-all.ru/3.4/install/index.html#id3) | В этом случае эмуляция POSIX недоступна, но и не требуется\\n`cygwin1.dll`. |612| --- | --- |613