Установка модулей Python¶Installing Python Modules

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

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

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

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

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

Если вы загружаете дистрибутив исходного кода модуля, вы довольно быстро можете определить, упакован ли он и распространён стандартным способом, т.е. с помощью Distutils. Во-первых, имя и номер версии дистрибутива будут prominently указаны в имени загруженного архива, например 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 дважды:

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

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

Альтернативная установка: схема пользователя¶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

Идея «домашней схемы» (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 – платформенно-зависимый базовый каталог установки, который используется для платформенно-зависимых файлов. (В настоящее время это касается только дистрибутивов модулей, не являющихся чисто Python-модулями, но может быть расширено на 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, используемым для запуска сценария setup, будут использоваться при компиляции расширений. Ответственность за обеспечение совместимости интерпретатора, используемого для запуска расширений, установленных таким образом, с интерпретатором, используемым для их сборки, лежит на вас. Лучший способ сделать это – убедиться, что оба интерпретатора являются одной версией Python (возможно, разными сборками или копиями одной сборки). (Разумеется, если ваши --prefix и --exec-prefix вовсе не указывают на альтернативную установку Python, это не имеет значения.)

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

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

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 и новее «префикс установки» по умолчанию – 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,\nUSERPROFILE, затем HOMEDRIVE и HOMEPATH будут\nиспользованы. Это делается с помощью функции os.path.expanduser(), используемой Distutils.

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

Все конфигурационные файлы Distutils имеют одинаковый синтаксис. Файлы конфигурации\nсгруппированы в разделы. Для каждой команды Distutils есть свой раздел,\nплюс раздел global для глобальных параметров, влияющих на все команды. Каждый\nраздел состоит из одного параметра на строку, указываемого в виде option=value.

Например, ниже приведён полный файл конфигурации, который заставляет все команды по умолчанию работать в тихом режиме:

[global]
verbose=0

Если этот файл установлен как системный конфигурационный файл, он будет влиять на обработку\nлюбого дистрибутива модулей Python любым пользователем на текущей системе. Если он\nустановлен как личный конфигурационный файл (в системах, которые это поддерживают), он будет\nвлиять только на дистрибутивы модулей, обрабатываемые этим пользователем. А если он используется как\nsetup.cfg для конкретного дистрибутива модулей, он влияет только на этот\nдистрибутив.

Можно переопределить каталог «build base» по умолчанию и заставить команды build* всегда принудительно пересобирать все файлы следующим образом:

[build]
build-base=blib
force=1

что соответствует аргументам командной строки

python setup.py build --build-base=blib --force

за исключением того, что указание команды build в командной строке означает, что эта команда будет выполнена. Включение конкретной команды в файлы конфигурации не имеет такого смысла; это лишь означает, что если команда будет выполнена, то будут применены параметры из файла конфигурации. (Или если будут выполнены другие команды, которые используют её значения, они возьмут значения из файла конфигурации.)

Полный список опций для любой команды можно получить с помощью\nопции --help, например:

python setup.py build --help

а полный список глобальных опций можно получить, используя\n--help без указания команды:

python setup.py --help

См. также раздел «Справочник» в руководстве «Распространение модулей Python».

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

Компиляция расширения Python, написанного на C или C++, иногда требует указания пользовательских флагов для компилятора и компоновщика, чтобы использовать конкретную библиотеку или создать особый вид объектного кода. Особенно это актуально, если расширение не тестировалось на вашей платформе или вы пытаетесь кросс-компилировать Python.

В самом общем случае автор расширения мог предвидеть, что\nкомпиляция расширений будет сложной, и предоставил файл Setup\nдля редактирования. Скорее всего, это делается только в том случае, если дистрибутив модулей\nсодержит много отдельных модулей расширения, или если для их работы часто требуются\nсложные наборы флагов компилятора.

Файл Setup, если он присутствует, разбирается для получения списка расширений,\nкоторые нужно собрать. Каждая строка в Setup описывает один модуль. Строки имеют\nследующую структуру:

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.

Если конкретная платформа требует специальной библиотеки, её можно\nдобавить, отредактировав файл Setup и запустив python setup.py build.\nНапример, если модуль, определённый строкой

foo foomodule.c

должен быть слинкован с математической библиотекой libm.a на данной платформе; достаточно добавить\n-lm в строку:

foo foomodule.c -lm

Произвольные ключи, предназначенные для компилятора или компоновщика, можно задать с помощью\nопций -Xcompiler arg и -Xlinker arg:

foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

Следующая опция после -Xcompiler и -Xlinker будет\nдобавлена к соответствующей командной строке, так что в приведённом выше примере компилятору будет\nпередана опция -o32, а компоновщику –\n-shared. Если опция компилятора требует аргумента, придётся\nуказать несколько опций -Xcompiler; например, чтобы передать -x c++,\nфайл Setup должен содержать -Xcompiler -x -Xcompiler c++.

Флаги компилятора также можно задать через установку переменной окружения CFLAGS.\nЕсли она установлена, содержимое CFLAGS будет добавлено к\nфлагам компилятора, указанным в файле 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