Документация Python неофициальный перевод
Содержание страницы

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

Исходный код: 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

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

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

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

site.USER_BASE

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

Интерфейс командной строкиCommand-line interface

Модуль 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-packages (всегда в этом порядке), разделённые os.pathsep.

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

См. также