Содержание страницы

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

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

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

Импорт этого модуля добавляет специфичные для сайта пути в путь поиска модулей и добавляет несколько встроенных функций, если не использовалась опция -S. В этом случае модуль можно безопасно импортировать без автоматических изменений в пути поиска модулей или добавления встроенных функций. Чтобы явно запустить обычное добавление специфичных для сайта путей, вызовите функцию 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`¶

После этих манипуляций с путями предпринимается попытка импортировать модуль с именем sitecustomize, который может выполнять произвольные настройки, специфичные для сайта. Обычно он создаётся системным администратором в каталоге site-packages. Если этот импорт завершается исключением ImportError или его подкласса, и атрибут name исключения равен 'sitecustomize', оно игнорируется без вывода сообщения. Если Python запущен без доступных выходных потоков, как в случае с pythonw.exe в Windows (которое используется по умолчанию для запуска IDLE), попытки вывода из sitecustomize игнорируются. Любое другое исключение вызывает молчаливый и, возможно, загадочный сбой процесса.

`usercustomize`¶

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

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

Конфигурация Readline¶Readline configuration

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

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

Содержимое модуля¶Module contents

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. Этот каталог является site-каталогом, что означает, что файлы .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.

Интерфейс командной строки¶Command Line Interface

Модуль 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 для каждого пользователя
Инициализация пути поиска модулей sys.path – Инициализация sys.path.