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

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

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

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

Изменено в версии 3.3: Импорт модуля теперь не вызывал манипуляций с путями, даже при использовании опции -S.

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

Изменено в версии 3.5: Поддержка директории «site-python» была удалена.

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

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

Примечание

Выполняемая строка в файле .pth выполняется при каждом запуске Python, независимо от того, будет ли конкретный модуль фактически использоваться. Поэтому её влияние должно быть минимальным. Основное предназначение выполняемых строк — сделать соответствующие модули импортируемыми (загрузить сторонние импортные хуки, настроить PATH и т. д.). Любая другая инициализация должна выполняться при фактическом импорте модуля, если и когда это происходит. Ограничение кода одной строкой — это целенаправленное решение, чтобы отговорить от помещения чего-то более сложного сюда.

Например, предположим, что 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 или её подклассом, и атрибут исключения name равен 'sitecustomize', ошибка игнорируется.

Если Python запускается без доступных потоков вывода, как в случае с pythonw.exe в Windows (который используется по умолчанию для запуска IDLE), попытка вывода от sitecustomize игнорируется. Любая другая ошибка приводит к тихому, а возможно и таинственному завершению процесса.

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

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

Настройка Readline

На системах, поддерживающих readline, этот модуль также импортирует и настраивает модуль rlcompleter, если Python запускается в интерактивном режиме и без опции -S. По умолчанию включена автодополнение и используется ~/.python_history в качестве файла сохранения истории. Чтобы отключить его, удалите (или перезапишите) атрибут sys.__interactivehook__ в модуле sitecustomize или usercustomize или в вашем файле PYTHONSTARTUP.

Изменено в версии 3.4: Активация rlcompleter и истории была автоматизирована.

Содержание модуля

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 и macOS-сборок не в виде фреймворка, ~/Library/Python/X.Y/lib/python/site-packages для macOS-сборок в виде фреймворка и %APPDATA%\Python\PythonXY\site-packages в Windows. Этот каталог является сайтовым каталогом, что означает, что .pth файлы в нём будут обработаны.

site.USER_BASE: Путь к базовому каталогу для site-packages пользователя. Может быть None если getuserbase() ещё не был вызван. Значение по умолчанию — ~/.local для UNIX и macOS-сборок не в виде фреймворка, ~/Library/Python/X.Y для macOS-сборок в виде фреймворка и %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.

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

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

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

site.getusersitepackages(): Возвращает путь к каталогу site-packages пользователя, USER_SITE. Если он ещё не инициализирован, эта функция также инициализирует его, учитывая USER_BASE. Чтобы определить, был ли каталог site-packages пользователя добавлен в sys.path, следует использовать ENABLE_USER_SITE.

Добавлена в версии 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.

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

См. также

PEP 370 – Каталог site-packages пользователя