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

Исходные дистрибутивы на основе 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

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

Варианты платформы¶

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

Макет дерева построения по умолчанию выглядит следующим образом:

--- 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 в Linux обычно используются оба /usr. Если вы создаете 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:

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

Самый удобный способ - добавить файл конфигурации path в каталог, который уже находится в path Python, обычно в каталог .../site-packages/. Файлы конфигурации Path имеют расширение .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. Строго говоря, общесистемный конфигурационный файл находится в каталоге, в котором установлены дистрибутивы; в Python 1.6 и более поздних версиях Unix все обстоит так, как показано на рисунке. Для Python 1.5.2 дистрибутивы обычно устанавливаются в 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, а файлы дистрибутива не были частью стандартной библиотеки, поэтому в стандартной установке 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. Вы не можете просто изменить его, чтобы переименовать модуль (также потребуются изменения в исходном коде), поэтому это следует оставить в покое.

• исходный файл - это все, что может быть файлом с исходным кодом, по крайней мере, судя по имени файла. Предполагается, что имена файлов, оканчивающиеся на .c, написаны на C, имена файлов, оканчивающиеся на .C, .cc, и .c++, - на .m C++, а имена файлов, оканчивающиеся на <<<4предполагается, что >>> или .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.

Использование компиляторов, не относящихся к Microsoft, в 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