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/.

Если файл с именем «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, этот модуль также импортирует и настраивает модуль rlcompleter, если Python запускается в интерактивном режиме и без опции -S. По умолчанию включена автодополнение, и используется ~/.python_history в качестве файла сохранения истории. Чтобы отключить это, удалите (или переопределите) атрибут sys.__interactivehook__ в вашем модуле sitecustomize или usercustomize или вашем файле PYTHONSTARTUP.

Изменено в версии 3.4: Активация rlcompleter и истории стала автоматической.

END_OF_DOCUMENT_MARKER

Содержание модуля

site.PREFIXES: Список префиксов для каталогов site-packages.

site.ENABLE_USER_SITE: Флаг, показывающий состояние каталога user site-packages. True означает, что он включён и был добавлен в sys.path. False означает, что он был отключён по запросу пользователя (с помощью -s или PYTHONNOUSERSITE). None означает, что он был отключён по соображениям безопасности (несовпадение идентификатора пользователя или группы с эффективным идентификатором) или администратором.

site.USER_SITE: Путь к каталогу user 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: Путь к базовому каталогу для user 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, USER_BASE. Если он ещё не инициализирован, эта функция также инициализирует его, учитывая PYTHONUSERBASE.

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

site.getusersitepackages(): Возвращает путь к каталогу user-specific 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 base.

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

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

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

См. также

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