site — Хук конфигурации для конкретного сайта

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

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

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

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

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

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

Изменено в версии 3.13: В Unix установки Python со свободной потокобезопасностью обозначаются суффиксом «t» в имени каталога для конкретной версии, например lib/python3.13t/.

Если на уровень выше sys.executable существует файл с именем «pyvenv.cfg», 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 и т. д.). Любую другую инициализацию следует выполнять при фактическом импорте модуля, если и когда он будет импортирован. Ограничение фрагмента кода одной строкой введено намеренно, чтобы не допустить размещения здесь чего-либо более сложного.

Изменено в версии 3.13: Сначала файлы .pth декодируются в UTF-8, а при неудаче — с использованием кодировки локали.

Например, предположим, что 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

После этого, если 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[t]/site-packages для сборок UNIX и macOS без framework, ~/Library/Python/X.Y/lib/python/site-packages для сборок macOS с framework и %APPDATA%\Python\PythonXY\site-packages в Windows. Необязательный суффикс «t» обозначает сборку со свободной потокобезопасностью. Это каталог сайта, то есть находящиеся в нём файлы .pth обрабатываются.

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

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

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

--user-base: Выводит путь к базовому пользовательскому каталогу.

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

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

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

См. также

PEP 370 — пользовательский каталог site-packages
Инициализация пути поиска модулей sys.path — инициализация sys.path.