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

Автор: Greg Ward

Примечание

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

См. также

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

Примечание

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

Примечание

Это руководство охватывает только базовые инструменты для создания и распространения расширений, предоставляемые в рамках данной версии Python. Инструменты сторонних разработчиков предлагают более простые в использовании и безопасные альтернативы. Для получения дополнительной информации см. раздел рекомендации по инструментам в Руководстве пользователя Python Packaging.

Введение

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

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

См. Установка модулей Python и Распространение модулей Python для получения более подробной информации.

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

Дистрибутивы исходного кода, основанные на Distutils

Если вы загружаете дистрибутив модуля исходного кода, вы можете довольно быстро определить, был ли он упакован и распространен стандартным способом, т.е. с использованием Distutils. Во-первых, имя и номер версии дистрибутива будут prominently указаны в имени загруженного архива, например foo-1.0.tar.gz или widget-0.9.7.zip. Далее, архив будет распакован в директорию с аналогичным именем: foo-1.0 или widget-0.9.7. Кроме того, дистрибутив будет содержать скрипт setup 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 для выполнения сборки/установки (т. е. для запуска скрипта setup), но устанавливать модули в каталог модулей сторонних библиотек другой установки 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, используемого для запуска скрипта setup, будут использоваться при компиляции расширений. Вам необходимо убедиться, что интерпретатор, используемый для запуска установленных таким образом расширений, совместим с интерпретатором, используемым для их сборки. Лучший способ сделать это — убедиться, что оба интерпретатора являются одной и той же версией 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 и --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). См. раздел Изменение пути поиска 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 не были частью стандартной библиотеки — поэтому системный конфигурационный файл в стандартной установке 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]
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.