Установка модулей Python (устаревшая версия)

Автор:: Greg Ward

Примечание

Весь пакет distutils устарел и будет удалён в Python 3.12. Эта документация сохраняется только в качестве справочного материала и будет удалена вместе с пакетом. Дополнительные сведения см. в записи Что нового.

См. также

Установка модулей Python: Актуальная документация по установке модулей. Для обычного использования Python вам почти наверняка нужен именно этот документ, а не этот.

Примечание

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

Примечание

В этом руководстве рассматриваются только основные инструменты для сборки и распространения расширений, входящие в состав данной версии Python. Сторонние инструменты предлагают более простые и безопасные альтернативы. Дополнительные сведения см. в разделе с краткими рекомендациями Руководства пользователя по упаковке Python.

Введение

В Python 2.0 API distutils впервые был добавлен в стандартную библиотеку. Он предоставил сопровождающим дистрибутивов Linux стандартный способ преобразования проектов Python в пакеты дистрибутивов Linux, а системным администраторам — стандартный способ их непосредственной установки в целевые системы.

За многие годы, прошедшие с выпуска Python 2.0, тесная связь системы сборки и установщика пакетов с циклом выпуска среды выполнения языка оказалась проблематичной. Теперь рекомендуется использовать установщик пакетов pip и систему сборки setuptools, а не напрямую использовать distutils.

Дополнительные сведения см. в разделах Установка модулей Python и Распространение модулей Python.

Эта устаревшая документация сохраняется только до тех пор, пока мы не убедимся, что документация setuptools охватывает всё необходимое.

Исходные дистрибутивы на основе Distutils

Если вы скачаете исходный дистрибутив модуля, довольно быстро можно определить, был ли он упакован и распространён стандартным способом, то есть с помощью Distutils. Во-первых, имя и номер версии дистрибутива будут заметно указаны в имени скачанного архива, например foo-1.0.tar.gz или widget-0.9.7.zip. Затем архив распакуется в каталог с похожим именем: foo-1.0 или widget-0.9.7. Кроме того, дистрибутив будет содержать сценарий настройки setup.py и файл с именем README.txt или, возможно, просто README, в котором должно быть указано, что для сборки и установки дистрибутива модуля достаточно выполнить одну команду в терминале:

python setup.py install

В Windows эту команду следует выполнить в окне командной строки (Пуск ‣ Стандартные программы):

setup.py install

Если всё это так, вы уже знаете, как собрать и установить только что скачанные модули: выполните указанную выше команду. Если вам не нужно устанавливать файлы нестандартным способом или настраивать процесс сборки, это руководство вам не понадобится. Или, точнее, приведённая выше команда — это всё, что вам нужно из этого руководства.

Стандартная сборка и установка

Как описано в разделе Исходные дистрибутивы на основе Distutils, для сборки и установки дистрибутива модуля с помощью Distutils обычно достаточно выполнить одну простую команду в терминале:

python setup.py install

Различия платформ

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

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

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

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

Разделение задачи на этапы

Выполнение setup.py install собирает и устанавливает все модули за один запуск. Если вы предпочитаете выполнять работу поэтапно — это особенно полезно, если вы хотите настроить процесс сборки или если что-то идёт не так, — можно использовать сценарий настройки для выполнения отдельных операций. Это особенно полезно, когда сборку и установку выполняют разные пользователи: например, вы можете собрать дистрибутив модуля и передать его системному администратору для установки (или сделать это самостоятельно с правами суперпользователя).

Например, можно собрать всё за один шаг, а затем установить всё за второй шаг, запустив сценарий настройки дважды:

python setup.py build
python setup.py install

Если вы сделаете это, то заметите, что команда install сначала запускает команду build, которая в данном случае быстро обнаруживает, что ей нечего делать, поскольку всё в каталоге build уже обновлено.

Если вы только устанавливаете модули, скачанные из Интернета, вам, возможно, нечасто понадобится разделять задачи на этапы, но эта возможность очень удобна для более сложных задач. Если вы начнёте распространять собственные модули и расширения Python, то будете часто запускать отдельные команды Distutils.

Как работает сборка

