sysconfig — доступ к сведениям о конфигурации Python

Переменные конфигурации

Дистрибутив Python содержит файлы заголовков Makefile и pyconfig.h, необходимые для сборки как самого бинарного файла Python, так и сторонних расширений на C, компилируемых с помощью setuptools.

Модуль sysconfig помещает все переменные, найденные в этих файлах, в словарь, доступный с помощью get_config_vars() или get_config_var().

Обратите внимание, что в Windows этот набор гораздо меньше.

sysconfig.get_config_vars(*args)

Без аргументов возвращает словарь всех переменных конфигурации, относящихся к текущей платформе.

С аргументами возвращает список значений, полученных при поиске каждого аргумента в словаре переменных конфигурации.

Если значение для какого-либо аргумента не найдено, возвращает None.

sysconfig.get_config_var(name)

Возвращает значение одной переменной name. Эквивалентно get_config_vars().get(name).

Если name не найдено, возвращает None.

Пример использования:

>>> import sysconfig
>>> sysconfig.get_config_var('Py_ENABLE_SHARED')
0
>>> sysconfig.get_config_var('LIBDIR')
'/usr/local/lib'
>>> sysconfig.get_config_vars('AR', 'CXX')
['ar', 'g++']

Пути установки

Python использует схему установки, которая зависит от платформы и параметров установки. Эти схемы хранятся в sysconfig под уникальными идентификаторами, основанными на значении, возвращаемом os.name. Схемы используются установщиками пакетов для определения места копирования файлов.

В настоящее время Python поддерживает девять схем:

• posix_prefix: схема для POSIX-платформ, таких как Linux или macOS. Это схема по умолчанию при установке Python или его компонента.
• posix_home: схема для POSIX-платформ, используемая, когда задан параметр home. Эта схема определяет пути внутри указанного префикса домашнего каталога.
• posix_user: схема для POSIX-платформ, используемая, когда задан параметр user. Эта схема определяет пути внутри домашнего каталога пользователя (site.USER_BASE).
• posix_venv: схема для Python virtual environments на POSIX-платформах; по умолчанию совпадает с posix_prefix.
• nt: схема для Windows. Это схема по умолчанию при установке Python или его компонента.
• nt_user: схема для Windows, используемая, когда задан параметр user.
• nt_venv: схема для Python virtual environments в Windows; по умолчанию совпадает с nt.
• venv: схема со значениями из posix_venv или nt_venv в зависимости от платформы, на которой выполняется Python.
• osx_framework_user: схема для macOS, используемая, когда задан параметр user.

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

• stdlib: каталог со стандартными файлами библиотеки Python, не зависящими от платформы.
• platstdlib: каталог со стандартными файлами библиотеки Python, зависящими от платформы.
• platlib: каталог для файлов, зависящих от платформы и предназначенных для конкретного сайта.
• purelib: каталог для файлов, не зависящих от платформы и предназначенных для конкретного сайта («чистый» Python).
• include: каталог для файлов заголовков Python C-API, не зависящих от платформы.
• platinclude: каталог для файлов заголовков Python C-API, зависящих от платформы.
• scripts: каталог для файлов скриптов.
• data: каталог для файлов данных.

Пользовательская схема

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

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

Схема home

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

Схема prefix

«Схема prefix» полезна, если вы хотите использовать одну установку Python для сборки/установки (то есть для запуска скрипта настройки), но устанавливать модули в каталог сторонних модулей другой установки Python (или чего-то, что выглядит как другая установка Python). Это может показаться немного необычным — поэтому сначала рассматриваются пользовательская схема и схема home. Однако есть как минимум два известных случая, когда схема prefix может пригодиться.

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

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

Функции для работы с путями установки

sysconfig предоставляет несколько функций для определения этих путей установки.

sysconfig.get_scheme_names()

Возвращает кортеж со всеми схемами, поддерживаемыми в настоящее время в sysconfig.

sysconfig.get_default_scheme()

Возвращает имя схемы по умолчанию для текущей платформы.

Добавлено в версии 3.10: Ранее эта функция называлась _get_default_scheme() и считалась деталью реализации.

Изменено в версии 3.11: Если Python выполняется в виртуальном окружении, возвращается схема venv.

sysconfig.get_preferred_scheme(key)

Возвращает предпочтительное имя схемы для макета установки, заданного параметром key.

key должен быть равен "prefix", "home" или "user".

Возвращаемое значение — имя схемы из списка, предоставляемого get_scheme_names(). Его можно передать функциям sysconfig, принимающим аргумент scheme, например get_paths().

Добавлено в версии 3.10.

Изменено в версии 3.11: Если Python выполняется в виртуальном окружении и key="prefix", возвращается схема venv.

