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

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

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

Обычно импорт этого модуля добавляет специфичные для сайта пути к пути поиска модулей и добавляет вызываемые объекты, включая help(), во встроенное пространство имен. Однако параметр запуска Python -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» удалена.

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

Например, предположим, что 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 имеет значение true. Предполагается, что этот файл будет создан в пользовательском каталоге 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 без framework, ~/Library/Python/X.Y/lib/python/site-packages для сборок macOS с framework и %APPDATA%\Python\PythonXY\site-packages в Windows. Этот каталог является каталогом сайта, то есть находящиеся в нем файлы .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-packages (всегда именно в таком порядке), разделенные os.pathsep.

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

См. также

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