Как упоминалось выше, команда build отвечает за размещение файлов, предназначенных для установки, в каталоге сборки. По умолчанию это build в корневом каталоге дистрибутива; если для вас особенно важна скорость или вы хотите сохранить исходное дерево в неизменном виде, каталог сборки можно изменить с помощью параметра --build-base. Например:

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

(Или можно задать это постоянно с помощью директивы в системном или личном файле конфигурации Distutils; см. раздел Файлы конфигурации Distutils.) Обычно в этом нет необходимости.

Стандартная структура дерева сборки выглядит следующим образом:

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

где <plat> заменяется кратким описанием текущей платформы ОС/оборудования и версии Python. Первая форма, содержащая только каталог lib, используется для «дистрибутивов чистых модулей», то есть дистрибутивов модулей, содержащих только модули на чистом Python. Если дистрибутив модуля содержит расширения (модули, написанные на C/C++), используется вторая форма с двумя каталогами <plat>. В этом случае каталог temp.plat содержит временные файлы, созданные в процессе компиляции/компоновки и фактически не устанавливаемые. В обоих случаях каталог lib (или lib.plat) содержит все модули Python (на чистом Python и расширения), которые будут установлены.

В будущем в дерево будут добавлены новые каталоги для обработки сценариев Python, документации, исполняемых файлов и всего остального, необходимого для установки модулей и приложений Python.

Как работает установка

После выполнения команды build (независимо от того, запускаете ли вы её явно или она выполняется командой install) работа команды install относительно проста: ей нужно лишь скопировать всё содержимое каталога build/lib (или build/lib.plat) в выбранный вами каталог установки.

Если вы не выберете каталог установки, то есть просто выполните setup.py install, команда install установит файлы в стандартное расположение для сторонних модулей Python. Это расположение зависит от платформы и от того, как вы собрали/установили сам Python. В Unix (и macOS, которая также основана на Unix) оно также зависит от того, является ли устанавливаемый дистрибутив модуля дистрибутивом чистого Python или содержит расширения («нечистый»):

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

Примечания:

В большинстве дистрибутивов Linux Python входит в стандартную систему, поэтому prefix и exec-prefix в Linux обычно совпадают и равны /usr. Если вы самостоятельно собираете Python в Linux (или любой другой Unix-подобной системе), значения по умолчанию для prefix и exec-prefix равны /usr/local.
В Python 1.6a1, 1.5.2 и более ранних версиях каталог установки по умолчанию в Windows находился в C:\Program Files\Python.

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

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

В этом документе используются ещё несколько заполнителей: X.Y обозначает версию Python, например 3.2; abiflags заменяется значением sys.abiflags или пустой строкой для платформ, не определяющих флаги ABI; distname заменяется именем устанавливаемого дистрибутива модуля. Точки и регистр символов в путях имеют значение: например, значению с python3.2 в UNIX обычно соответствует Python32 в Windows.

Если вы не хотите устанавливать модули в стандартное расположение или у вас нет разрешения на запись туда, прочитайте об альтернативных установках в разделе Альтернативная установка. Если вы хотите более тщательно настроить каталоги установки, см. раздел Настраиваемая установка.

Альтернативная установка

Часто возникает необходимость или желание устанавливать модули не в стандартное расположение для сторонних модулей Python. Например, в системе Unix у вас может не быть разрешения на запись в стандартный каталог сторонних модулей. Или вы можете захотеть опробовать модуль, прежде чем сделать его стандартной частью локальной установки Python. Это особенно важно при обновлении уже установленного дистрибутива: перед обновлением нужно убедиться, что имеющиеся сценарии по-прежнему работают с новой версией.

Команда Distutils install разработана так, чтобы установка дистрибутивов модулей в альтернативное расположение была простой и удобной. Основная идея заключается в том, что вы указываете базовый каталог установки, а команда install выбирает набор каталогов (называемый схемой установки) внутри этого базового каталога для размещения файлов. Подробности различаются в зависимости от платформы, поэтому прочитайте подходящий для вас раздел ниже.

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

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

Эта схема разработана как наиболее удобное решение для пользователей, у которых нет разрешения на запись в глобальный каталог site-packages или которые не хотят устанавливать файлы в него. Она включается простым параметром:

python setup.py install --user

Файлы будут установлены в подкаталоги site.USER_BASE (далее обозначаемого как userbase). Эта схема устанавливает модули на чистом Python и модули-расширения в одно и то же расположение (также известное как site.USER_SITE). Ниже приведены значения для UNIX, включая macOS:

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

Ниже приведены значения, используемые в Windows:

Тип файла	Каталог установки
модули	`userbase\PythonXY\site-packages`
сценарии	`userbase\PythonXY\Scripts`
данные	`userbase`
заголовочные файлы C	`userbase\PythonXY\Include{distname}`

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

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

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

Идея «схемы home» заключается в том, что вы создаёте и поддерживаете личное хранилище модулей Python. Название этой схемы происходит от идеи домашнего каталога в Unix, поскольку пользователи Unix нередко организуют домашний каталог по структуре, похожей на /usr/ или /usr/local/. Эту схему можно использовать независимо от операционной системы, для которой выполняется установка.

Установка нового дистрибутива модуля выполняется так же просто, как

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

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

python setup.py install --home=~

Чтобы Python находил дистрибутивы, установленные по этой схеме, может потребоваться изменить путь поиска Python или отредактировать sitecustomize (см. site), чтобы вызвать site.addsitedir(), либо отредактировать sys.path.

Параметр --home задаёт базовый каталог установки. Файлы устанавливаются в следующие каталоги внутри базового каталога установки:

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

(Если вы работаете в Windows, мысленно замените косые черты обратными.)

Альтернативная установка: Unix (схема prefix)

«Схема prefix» полезна, если вы хотите использовать одну установку Python для выполнения сборки/установки (то есть для запуска сценария настройки), но устанавливать модули в каталог сторонних модулей другой установки Python (или чего-то, похожего на другую установку Python). Это может показаться немного необычным — именно поэтому сначала описываются пользовательская схема и схема home. Однако известно по крайней мере о двух случаях, когда схема prefix может быть полезна.

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

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

Другой вариант — сетевая файловая система, где имя для записи в удалённый каталог отличается от имени для чтения из него: например, интерпретатор Python, доступный как /usr/local/bin/python, может искать модули в /usr/local/lib/python2.X, но устанавливать эти модули нужно, скажем, в /mnt/@server/export/lib/python2.X. Это можно сделать с помощью

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

В обоих случаях параметр --prefix задаёт базовый каталог установки, а параметр --exec-prefix — платформенно-зависимый базовый каталог установки, который используется для платформенно-зависимых файлов. (В настоящее время это означает только дистрибутивы модулей, не относящиеся к чистому Python, но сюда могут быть добавлены библиотеки C, исполняемые файлы и т. д.) Если --exec-prefix не указан, по умолчанию используется --prefix. Файлы устанавливаются следующим образом:

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

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

Кстати, настоящая причина важности схемы prefix заключается лишь в том, что стандартная установка Unix использует эту схему, но значения --prefix и --exec-prefix задаются самим Python как sys.prefix и sys.exec_prefix. Таким образом, вы можете думать, что никогда не будете использовать схему prefix, но каждый раз, когда вы запускаете python setup.py install без других параметров, вы используете её.

Обратите внимание, что установка расширений в альтернативную установку Python не влияет на способ их сборки: в частности, при компиляции расширений будут использоваться заголовочные файлы Python (Python.h и другие), установленные вместе с интерпретатором Python, который используется для запуска сценария настройки. Вы несёте ответственность за то, чтобы интерпретатор, используемый для запуска установленных таким образом расширений, был совместим с интерпретатором, использованным для их сборки. Лучше всего убедиться, что оба интерпретатора имеют одну и ту же версию Python (возможно, это разные сборки или копии одной сборки). (Разумеется, если --prefix и --exec-prefix даже не указывают на альтернативную установку Python, это не имеет значения.)

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

В Windows нет понятия домашнего каталога пользователя, а стандартная установка Python в Windows проще, чем в Unix, поэтому параметр --prefix традиционно используется для установки дополнительных пакетов в отдельные расположения Windows.

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

чтобы установить модули в каталог \Temp\Python на текущем диске.

