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

`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» указывает на сборку со свободной потоковой обработкой и добавляется, если в константе sys.abiflags присутствует "t".) Для каждой уникальной комбинации головной и хвостовой частей проверяется, указывает ли она на существующую директорию, и если да, то она добавляется в sys.path, а также проверяется новый путь на наличие конфигурационных файлов.

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

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

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

Изменено в версии 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 всё равно предпринимается.

Конфигурация 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[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, если произошла ошибка.

См. также

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