28.13. site – Конфигурационный хук, специфичный для сайта¶site – Site-specific configuration hook

Исходный код: Lib/site.py

Этот модуль автоматически импортируется при инициализации. Автоматический импорт можно подавить с помощью флага интерпретатора -S.

Если не использовался флаг -S, импорт этого модуля добавляет специфичные для сайта пути в список поиска модулей и несколько встроенных объектов. В противном случае модуль можно безопасно импортировать без автоматических изменений пути поиска модулей или дополнений встроенных объектов. Чтобы явно запустить обычные добавления для сайта, вызовите функцию site.main().

Сначала создаются до четырёх каталогов из головной и хвостовой частей. В качестве головной части используются sys.prefix и sys.exec_prefix; пустые головные части пропускаются. В качестве хвостовой части используется пустая строка, затем lib/site-packages (в Windows) или lib/pythonX.Y/site-packages, а затем lib/site-python (в Unix и Macintosh). Для каждой уникальной комбинации головной и хвостовой частей проверяется, указывает ли она на существующий каталог; если да, он добавляется в sys.path, и также проверяется добавленный путь на наличие файлов конфигурации.

Если на один каталог выше sys.executable существует файл с именем «pyvenv.cfg», то sys.prefix и sys.exec_prefix устанавливаются в этот каталог, и он также проверяется на наличие site-packages и site-python (sys.base_prefix и sys.base_exec_prefix всегда будут «настоящими» префиксами установки Python). Если в файле «pyvenv.cfg» (файл начальной загрузки конфигурации) ключ «include-system-site-packages» имеет значение, отличное от «false» (без учёта регистра), системные префиксы всё равно будут проверяться на наличие site-packages; в противном случае – нет.

Файл конфигурации пути – это файл, имя которого имеет форму name.pth и находится в одном из четырёх указанных выше каталогов; его содержимое – дополнительные элементы (по одному на строку), которые добавляются в sys.path. Несуществующие элементы никогда не добавляются в sys.path, и не проверяется, ссылается ли элемент на каталог, а не на файл. Ни один элемент не добавляется в sys.path более одного раза. Пустые строки и строки, начинающиеся с символа #, пропускаются. Строки, начинающиеся с import (с последующим пробелом или табуляцией), выполняются.

Например, предположим, что sys.prefix и sys.exec_prefix установлены в /usr/local. Тогда библиотека Python X.Y устанавливается в /usr/local/lib/pythonX.Y. Предположим, в нём есть подкаталог /usr/local/lib/pythonX.Y/site-packages с тремя подподкаталогами foo, bar и spam, и два файла конфигурации пути: foo.pth и bar.pth. Предположим, что foo.pth содержит следующее:

# foo package configuration

foo
bar
bletch

а bar.pth содержит:

# bar package configuration

bar

Тогда в sys.path добавляются следующие специфические для версии каталоги (в указанном порядке):

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

Обратите внимание, что bletch пропущен, потому что не существует; каталог bar предшествует каталогу foo, так как bar.pth идёт раньше foo.pth в алфавитном порядке; а spam пропущен, потому что не упоминается ни в одном из файлов конфигурации пути.

После этих манипуляций с путями предпринимается попытка импортировать модуль с именем sitecustomize, который может выполнять произвольные настройки, специфичные для сайта. Обычно он создаётся системным администратором в каталоге site-packages. Если этот импорт завершается неудачей с исключением ImportError, это бесшумно игнорируется.

После этого предпринимается попытка импортировать модуль с именем usercustomize, который может выполнять произвольные пользовательские настройки, если ENABLE_USER_SITE истинно. Этот файл предназначен для создания в каталоге пользовательских site-packages (см. ниже), который является частью sys.path, если не отключён флагом -s. Исключение ImportError будет молча проигнорировано.

Обратите внимание, что для некоторых систем, не основанных на Unix, sys.prefix и sys.exec_prefix пусты, и манипуляции с путём пропускаются; однако попытка импорта sitecustomize и usercustomize всё равно предпринимается.

site.PREFIXES¶

Список префиксов для каталогов site-packages.

site.ENABLE_USER_SITE¶

Флаг, показывающий статус пользовательского каталога site-packages. Значение True означает, что он включён и добавлен в sys.path. False означает, что он был отключён по запросу пользователя (с помощью -s или PYTHONNOUSERSITE). None означает, что он был отключён по соображениям безопасности (несовпадение идентификатора пользователя или группы с эффективным идентификатором) или администратором.

site.USER_SITE¶

Путь к пользовательским site-packages для запущенного Python. Может быть равен None, если getusersitepackages() ещё не вызывалась. Значение по умолчанию: ~/.local/lib/pythonX.Y/site-packages для UNIX и сборок Mac OS X без фреймворка, ~/Library/Python/X.Y/lib/python/site-packages для сборок Mac с фреймворком, и %APPDATA%\Python\PythonXY\site-packages в Windows. Этот каталог является site-каталогом, то есть файлы .pth в нём будут обработаны.

site.USER_BASE¶

Путь к базовому каталогу для пользовательских site-packages. Может быть равен None, если getuserbase() ещё не вызывалась. Значение по умолчанию: ~/.local для UNIX и сборок Mac OS X без фреймворка, ~/Library/Python/X.Y для сборок Mac с фреймворком, и %APPDATA%\Python для Windows. Это значение используется Distutils для вычисления каталогов установки скриптов, файлов данных, модулей Python и т.д. для схемы пользовательской установки. См. также PYTHONUSERBASE.

site.main()¶

Добавляет все стандартные каталоги, специфичные для сайта, в путь поиска модулей. Эта функция вызывается автоматически при импорте этого модуля, если только интерпретатор python не был запущен с флагом -S.

Изменено в версии 3.3: Раньше эта функция вызывалась безусловно.

site.addsitedir(sitedir, known_paths=None)¶

Добавляет каталог в sys.path и обрабатывает его файлы .pth. Обычно используется в файлах sitecustomize или usercustomize (см. выше).

site.getsitepackages()¶

Возвращает список, содержащий все глобальные каталоги site-packages (и, возможно, site-python).

Новое в версии 3.2.

site.getuserbase()¶

Возвращает путь к базовому каталогу пользователя USER_BASE. Если он ещё не инициализирован, эта функция также установит его, учитывая PYTHONUSERBASE.

Новое в версии 3.2.

site.getusersitepackages()¶

Возвращает путь к каталогу site-packages, специфичному для пользователя, USER_SITE. Если он ещё не инициализирован, эта функция также устанавливает его, учитывая PYTHONNOUSERSITE и USER_BASE.

Новое в версии 3.2.

Модуль site также предоставляет способ получить пользовательские каталоги из командной строки:

$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages

Если он вызывается без аргументов, он выводит содержимое sys.path на стандартный вывод, затем значение USER_BASE и существует ли этот каталог, затем то же самое для USER_SITE, и наконец значение ENABLE_USER_SITE.

--user-base¶

Выводит путь к базовому каталогу пользователя.

--user-site¶

Выводит путь к каталогу site-packages пользователя.

Если указаны оба параметра, будут выведены базовый каталог пользователя и пользовательский каталог site-packages (всегда в этом порядке), разделённые os.pathsep.

Если указан любой из параметров, сценарий завершится с одним из следующих значений: O, если каталог site-packages пользователя включён, 1, если он был отключён пользователем, 2, если он отключён по соображениям безопасности или администратором, а значение больше 2 в случае ошибки.