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

Идеальный случай: простая установка¶Best case: trivial installation

В идеальном случае кто-то подготовит специальную версию распространяемого модуля, который вы хотите установить, ориентированную именно на вашу платформу, и устанавливаемую как любое другое программное обеспечение на вашей платформе. Например, разработчик модуля может предоставить исполняемый установщик для пользователей Windows, пакет RPM для пользователей Linux-систем на основе RPM (Red Hat, SuSE, Mandrake и многих других), пакет Debian для пользователей систем на основе Debian и так далее.

В этом случае вы загрузите установщик, подходящий для вашей платформы, и сделаете очевидное: запустите его, если это исполняемый установщик, rpm --install его, если это RPM, и т.д. Вам не нужно запускать Python или сценарий установки, не нужно ничего компилировать – возможно, вам даже не придётся читать какие-либо инструкции (хотя всегда полезно это сделать).

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

Новый стандарт: Distutils¶The new standard: Distutils

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

python setup.py install

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

setup.py install

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

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

Команду 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

Разделение процесса на этапы¶Splitting the job up

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

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

python setup.py build
python setup.py install

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

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

Как работает сборка¶How building works

Как уже было сказано, команда 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.

Как работает установка¶How installation works

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

Если не указать каталог установки (то есть просто запустить setup.py install), то команда install устанавливает модули в стандартный каталог для сторонних модулей Python. Этот каталог зависит от платформы и от того, как собран или установлен сам Python. На Unix (и Mac OS X, которая также основана на 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 и 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, в Windows обычно имеет вид Python32.

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

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

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

python setup.py install --user

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

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

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

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

Альтернативная установка: схема home¶Alternate installation: the home scheme

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

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

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

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

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

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

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

Альтернативная установка: Windows (префиксная схема)¶Alternate installation: Windows (the prefix scheme)

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

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

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

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

Изменение пути поиска Python¶Modifying Python’s Search Path

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

Расположение и имена файлов конфигурации¶Location and names of config files

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

А в 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. То есть в текущем каталоге (обычно там, где находится сценарий setup).

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

5. В Windows, если переменная окружения HOME не определена, то перебираются USERPROFILE, HOMEDRIVE и HOMEPATH. Это делается функцией os.path.expanduser(), используемой в Distutils.

Синтаксис файлов конфигурации¶Syntax of config files

Все файлы конфигурации 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».

Настройка флагов компилятора/компоновщика¶Tweaking compiler/linker flags

Компиляция расширения 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 аргумент и -Xlinker аргумент:

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¶Using non-Microsoft compilers on 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