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

Author:Greg Ward

См.также

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

Актуальная документация по установке модуля. При регулярном использовании Python вам почти наверняка понадобится этот документ, а не этот.

Примечание

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

Примечание

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

Вступление

В Python 2.0 API distutils был впервые добавлен в стандартную библиотеку. Это предоставило разработчикам дистрибутивов Linux стандартный способ преобразования проектов Python в пакеты дистрибутивов Linux, а системным администраторам стандартный способ их установки непосредственно в целевые системы.

За многие годы, прошедшие с момента выпуска Python 2.0, тесная связь системы сборки и установщика пакетов с циклом выпуска языковой среды выполнения оказалась проблематичной, и теперь рекомендуется, чтобы проекты использовали установщик пакетов pip и систему сборки setuptools, а не чем напрямую использовать distutils.

Подробнее см. Установка модулей Python и Распространение модулей Python.

Эта устаревшая документация сохраняется только до тех пор, пока мы не будем уверены, что документация setuptools охватывает все необходимое.

Распределения исходного кода на основе Distutils

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

python setup.py install

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

setup.py install

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

Стандартная сборка и установка

Как описано в разделе Распределения исходного кода на основе Distutils, сборка и установка дистрибутива модуля с использованием Distutils обычно представляет собой одну простую команду, запускаемую из терминала:

python setup.py install

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

Вы всегда должны запускать команду установки из корневого каталога дистрибутива, то есть из подкаталога верхнего уровня, в который распаковывается исходный дистрибутив модуля. Например, если вы только что загрузили исходный код модуля foo-1.0.tar.gz в систему Unix, вы можете сделать это обычно:

gunzip -c foo-1.0.tar.gz | tar xf -    # распаковывается в каталог 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/
или
--- build/ --- lib.<plat>/
               temp.<plat>/

где <plat> расширяется до краткого описания текущей операционной системы/ аппаратной платформы и версии Python. Первая форма, содержащая только каталог lib, используется для «чистых распределений модулей», т.е. дистрибутивов модулей, которые включают только чистые модули Python. Если дистрибутив модуля содержит какие-либо расширения (модули, написанные на C/C++), то используется вторая форма с двумя каталогами <plat>. В этом случае каталог temp.plat содержит временные файлы, созданные в процессе компиляции/компоновки, которые фактически не устанавливаются. В любом случае каталог lib (или lib.plat) содержит все модули Python (чистый Python и расширения), которые будут установлены.

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

Как работает установка?

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

Если вы не выбрали каталог для установки, т.е. если вы просто запустили setup.py install, то команда install установится в стандартное расположение для сторонних Python модулей. Это расположение зависит от платформы и от того, как вы собрали/установили Python. В Unix (и Mac OS X, который также основан на Unix) это также зависит от того, является ли устанавливаемый дистрибутив модуля чистым Python или содержит расширения («нечистый»)

Платформа	Стандартное место установки	Значение по умолчанию	Заметки
Unix (чистый)	prefix/lib/pythonX.Y/site-packages	/usr/local/lib/pythonX.Y/site-packages	(1)
Unix (нечистый)	exec-prefix/lib/pythonX.Y/site-packages	/usr/local/lib/pythonX.Y/site-packages	(1)
Windows	prefix\Lib\site-packages	C:\PythonXY\Lib\site-packages	(2)

