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

Автор: Greg Ward

См. также

Установка модулей 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

Варианты для разных платформ

Вы всегда должны запускать команду setup из корневого каталога дистрибутива, то есть из верхнего каталога, в который распаковывается дистрибутив исходного кода модуля. Например, если вы только что скачали дистрибутив исходного кода модуля 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 собирает и устанавливает все модули в одном запуске. Если вы предпочитаете работать поэтапно (особенно полезно, если вы хотите настроить процесс сборки или если возникают проблемы), вы можете использовать скрипт setup для выполнения одной операции за раз. Это особенно полезно, когда сборка и установка будут выполняться разными пользователями — например, вы можете собрать дистрибутив модуля и передать его системному администратору для установки (или сделать это самостоятельно с правами суперпользователя).

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

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 (чистый)	`prefix/lib/pythonX.Y/site-packages`	`/usr/local/lib/pythonX.Y/site-packages`	(1)
Unix (нечистый)	`exec-prefix/lib/pythonX.Y/site-packages`	`/usr/local/lib/pythonX.Y/site-packages`	(1)
Windows	`prefix\Lib\site-packages`	`C:\PythonXY\Lib\site-packages`	(2)

Примечания:

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

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).

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

Идея «схемы домашнего каталога» заключается в том, что вы создаете и поддерживаете личный набор 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 (схема префикса)

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

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

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

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

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

В любом случае, параметр --prefix определяет базовый каталог установки, а параметр --exec-prefix определяет платформенно-специфический базовый каталог, который используется для платформенно-специфических файлов. (В настоящее время это означает только дистрибутивы модулей, не являющихся чистыми, но может быть расширено до C-библиотек, двоичных исполняемых файлов и т. д.) Если --exec-prefix не указан, он по умолчанию равен --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; если перечисленные выше каталоги еще не существуют, они создаются во время установки.

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

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

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

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

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

для установки модулей в каталог \Temp\Python на текущем диске.

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

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

Настройка установки

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

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

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

Эти параметры переопределения могут быть относительными, абсолютными или явно определены относительно одного из базовых каталогов установки. (Существует два базовых каталога установки, и они обычно совпадают; они различаются только при использовании схемы Unix «prefix» и при указании разных параметров --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

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

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

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

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

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

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

или, эквивалентно,

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

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

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

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

или, эквивалентно,

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечания

1: Это также означает, что вы могли бы заменить все существующие COFF-библиотеки OMF-библиотеками с теми же именами.
2: Дополнительную информацию см. на сайте https://www.sourceware.org/cygwin/
3: Тогда у вас нет эмуляции POSIX, но вам также не нужен cygwin1.dll.