Базовый каталог установки задаётся параметром --prefix; параметр --exec-prefix в Windows не поддерживается, поэтому модули на чистом Python и модули-расширения устанавливаются в одно и то же расположение. Файлы устанавливаются следующим образом:

Тип файла	Каталог установки
модули	`prefix\Lib\site-packages`
сценарии	`prefix\Scripts`
данные	`prefix`
заголовочные файлы C	`prefix\Include{distname}`

Настраиваемая установка

Иногда альтернативные схемы установки, описанные в разделе Альтернативная установка, просто не подходят для ваших целей. Возможно, вы захотите изменить всего один или два каталога, оставив всё остальное в том же базовом каталоге, или полностью переопределить схему установки. В обоих случаях вы создаёте настраиваемую схему установки.

Чтобы создать настраиваемую схему установки, возьмите одну из альтернативных схем и переопределите некоторые каталоги установки, используемые для различных типов файлов, с помощью следующих параметров:

Тип файла	Параметр переопределения
Модули Python	`--install-purelib`
модули расширений	`--install-platlib`
все модули	`--install-lib`
скрипты	`--install-scripts`
данные	`--install-data`
заголовочные файлы C	`--install-headers`

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

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

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

Ещё один пример для Unix: предположим, что ваша установка Python была собрана и установлена с префиксом /usr/local/python, поэтому при стандартной установке скрипты окажутся в /usr/local/python/bin. Если вместо этого вы хотите поместить их в /usr/local/bin, укажите этот абсолютный каталог для параметра --install-scripts:

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

(При этом выполняется установка с использованием «схемы с префиксом», где префикс — это тот, с которым был установлен интерпретатор Python, в данном случае /usr/local/python.)

Если вы сопровождаете Python в Windows, вам может понадобиться, чтобы сторонние модули находились в подкаталоге prefix, а не непосредственно в prefix. Настроить это почти так же просто, как изменить каталог установки скриптов: нужно лишь помнить, что следует учитывать два типа модулей — Python и модули расширений, — которыми удобно управлять с помощью одного параметра:

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

Указанный каталог установки задаётся относительно prefix. Разумеется, необходимо также убедиться, что этот каталог входит в путь поиска модулей Python, например, поместив файл .pth в каталог site (см. site). О том, как изменить путь поиска Python, см. в разделе Изменение пути поиска Python.

Чтобы определить целую схему установки, достаточно указать все параметры каталогов установки. Рекомендуется задавать относительные пути; например, если вы хотите хранить все файлы, связанные с модулями Python, в каталоге python в своём домашнем каталоге и использовать отдельный каталог для каждой платформы, с которой вы обращаетесь к домашнему каталогу, можно определить следующую схему установки:

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

или, что равнозначно,

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

$PLAT — не обязательно переменная среды: Distutils подставит её при разборе параметров командной строки, так же как при разборе файлов конфигурации.

Очевидно, что каждый раз указывать всю схему установки при установке нового дистрибутива модуля было бы очень утомительно. Поэтому эти параметры можно поместить в файл конфигурации Distutils (см. раздел Файлы конфигурации Distutils):

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

или, что равнозначно,

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

Обратите внимание, что эти варианты не равнозначны, если при запуске скрипта установки указать другой базовый каталог установки. Например,

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

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

Вы, вероятно, заметили использование $HOME и $PLAT во входных данных примера файла конфигурации. Это переменные конфигурации Distutils, очень похожие на переменные среды. На самом деле в файлах конфигурации можно использовать переменные среды на платформах, где они доступны, однако Distutils дополнительно определяет несколько переменных, которых может не быть в вашей среде, например $PLAT. (И, разумеется, в системах без переменных среды, таких как Mac OS 9, переменные конфигурации, предоставляемые Distutils, — единственные, которые можно использовать.) Подробности см. в разделе Файлы конфигурации Distutils.

Примечание

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

Изменение пути поиска Python

Когда интерпретатор Python выполняет инструкцию import, он ищет код Python и модули расширений вдоль пути поиска. Значение пути по умолчанию задаётся в исполняемом файле Python при сборке интерпретатора. Узнать путь можно, импортировав модуль sys и выведя значение sys.path.

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