Примечания:

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 (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 будет заменено названием устанавливаемого дистрибутива модуля. В путях важны точки и заглавные буквы, например в UNIX python3.2, обычно будет соответствовать Python32 в Windows.

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

Альтернативная установка

Часто бывает необходимо или желательно устанавливать модули в место, отличное от стандартного для сторонних модулей Python. Например, в системе Unix у вас может не быть разрешения на запись в стандартный каталог сторонних модулей. Или вы можете попробовать модуль, прежде чем сделать его стандартной частью вашей локальной установки Python. Это особенно верно при обновлении уже существующего дистрибутива: вы хотите убедиться, что ваша существующая база скриптов всё ещё работает с новой версией, перед фактическим обновлением.

Команда Distutils install предназначена для упрощения и безболезненной установки дистрибутивов модулей в другое место. Основная идея заключается в том, что вы указываете базовый каталог для установки, а команда install выбирает набор каталогов (называемых схема установки) в этом базовом каталоге для установки файлов. Детали различаются для разных платформ, поэтому прочтите, какой из следующих разделов относится к вам.

Обратите внимание, что различные альтернативные схемы установки являются взаимоисключающими: вы можете передать --user, или --home, или --prefix и --exec-prefix, или --install-base и --install-platbase, но вы не можете смешивать из этих групп.

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

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

python setup.py install --user

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

Тип файла	Каталог установки
модули	userbase/lib/pythonX.Y/site-packages
скрипты	userbase/bin
данные	userbase
C инклудники	userbase/include/pythonX.Yabiflags/distname

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

Тип файла	Каталог установки
модули	userbase\PythonXY\site-packages
скрипты	userbase\PythonXY\Scripts
данные	userbase
C инклудники	userbase\PythonXY\Include{distname}

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

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

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

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

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

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

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

python setup.py install --home=~

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

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

Тип файла	Каталог установки
модули	home/lib/python
скрипты	home/bin
данные	home
C инклудники	home/include/python/distname

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

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

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

Во-первых, учтите, что многие дистрибутивы Linux помещают Python в /usr, а не в более традиционный /usr/local. Это вполне уместно, поскольку в этих случаях Python является частью «системы», а не локальным дополнением. Однако, если вы устанавливаете модули Python из исходного кода, вы вероятно захотите чтобы они были в /usr/local/lib/python2.X, а не в /usr/lib/python2.X. Это можно сделать с помощью:

/usr/bin/python setup.py install --prefix=/usr/local

Другой возможностью является сетевая файловая система, в которой имя, используемое для записи в удаленный каталог, отличается от имени, используемого для его чтения: например, интерпретатор Python, доступный как /usr/local/bin/python, может искать модули в /usr/local/lib/python2.X, но эти модули должны быть установлены в /mnt/@server/export/lib/python2.X. Это можно сделать с помощью:

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export

В любом случае параметр --prefix определяет базу установки, а параметр --exec-prefix определяет базу установки для конкретной платформы, которая используется для файлов для конкретной платформы. (В настоящее время это означает только не чистые дистрибутивы модулей, но его можно расширить до библиотек C, двоичных исполняемых файлов и т.д.) Если --exec-prefix не предоставляется, по умолчанию используется --prefix. Файлы устанавливаются следующим образом :

Тип файла	Каталог установки
модули Python	prefix/lib/pythonX.Y/site-packages
модули расширения	exec-prefix/lib/pythonX.Y/site-packages
скрипты	prefix/bin
данные	prefix
C инклудники	prefix/include/pythonX.Yabiflags/distname

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

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

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

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

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

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

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

Тип файла	Каталог установки
модули	prefix\Lib\site-packages
скрипты	prefix\Scripts
данные	prefix
C инклудники	prefix\Include{distname}

Пользовательская установка

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

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

Тип файла	Опция переопределения
модули Python	--install-purelib
модули расширения	--install-platlib
все модули	--install-lib
скрипты	--install-scripts
данные	--install-data
C инклудники	--install-headers

Эти параметры переопределения могут быть относительными, абсолютными или явно определенными в терминах одного из базовых каталогов установки. (Существует два установочных базовых каталога, и обычно они одинаковы —- они отличаются только при использовании «схемы префиксов» Unix и поставьте различные варианты --prefix и --exec-prefix; использование --install-lib переопределит значения, вычисленные или заданные для --install-purelib и --install- platlib, и рекомендуется для схем, которые не делают разницы между Python и модулями расширения.)

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

python setup.py install --home=~ --install-scripts=scripts

Другой пример Unix: предположим, что ваша установка Python была построена и установлена с префиксом /usr/local/python, поэтому при стандартной установке скрипты будут находиться в /usr/local/python/bin. Если вы хотите, чтобы они были в /usr/local/bin вместо этого, вы бы предоставили этот абсолютный каталог для опции --install-scripts:

python setup.py install --install-scripts=/usr/local/bin

Это выполняет установку с использованием «схемы префиксов», где префикс — это то, что ваш интерпретатор Python был установлен с помощью /usr/local/python в данном случае.

Если вы поддерживаете Python в Windows, вам может потребоваться, чтобы сторонние модули располагались в подкаталоге prefix, а не прямо в самом prefix. Это почти так же просто, как настроить каталог установки скрипта, — вам просто нужно помнить, что есть два типа модулей, о которых нужно беспокоиться, Python и модули расширения, которыми можно удобно управлять с помощью одной опции:

python setup.py install --install-lib=Site

Указанный каталог установки относится к prefix. Конечно, вы также должны убедиться, что этот каталог находится в пути поиска модуля Python, например, поместив файл .pth в каталог сайта (см. site). См. Раздел Изменение пути поиска Python, чтобы узнать, как изменить путь поиска Python.

Если вы хотите определить всю схему установки, вам просто нужно указать все параметры каталога установки. Рекомендуемый способ сделать это — указать относительные пути; например, если вы хотите сохранить все файлы, связанные с модулем Python, в python в своем домашнем каталоге и хотите отдельный каталог для каждой платформы, с которой вы используете свой домашний каталог, вы можете определить следующую схему установки:

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data

или, что то же самое:

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data

$PLAT не является (обязательно) переменной окружения — она будет расширена Distutils, когда она анализирует ваши параметры командной строки, так же, как он это делает при разборе вашего файла(ов) конфигурации.

Очевидно, что указывать всю схему установки каждый раз, когда вы устанавливаете новый дистрибутив модуля, было бы очень утомительно. Таким образом, вы можете поместить эти параметры в конфигурационный файл Distutils (см. раздел Файлы конфигурации Distutils) :

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data

или, что то же самое

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data

Обратите внимание, что эти два не эквивалентны, если вы указываете другой базовый каталог установки при запуске сценария установки. Например

python setup.py install --install-base=/tmp

установил бы чистые модули в /tmp/python/lib в первом случае и в /tmp/lib во втором. (Для второго случая вы, вероятно, захотите поставить установочную базу /tmp/python.)

Вы, наверное, заметили использование $HOME и $PLAT во входном файле конфигурации примера. Это переменные конфигурации Distutils, которые очень похожи на переменные среды. Фактически, вы можете использовать переменные среды в файлах конфигурации на платформах, которые имеют такое понятие, но Distutils дополнительно определяет несколько дополнительных переменных, которые могут отсутствовать в вашей среде, например $PLAT. (И, конечно же, в системах, не имеющих переменных среды, таких как Mac OS 9, переменные конфигурации, предоставленные Distutils, - единственные, которые вы можете использовать.) См. подробности в разделе Файлы конфигурации Distutils.

Примечание

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

Изменение пути поиска Python

Когда интерпретатор Python выполняет оператор import, он ищет как код Python, так и модули расширения по пути поиска. Значение по умолчанию для пути настраивается в двоичном файле Python при сборке интерпретатора. Вы можете определить путь, импортировав модуль sys и распечатав значение sys.path.

$ python
Python 2.2 (#11, Oct  3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
 '/usr/local/lib/python2.3/site-packages']
>>>

Нулевая строка в sys.path представляет текущий рабочий каталог.

Ожидаемое соглашение для локально установленных пакетов — поместить их в каталог …/site-packages/, но вы можете захотеть установить модули Python в какой-нибудь произвольный каталог. Например, на вашем сайте может быть принято соглашение о хранении всего программного обеспечения, связанного с веб-сервером в /www. Дополнительные модули Python могут тогда принадлежать /www/python, и для их импорта этот каталог должен быть добавлен в sys.path. Есть несколько разных способов добавить каталог.

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

Пути могут быть абсолютными или относительными, и в этом случае они относятся к каталогу, содержащему файл .pth. См. документацию модуля site для получения дополнительной информации.

Немного менее удобный способ — отредактировать файл site.py в стандартной библиотеке Python и изменить sys.path. site.py автоматически импортируется при выполнении интерпретатора Python, если только переключатель -S не используется для подавления этого поведения. Таким образом, вы можете просто отредактировать site.py и добавить к нему две строки :

import sys
sys.path.append('/www/python/')

Однако, если вы переустановите ту же основную версию Python (например, при обновлении с 2.2 до 2.2.2), site.py будет заменен стандартной версией. Вы должны помнить, что он был изменен, и сохранить копию перед установкой.

Есть две переменные среды, которые могут изменять sys.path. PYTHONHOME устанавливает альтернативное значение для префикса установки Python. Например, если PYTHONHOME указывает на /www/python, путь поиска будет установлен на ['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...].

Переменная PYTHONPATH может быть содержать ​​список путей, которые будут добавлены в начало sys.path. Например, если для PYTHONPATH задано значение /www/python:/opt/py, путь поиска начнется с ['/www/python', '/opt/py']. (Обратите внимание, что каталоги должны существовать, чтобы их можно было добавить в sys.path; модуль site удаляет несуществующие пути.

Наконец, sys.path — это просто обычный список Python, поэтому любое приложение Python может изменять его, добавляя или удаляя записи.

Файлы конфигурации Distutils

Как упоминалось выше, вы можете использовать файлы конфигурации Distutils для записи личных предпочтений или настроек сайта для любых опций Distutils. То есть любой параметр любой команды может быть сохранен в одном из двух или трех (в зависимости от вашей платформы) файлов конфигурации, с которыми будет выполняться консультация перед анализом командной строки. Это означает, что файлы конфигурации переопределят значения по умолчанию, а командная строка, в свою очередь, переопределит файлы конфигурации. Более того, если применяется несколько файлов конфигурации, значения из «более ранних» файлов заменяются «более поздними» файлами.

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

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

Тип файла	Расположение и имя файла	Примечания
системный	prefix/lib/pythonver/distutils/distutils.cfg	(1)
личный	$HOME/.pydistutils.cfg	(2)
локальный	setup.cfg	(3)

А в Windows это файлы конфигурации :

Тип файла	Расположение и имя файла	Примечания
системный	prefix\Lib\distutils\distutils.cfg	(4)
личный	%HOME%\pydistutils.cfg	(5)
локальный	setup.cfg	(3)

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

Примечания:

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

Сборочные расширения: советы и хитрости

По возможности, Distutils пытается использовать информацию о конфигурации, предоставляемую интерпретатором Python, используемым для запуска сценария setup.py. Например, те же флаги компилятора и компоновщика, которые использовались для компиляции Python, также будут использоваться для компиляции расширений. Обычно это срабатывает, но в сложных ситуациях это может быть неуместным. В этом разделе обсуждается, как переопределить обычное поведение Distutils.

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

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

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

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

module ... [sourcefile ...] [cpparg ...] [library ...]

Рассмотрим по очереди каждое из полей.

• module — это имя создаваемого модуля расширения, которое должно быть действительным идентификатором Python. Вы не можете просто изменить его, чтобы переименовать модуль (также потребуются правки в исходный код), поэтому рекомендуется оставить в покое.
• sourcefile — это все, что может быть файлом исходного кода, по крайней мере, судя по имени файла. Предполагается, что имена файлов, оканчивающиеся на .c, написаны на языке C, имена файлов, заканчивающиеся на .C, .cc и .c++, считаются на языке C++, а имена файлов, заканчивающиеся на .m или .mm, относятся к языку Objective C.
• cpparg является аргументом препроцессора C и может начинаться с -I, -D, -U или -C.
• library — это все, что заканчивается на .a или начинается с -l или -L.

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

foo foomodule.c

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

foo foomodule.c -lm

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

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

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

Флаги компилятора также могут быть предоставлены путем установки переменной среды CFLAGS. Если установлено, содержимое CFLAGS будет добавлено к флагам компилятора, указанным в файле Setup.

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

Borland/CodeGear C++

В этом подразделе описаны необходимые шаги для использования Distutils с компилятором Borland C++ версии 5.5. Сначала вы должны знать, что формат объектного файла Borland (OMF) отличается от формата, используемого версией Python, которую вы можете загрузить с веб-сайта Python или ActiveState. (Python собран с помощью Microsoft Visual C ++, который использует COFF в качестве формата объектного файла.) По этой причине вам необходимо преобразовать библиотеку Python python25.lib в формат Borland. Сделать это можно следующим образом:

coff2omf python25.lib python25_bcpp.lib

Программа coff2omf поставляется с компилятором Borland. Файл python25.lib находится в каталоге Libs вашей установки Python. Если ваше расширение использует другие библиотеки (zlib, …), вам также необходимо преобразовать и их.

Преобразованные файлы должны находиться в тех же каталогах, что и обычные библиотеки.

Как Distutils удается использовать эти библиотеки с измененными именами? Если расширению нужна библиотека (например, foo), Distutils сначала проверяет, находит ли он библиотеку с суффиксом _bcpp (например, foo_bcpp.lib), а затем использует эту библиотеку. В случае, если такая специальная библиотека не найдена, используется имя по умолчанию (foo.lib.) [1]

Чтобы позволить Distutils скомпилировать ваше расширение с помощью Borland C++, вам нужно ввести:

python setup.py build --compiler=bcpp

Если вы хотите использовать компилятор Borland C++ по умолчанию, вы можете указать его в своем личном или общесистемном файле конфигурации для Distutils (см. раздел Файлы конфигурации Distutils.)

См.также

C++Builder компилятор

Информация о бесплатном компиляторе C++ от Borland, включая ссылки на страницы загрузки.

Создание расширений Python с помощью бесплатного компилятора Borland

Документ, описывающий, как использовать бесплатный компилятор C++ командной строки Borland для сборки Python.

GNU C / Cygwin / MinGW

В этом разделе описаны необходимые шаги для использования Distutils с компиляторами GNU C/C ++ в их дистрибутивах Cygwin и MinGW. [2] Для интерпретатора Python, созданного с помощью Cygwin, все должно работать без каких-либо из следующих шагов.

Не все расширения можно собрать с помощью MinGW или Cygwin, но многие можно. Скорее всего, не будут работать расширения, использующие C++ или зависящие от расширений Microsoft Visual C.

Чтобы позволить Distutils скомпилировать ваше расширение с помощью Cygwin, вам нужно ввести:

python setup.py build --compiler=cygwin

и для Cygwin в режиме без cygwin [3] или для типа MinGW:

python setup.py build --compiler=mingw32

Если вы хотите использовать какие-либо из этих параметров/компиляторов по умолчанию, вам следует подумать о том, чтобы записать их в свой личный или общесистемный файл конфигурации для Distutils (см. раздел Файлы конфигурации Distutils.)

Старые версии Python и MinGW

Следующие инструкции применимы только в том случае, если вы используете версию Python ниже 2.4.1 с MinGW ниже 3.0.0 (с binutils-2.13.90-20030111-1).

Для этих компиляторов требуются специальные библиотеки. Эта задача более сложная, чем для Borland C++, потому что нет программы для преобразования библиотеки. Сначала вам нужно создать список символов, которые экспортирует Python DLL. Вы можете найти хорошую программу для этой задачи по адресу https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/.

pexports python25.dll >python25.def

Расположение установленного python25.dll будет зависеть от параметров установки, а также от версии и языка Windows. При установке «только для себя» он появится в корневом каталоге установки. При общей установке он будет находиться в системном каталоге.

Затем вы можете создать из этой информации библиотеку импорта для gcc.

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

Полученная библиотека должна быть помещена в тот же каталог, что и python25.lib. (Должен существовать каталог libs в каталоге установки Python.)

Если ваше расширение использует другие библиотеки (zlib, …), возможно вам придется преобразовать их тоже. Преобразованные файлы должны находиться в тех же каталогах, что и нормальные библиотеки.

См.также

Сборка модулей Python на платформе MS Windows с помощью MinGW

Информация о создании необходимых библиотек для среды MinGW.

Сноски

[1]	Это также означает, что вы можете заменить все существующие COFF-библиотеки на одноименные OMF-библиотеки.

[2]	Посетите https://www.sourceware.org/cygwin/ для получения дополнительной информации.

[3]	Тогда у вас нет эмуляции POSIX, но вам также не нужно cygwin1.dll.