site — Модуль настройки сайта

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

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

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

Он начинает с построения до четырёх каталогов из части заголовка и части хвоста. Для части заголовка он использует sys.prefix и sys.exec_prefix; пустые заголовки пропускаются. Для части хвоста он использует пустую строку, а затем lib/site-packages (в Windows) или lib/pythonX.Y/site-packages и затем lib/site-python (в Unix и Macintosh). Для каждой комбинации заголовок-хвост он проверяет, является ли это существующим каталогом, и если да, добавляет его в 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 истинно. Этот файл должен создаваться в каталоге 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. Этот каталог — это каталог сайта, что означает, что файлы .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 пользователя.

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

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