sysconfig._get_preferred_schemes()

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

Конечным пользователям не следует использовать эту функцию: вместо неё следует использовать get_default_scheme() и get_preferred_scheme().

Добавлено в версии 3.10.

sysconfig.get_path_names()

Возвращает кортеж со всеми именами путей, поддерживаемыми в настоящее время в sysconfig.

sysconfig.get_path(name[, scheme[, vars[, expand]]])

Возвращает путь установки, соответствующий пути name, из схемы установки с именем scheme.

name должен быть одним из значений списка, возвращаемого get_path_names().

sysconfig хранит пути установки для каждого имени пути и каждой платформы вместе с переменными, значения которых нужно подставить. Например, путь stdlib для схемы nt — это: {base}/Lib.

get_path() использует переменные, возвращаемые get_config_vars(), чтобы подставить их значения в путь. Для каждой платформы у всех переменных есть значения по умолчанию, поэтому эту функцию можно вызвать и получить значение по умолчанию.

Если задан scheme, он должен быть одним из значений списка, возвращаемого get_scheme_names(). В противном случае используется схема по умолчанию для текущей платформы.

Если задан vars, это должен быть словарь переменных, которым будет обновлён словарь, возвращаемый get_config_vars().

Если для expand задано значение False, переменные не будут подставлены в путь.

Если name не найдено, возбуждается исключение KeyError.

sysconfig.get_paths([scheme[, vars[, expand]]])

Возвращает словарь со всеми путями установки, соответствующими схеме установки. Дополнительную информацию см. в описании get_path().

Если scheme не задан, используется схема по умолчанию для текущей платформы.

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

Если для expand задано значение false, подстановка значений в пути не выполняется.

Если scheme не является существующей схемой, get_paths() возбуждает исключение KeyError.

Другие функции

sysconfig.get_python_version()

Возвращает номер версии Python MAJOR.MINOR в виде строки. Аналогично '%d.%d' % sys.version_info[:2].

sysconfig.get_platform()

Возвращает строку, идентифицирующую текущую платформу.

Она используется главным образом для различения каталогов сборки и собранных дистрибутивов, зависящих от платформы. Обычно строка включает название и версию ОС, а также архитектуру (согласно данным os.uname()), хотя точный набор сведений зависит от ОС; например, в Linux версия ядра не особенно важна.

Примеры возвращаемых значений:

• linux-i586
• linux-alpha (?)
• solaris-2.6-sun4u

В Windows возвращается одно из следующих значений:

• win-amd64 (64-разрядная Windows на AMD64, также известной как x86_64, Intel64 и EM64T)
• win-arm64 (64-разрядная Windows на ARM64, также известной как AArch64)
• win32 (все остальные случаи — в частности, возвращается значение sys.platform)

В macOS могут возвращаться следующие значения:

• macosx-10.6-ppc
• macosx-10.4-ppc64
• macosx-10.3-i386
• macosx-10.4-fat

Для других платформ, не относящихся к POSIX, в настоящее время просто возвращается значение sys.platform.

sysconfig.is_python_build()

Возвращает True, если выполняемый интерпретатор Python был собран из исходного кода и запускается из каталога сборки, а не из каталога, полученного, например, после запуска make install или установки с помощью бинарного установщика.

sysconfig.parse_config_h(fp[, vars])

Разбирает файл в формате config.h.

fp — файловый объект, указывающий на файл в формате config.h.

Возвращается словарь пар «имя/значение». Если в качестве второго аргумента передан необязательный словарь, вместо создания нового словаря используется он, и в него добавляются значения, прочитанные из файла.

sysconfig.get_config_h_filename()

Возвращает путь к pyconfig.h.

sysconfig.get_makefile_filename()

Возвращает путь к Makefile.

Использование sysconfig в качестве скрипта

Модуль sysconfig можно запустить как скрипт с параметром Python -m:

$ python -m sysconfig
Platform: "macosx-10.4-i386"
Python version: "3.2"
Current installation scheme: "posix_prefix"

Paths:
        data = "/usr/local"
        include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
        platinclude = "."
        platlib = "/usr/local/lib/python3.2/site-packages"
        platstdlib = "/usr/local/lib/python3.2"
        purelib = "/usr/local/lib/python3.2/site-packages"
        scripts = "/usr/local/bin"
        stdlib = "/usr/local/lib/python3.2"

Variables:
        AC_APPLE_UNIVERSAL_BUILD = "0"
        AIX_GENUINE_CPLUSPLUS = "0"
        AR = "ar"
        ARFLAGS = "rc"
        ...

Этот вызов выведет в стандартный поток вывода сведения, возвращаемые функциями get_platform(), get_python_version(), get_path() и get_config_vars().