Установка модулей 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 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 (и Mac OS X, которая также основана на 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 и Mac OS X. Вы можете узнать, что ваши Python использует для prefix и exec-prefix, запустив 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, включая Mac OS X:

Тип файла	Каталог установки
модули	`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» и предоставлении различных параметров --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 (см. 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 и Mac OS X три файла конфигурации (в порядке их обработки) это:

Тип файла	Расположение и имя файла	Примечания
системный	`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 base» и сделать команды 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.