28.14. site – Хук конфигурации для конкретного сайта¶site – Site-specific configuration hook

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

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

Импорт этого модуля добавляет пути для конкретного сайта в путь поиска модулей и добавляет несколько встроенных объектов.

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

Файл конфигурации пути – это файл, имя которого имеет вид 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, оно молча игнорируется. Если Python запущен без доступных выходных потоков, как в случае с pythonw.exe в Windows (который используется по умолчанию для запуска IDLE), попытка вывода от sitecustomize игнорируется. Любое исключение, отличное от ImportError, вызывает тихий и, возможно, загадочный сбой процесса.

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

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

site.PREFIXES¶

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

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

site.ENABLE_USER_SITE¶

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

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

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 файлы в нём будут обработаны.

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

site.USER_BASE¶

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

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

site.addsitedir(sitedir, known_paths=None)¶

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

site.getsitepackages()¶

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

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

site.getuserbase()¶

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

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

site.getusersitepackages()¶

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

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

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

$ python -m site --user-site
/home/user/.local/lib/python2.7/site-packages

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

--user-base¶

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

--user-site¶

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

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

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