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

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

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

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

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

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

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

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

Изменено в версии 3.14: site больше не отвечает за обновление sys.prefix и sys.exec_prefix в виртуальных средах. Теперь это выполняется во время инициализации путей. В результате в виртуальных средах sys.prefix и sys.exec_prefix больше не зависят от инициализации site и поэтому не затрагиваются параметром -S.

При работе в виртуальной среде файл pyvenv.cfg в sys.prefix проверяется на наличие конфигурации для конкретного сайта. Если ключ 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(prefixes=None)

Возвращает список всех глобальных каталогов site-packages.

Для каждого каталога, указанного в prefixes (или в PREFIXES, если prefixes имеет значение None), эта функция находит его подкаталог site-packages в зависимости от системного окружения и возвращает список полных путей.

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

Изменено в версии 3.3: Добавлен необязательный параметр prefixes.

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.

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

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

См. также

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