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

Дистрибутивы с исходным кодом на основе 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 эту команду следует выполнить из окна командной строки (Start ‣ Accessories):

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

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

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 или содержит расширения («нечистый»):

Примечания:

1. Большинство дистрибутивов Linux включают Python в качестве стандартной части системы, поэтому prefix и exec-prefix обычно оба /usr в Linux. Если вы сами собираете Python в Linux (или любой другой Unix-подобной системе), то по умолчанию prefix и exec-prefix будут /usr/local.

2. Каталог установки по умолчанию в Windows был C:\Program Files\Python в Python 1.6a1, 1.5.2 и более ранних версиях.

prefix и exec-prefix означают каталоги, в которые устанавливается Python и где он находит свои библиотеки во время выполнения. Они всегда одинаковы в Windows, и очень часто одинаковы в Unix и macOS. Вы можете узнать, что ваша установка Python использует для prefix и exec-prefix, запустив Python в интерактивном режиме и набрав несколько простых команд. В Unix просто введите python в приглашении оболочки. В Windows выберите Start ‣ Programs ‣ Python X.Y ‣ Python (command line). После запуска интерпретатора вы набираете код 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.

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

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

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

python setup.py install --user

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

А вот значения, используемые в Windows:

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

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

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

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

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

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

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

python setup.py install --home=~

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

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

(Мысленно замените слеши на обратные слеши, если вы работаете в Windows).

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

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

Во-первых, учтите, что многие дистрибутивы 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. Файлы устанавливаются следующим образом:

Нет требования, чтобы --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 и модули расширения устанавливаются в одно и то же место. Файлы устанавливаются следующим образом:

Изменение пути поиска в 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 может изменять его, добавляя или удаляя элементы.

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

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

В Windows конфигурационные файлы находятся:

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

Примечания:

1. Строго говоря, общесистемный конфигурационный файл находится в каталоге, где установлены Distutils; в Python 1.6 и более поздних версиях на Unix это выглядит так, как показано на рисунке. Для Python 1.5.2 Distutils обычно устанавливается в каталог prefix/lib/python1.5/site-packages/distutils, поэтому системный конфигурационный файл должен быть помещен туда для Python 1.5.2.

2. На Unix, если переменная окружения HOME не определена, домашний каталог пользователя будет определен с помощью функции getpwuid() из стандартного модуля pwd. Это делается с помощью функции os.path.expanduser(), используемой Distutils.

3. Т.е. в текущем каталоге (обычно это местоположение скрипта настройки).

4. (См. также примечание (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.

5. В 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».

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

Компиляция расширения 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.

• библиотека - это все, что заканчивается на .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.

Использование компиляторов других производителей под Windows¶

coff2omf python25.lib python25_bcpp.lib

python setup.py build --compiler=bcpp

python setup.py build --compiler=cygwin

python setup.py build --compiler=mingw32

pexports python25.dll >python25.def

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