Пустая строка в sys.path обозначает текущий рабочий каталог.

Обычно локально установленные пакеты помещают в каталог .../site-packages/, однако может потребоваться установить модули Python в произвольный каталог. Например, на вашем сайте может быть принято хранить всё программное обеспечение, связанное с веб-сервером, в /www. Тогда дополнительные модули Python могут размещаться в /www/python, и для их импорта этот каталог нужно добавить в sys.path. Добавить каталог можно несколькими способами.

Самый удобный способ — добавить файл конфигурации пути в каталог, который уже находится в пути Python, обычно в каталог .../site-packages/. Файлы конфигурации пути имеют расширение .pth, и каждая строка должна содержать один путь, который будет добавлен в sys.path. (Поскольку новые пути добавляются в конец sys.path, модули из добавленных каталогов не переопределяют стандартные модули. Поэтому этот способ нельзя использовать для установки фиксированных версий стандартных модулей.)

Пути могут быть абсолютными или относительными; в последнем случае они задаются относительно каталога, содержащего файл .pth. Дополнительные сведения см. в документации модуля site.

Чуть менее удобный способ — отредактировать файл site.py в стандартной библиотеке Python и изменить sys.path. site.py импортируется автоматически при запуске интерпретатора Python, если только для отключения этого поведения не указан параметр -S. Поэтому можно просто отредактировать site.py и добавить в него две строки:

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

Однако при повторной установке той же младшей версии Python (например, при обновлении с 2.2 до 2.2.2) site.py будет перезаписан стандартной версией. Поэтому перед установкой нужно не забыть, что файл был изменён, и сохранить его копию.

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

Переменной PYTHONPATH можно присвоить список путей, которые будут добавлены в начало sys.path. Например, если для PYTHONPATH задано значение /www/python:/opt/py, путь поиска будет начинаться с ['/www/python', '/opt/py']. (Обратите внимание, что для добавления в sys.path каталоги должны существовать; модуль site удаляет несуществующие пути.)

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

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

Как упоминалось выше, файлы конфигурации Distutils можно использовать для сохранения личных или системных предпочтений для любых параметров Distutils. Иными словами, любой параметр любой команды можно сохранить в одном из двух или трёх (в зависимости от платформы) файлов конфигурации, которые будут обработаны до разбора командной строки. Это означает, что файлы конфигурации переопределяют значения по умолчанию, а командная строка, в свою очередь, переопределяет файлы конфигурации. Кроме того, если применимо несколько файлов конфигурации, значения из «более ранних» файлов переопределяются значениями из «более поздних» файлов.

Расположение и имена файлов конфигурации

Имена и расположение файлов конфигурации немного различаются в зависимости от платформы. В Unix и macOS используются три файла конфигурации (в порядке обработки):

Тип файла	Расположение и имя файла	Примечания
системный	`prefix/lib/pythonver/distutils/distutils.cfg`	(1)
личный	`$HOME/.pydistutils.cfg`	(2)
локальный	`setup.cfg`	(3)

В Windows файлы конфигурации следующие:

Тип файла	Расположение и имя файла	Примечания
системный	`prefix\Lib\distutils\distutils.cfg`	(4)
личный	`%HOME%\pydistutils.cfg`	(5)
локальный	`setup.cfg`	(3)

На всех платформах личный файл можно временно отключить, передав параметр --no-user-cfg.

Примечания:

Строго говоря, общесистемный файл конфигурации находится в каталоге установки Distutils; в Unix для Python 1.6 и более поздних версий это указанный выше каталог. Для Python 1.5.2 Distutils обычно устанавливается в prefix/lib/python1.5/site-packages/distutils, поэтому в Python 1.5.2 системный файл конфигурации следует поместить туда.
В Unix, если переменная среды HOME не определена, домашний каталог пользователя определяется с помощью функции getpwuid() из стандартного модуля pwd. Это делает функция os.path.expanduser(), используемая Distutils.
То есть в текущем каталоге (обычно там, где находится скрипт установки).
(См. также примечание (1).) В Python 1.6 и более поздних версиях префикс установки Python по умолчанию — 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.
В Windows, если переменная среды HOME не определена, будут проверены USERPROFILE, затем HOMEDRIVE и HOMEPATH. Это делает функция os.path.expanduser(), используемая Distutils.

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

