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

Расширения путей (файлы .pth)¶Path extensions (.pth files)

name.pth содержит дополнительные элементы (по одному на строку), которые добавляются к sys.path. Элементы, указывающие на несуществующие каталоги, никогда не добавляются в sys.path, и не проверяется, что элемент ссылается на каталог, а не на файл. Ни один элемент не добавляется в sys.path более одного раза. Пустые строки и строки, начинающиеся с #, пропускаются.

Для обратной совместимости строки, начинающиеся с import (с последующим пробелом или табуляцией), выполняются с помощью exec().

Точки входа при запуске (файлы .start)¶Startup entry points (.start files)

Файл точки входа при запуске – это файл, имя которого имеет форму name.start и который находится в одном из каталогов site-packages, описанных выше. Каждый файл задаёт точки входа, которые вызываются при запуске интерпретатора, используя синтаксис pkg.mod:callable, понимаемый pkgutil.resolve_name().

Каждая непустая строка, не начинающаяся с #, должна содержать ссылку на точку входа в форме pkg.mod:callable. Двоеточие и часть с вызываемым объектом обязательны. Каждый вызываемый объект вызывается без аргументов, и любое возвращаемое значение отбрасывается.

Файлы .start обрабатываются после того, как все расширения путей .pth были применены к sys.path, что гарантирует доступность путей до выполнения любого кода запуска.

В отличие от расширений sys.path из файлов .pth, дубликаты точек входа не дедуплицируются – если точка входа встречается несколько раз, она будет вызвана несколько раз.

Если во время разрешения или вызова точки входа возникает исключение, трассировка выводится в sys.stderr, и обработка продолжается с оставшимися точками входа.

Файлы .start должны быть закодированы в UTF-8.

PEP 829 определил оригинальную спецификацию для этих возможностей.

Примеры файлов запуска¶Startup file examples

Например, предположим, что 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 пропущен, так как не упоминается ни в одном файле конфигурации путей.

Допустим, также есть файл foo.start, содержащий следующее:

# foo package startup code

foo.submod:initialize

Теперь, после того как sys.path был расширен, как указано выше, и до того, как Python передаст управление пользовательскому коду, импортируется модуль foo.submod и вызывается функция initialize() из этого модуля.

Миграция со строк import в файлах .pth на файлы .start¶Migrating from import lines in .pth files to .start files

Если ваш пакет в настоящее время поставляет файл name.pth, вы можете оставить все строки расширения sys.path без изменений. Мигрировать нужно только строки import.

Для миграции создайте вызываемый объект (принимающий ноль аргументов) внутри импортируемого модуля вашего пакета. Укажите его как точку входа pkg.mod:callable в соответствующем файле name.start. Перенесите всё, что находится в вашей строке import после первой точки с запятой, в функцию callable().

Если ваш пакет должен поддерживать как старые версии Python, не поддерживающие PEP 829, так и новые, которые его поддерживают, измените строки import в вашем файле name.pth, чтобы они использовали следующую форму:

import pkg.mod; pkg.mod.callable()

Старые версии Python будут выполнять эти строки import, а новые версии будут игнорировать их в пользу файла name.start. После периода поддержки обеих версий удалите все строки import из ваших файлов .pth.

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.

Содержимое модуля¶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.makepath(*paths)¶

Объединяет paths с os.path.join(), пытается сделать результат абсолютным с помощью os.path.abspath() и возвращает кортеж из двух элементов, содержащий абсолютный путь и его форму, нормализованную по регистру, как получено из os.path.normcase(). Если os.path.abspath() возбуждает OSError, объединённый путь используется без изменений для нормализации регистра.

Второй элемент возвращаемого кортежа – это форма, используемая во всём модуле site для сравнения путей в файловых системах, нечувствительных к регистру, и именно она заполняет множества known_paths, предотвращающие дублирование записей sys.path в различных API этого модуля.

class site.StartupState(known_paths=None)¶

Экземпляры этого класса накапливают данные конфигурации запуска интерпретатора из одного или нескольких каталогов site. Они являются предпочтительным интерфейсом для пакетной обработки файлов .pth и .start в нескольких каталогах site, чтобы каждое расширение sys.path было видимым до выполнения любого стартового кода.

Необязательный аргумент known_paths – это множество путей, нормализованных по регистру (которые могут быть получены с помощью makepath()), используемое для предотвращения дублирования записей sys.path. Когда None (значение по умолчанию), множество строится из текущего sys.path. main() неявно использует экземпляр этого класса.

Типичное использование:

state = site.StartupState()
for sitedir in site_dirs:
    state.addsitedir(sitedir)
state.process()

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

addsitedir(sitedir)¶

Читает файлы .pth и .start в каталоге sitedir и записывает их расширения sys.path, устаревшие строки .pth import и точки входа .start в это состояние. Записанные данные не применяются до вызова process().

addusersitepackages()¶

Добавляет каталог пользовательских site-packages, если он включён и существует. Данные запуска каталога накапливаются для последующей обработки process().

addsitepackages(prefixes=None)¶

Добавляет глобальные каталоги site-packages, вычисленные из prefixes или из глобального PREFIXES, когда prefixes равно None. Данные запуска каждого каталога накапливаются для последующей обработки process().

process()¶

Применяет накопленное состояние, сначала добавляя расширения путей к sys.path, затем выполняя точки входа файлов .start и строки import файлов .pth (устарело).

Этот метод не является идемпотентным и не должен вызываться более одного раза на одном экземпляре. Это приведёт к повторному применению накопленного состояния, повторному запуску точек входа и строк import.

site.addsitedir(sitedir, known_paths=None)¶

Добавляет каталог в sys.path и разбирает файлы .pth и .start, найденные в этом каталоге. Обычно используется в sitecustomize или usercustomize (см. выше).

Аргумент known_paths – необязательное множество путей, нормализованных по регистру, используемое для предотвращения дублирования записей sys.path. Когда None (значение по умолчанию), множество строится из текущего sys.path.

Для пакетной обработки в нескольких каталогах site явно создайте StartupState и вызовите StartupState.addsitedir() на нём; это откладывает обработку .pth и .start до одного вызова StartupState.process(), гарантируя, что каждое расширение sys.path будет видимым до выполнения любого стартового кода.

Изменено в версии 3.15: Также обрабатывает файлы .start. См. Стартовые точки входа (.start файлы).

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, если произошла ошибка.