Все файлы конфигурации Distutils имеют одинаковый синтаксис. Они разбиты на разделы. Для каждой команды Distutils предусмотрен отдельный раздел, а раздел global содержит глобальные параметры, влияющие на все команды. Каждый раздел состоит из параметров, по одному в строке, заданных в виде option=value.

Например, ниже приведён полный файл конфигурации, который просто заставляет все команды по умолчанию работать в тихом режиме:

[global]
verbose=0

Если установить его как системный файл конфигурации, он повлияет на обработку дистрибутивов любых модулей Python любым пользователем в текущей системе. Если установить его как личный файл конфигурации (в системах, где такие файлы поддерживаются), он повлияет только на дистрибутивы модулей, обрабатываемые вами. А если использовать его как setup.cfg для определённого дистрибутива модуля, он повлияет только на этот дистрибутив.

Можно переопределить базовый каталог сборки по умолчанию и заставить команды build* всегда принудительно пересобирать все файлы следующим образом:

[build]
build-base=blib
force=1

что соответствует аргументам командной строки

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

за исключением того, что включение команды build в командную строку означает, что эта команда будет выполнена. Включение определённой команды в файлы конфигурации такого следствия не имеет: это означает лишь, что при запуске команды к ней будут применены параметры из файла конфигурации. (Если запущены другие команды, получающие значения из этой команды, они также будут использовать значения из файла конфигурации.)

Полный список параметров любой команды можно получить с помощью параметра --help, например:

python setup.py build --help

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

python setup.py --help

См. также раздел «Справочник» руководства «Распространение модулей Python».

Сборка расширений: советы и рекомендации

По возможности Distutils старается использовать сведения о конфигурации, предоставляемые интерпретатором Python, с помощью которого запускается скрипт setup.py. Например, для сборки расширений будут использоваться те же флаги компилятора и компоновщика, что и при сборке Python. Обычно это работает хорошо, но в сложных случаях может оказаться неподходящим. В этом разделе описано, как изменить стандартное поведение Distutils.

Настройка флагов компилятора и компоновщика

Для компиляции расширения Python, написанного на C или C++, иногда требуется указать специальные флаги компилятора и компоновщика, чтобы использовать определённую библиотеку или получить особый тип объектного кода. Это особенно актуально, если расширение не тестировалось на вашей платформе или вы пытаетесь выполнить кросс-компиляцию Python.

В наиболее общем случае автор расширения мог предусмотреть, что его сборка будет сложной, и предоставить файл Setup для редактирования. Такое делают, скорее всего, только в том случае, если дистрибутив модуля содержит множество отдельных модулей расширений или для их работы часто требуются сложные наборы флагов компилятора.

Если файл Setup существует, он разбирается для получения списка расширений, которые нужно собрать. Каждая строка файла Setup описывает один модуль. Строки имеют следующую структуру:

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

Рассмотрим каждое поле по очереди.

module — имя собираемого модуля расширения; оно должно быть допустимым идентификатором Python. Просто изменить его, чтобы переименовать модуль, нельзя (понадобится также изменить исходный код), поэтому оставьте его без изменений.
sourcefile — имя, которое, судя по расширению, вероятно, обозначает файл исходного кода. Считается, что файлы с расширением .c написаны на C, файлы с расширениями .C, .cc и .c++ — на C++, а файлы с расширениями .m или .mm — на Objective C.
cpparg — аргумент препроцессора C; это любой аргумент, начинающийся с -I, -D, -U или -C.
library — любой аргумент, заканчивающийся на .a или начинающийся с -l либо -L.

Если на вашей платформе требуется специальная библиотека, её можно добавить, отредактировав файл Setup и запустив python setup.py build. Например, если модуль, описанный строкой

foo foomodule.c

на вашей платформе нужно скомпоновать с математической библиотекой libm.a, просто добавьте -lm в эту строку:

foo foomodule.c -lm

Произвольные параметры для компилятора или компоновщика можно передать с помощью параметров -Xcompiler arg и -Xlinker arg:

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

Следующий параметр после -Xcompiler и -Xlinker будет добавлен в соответствующую командную строку, поэтому в приведённом выше примере компилятору будет передан параметр -o32, а компоновщику — -shared. Если параметру компилятора требуется аргумент, нужно указать несколько параметров -Xcompiler; например, чтобы передать -x c++, файл Setup должен содержать -Xcompiler -x -Xcompiler c++.

Флаги компилятора также можно передать, задав переменную среды CFLAGS. Если она задана, содержимое CFLAGS будет добавлено к флагам компилятора, указанным в файле Setup.

Использование компиляторов, отличных от Microsoft, в Windows

Borland/CodeGear C++

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

coff2omf python25.lib python25_bcpp.lib

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

Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.

Как Distutils удаётся использовать эти библиотеки под изменёнными именами? Если расширению требуется библиотека (например, foo), Distutils сначала проверяет, есть ли библиотека с суффиксом _bcpp (например, foo_bcpp.lib), и использует её. Если такая специальная библиотека не найдена, используется имя по умолчанию (foo.lib.) [1]

Чтобы Distutils скомпилировал расширение с помощью Borland C++, введите:

python setup.py build --compiler=bcpp

Если вы хотите использовать компилятор Borland C++ по умолчанию, укажите это в личном или общесистемном файле конфигурации Distutils (см. раздел Файлы конфигурации Distutils.)

См. также

Компилятор C++Builder: Сведения о бесплатном компиляторе C++ от Borland, включая ссылки на страницы загрузки.
Создание расширений Python с помощью бесплатного компилятора Borland: Документ с описанием использования бесплатного командного компилятора C++ от Borland для сборки Python.

GNU C / Cygwin / MinGW

В этом разделе описаны необходимые шаги для использования Distutils с компиляторами GNU C/C++ из дистрибутивов Cygwin и MinGW. [2] Для интерпретатора Python, собранного с помощью Cygwin, всё должно работать без выполнения следующих шагов.

Не все расширения можно собрать с помощью MinGW или Cygwin, но многие — можно. С наибольшей вероятностью не будут работать расширения, использующие C++ или зависящие от расширений Microsoft Visual C.

Чтобы Distutils скомпилировал расширение с помощью Cygwin, введите:

python setup.py build --compiler=cygwin

а для Cygwin в режиме без Cygwin [3] или для MinGW введите:

python setup.py build --compiler=mingw32

Если вы хотите использовать любой из этих параметров или компиляторов по умолчанию, добавьте соответствующие настройки в личный или общесистемный файл конфигурации Distutils (см. раздел Файлы конфигурации Distutils.)

Старые версии Python и MinGW

Следующие инструкции применимы только в том случае, если используется версия Python ниже 2.4.1 вместе с версией MinGW ниже 3.0.0 (с binutils-2.13.90-20030111-1).

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

pexports python25.dll >python25.def

Расположение установленного python25.dll зависит от параметров установки, версии и языка Windows. При установке «только для меня» он находится в корне каталога установки. При общей установке он будет находиться в системном каталоге.

Затем на основе этих сведений можно создать библиотеку импорта для gcc.

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

Полученную библиотеку нужно поместить в тот же каталог, что и python25.lib. (Это должен быть каталог libs внутри каталога установки Python.)

Если ваше расширение использует другие библиотеки (zlib и т. д.), возможно, их тоже придётся преобразовать. Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.

См. также

Сборка модулей Python на платформе MS Windows с помощью MinGW: Сведения о сборке библиотек, необходимых для среды MinGW.

Установка модулей Python (устаревшая версия)

Введение

Исходные дистрибутивы на основе Distutils

Стандартная сборка и установка

Различия платформ

Разделение задачи на этапы

Как работает сборка

Как работает установка

Альтернативная установка

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

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

Альтернативная установка: Unix (схема prefix)

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

Настраиваемая установка

Изменение пути поиска Python

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

Расположение и имена файлов конфигурации

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

Сборка расширений: советы и рекомендации

Настройка флагов компилятора и компоновщика

Использование компиляторов, отличных от Microsoft, в Windows

Borland/CodeGear C++

GNU C / Cygwin / MinGW

Старые версии Python и MinGW

Сноски