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

Источник: Lib/site.py

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

Импорт этого модуля добавит к пути поиска модуля пути, специфичные для конкретного сайта, и добавит несколько встроенных модулей, если только не было использовано значение -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» была удалена.

Если файл с именем «pyvenv.cfg» существует на один каталог выше sys.executable, sys.prefix и sys.exec_prefix устанавливаются в этот каталог, и он также проверяется на наличие site-пакетов (sys.base_prefix и sys.base_exec_prefix всегда будут «реальными» префиксами установки Python). Если в файле pyvenv.cfg (конфигурационный файл bootstrap) ключ «include-system-site-packages» имеет значение, отличное от «true» (без учета регистра), префиксы системного уровня не будут проверяться на наличие site-пакетов; в противном случае они будут проверяться.

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

Примечание

Исполняемая строка в файле .pth запускается при каждом запуске Python, независимо от того, будет ли в действительности использоваться тот или иной модуль. Поэтому ее влияние должно быть сведено к минимуму. Основное предназначение исполняемых строк - сделать соответствующий модуль(и) импортируемым (загрузить сторонние крючки импорта, настроить PATH и т.д.). Любая другая инициализация должна выполняться при фактическом импорте модуля, если и когда это произойдет. Ограничение фрагмента кода одной строкой - это намеренная мера, чтобы не допустить размещения здесь чего-либо более сложного.

Изменено в версии 3.13: Теперь файлы .pth сначала декодируются UTF-8, а затем locale encoding, если это не удается.

Например, предположим, что 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 запущен в interactive mode и без опции -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

Путь к пользовательским сайт-пакетам для запущенного Python. Может быть None, если getusersitepackages() еще не был вызван. Значение по умолчанию - ~/.local/lib/pythonX.Y/site-packages для UNIX и нефреймворковых сборок macOS, ~/Library/Python/X.Y/lib/python/site-packages для фреймворковых сборок macOS и %APPDATA%\Python\PythonXY\site-packages в Windows. Этот каталог является каталогом сайта, что означает, что файлы .pth в нем будут обработаны.

site.USER_BASE

Путь к базовому каталогу для пользовательских сайт-пакетов. Может быть None, если getuserbase() еще не был вызван. Значение по умолчанию - ~/.local для UNIX и macOS без фреймворка, ~/Library/Python/X.Y для фреймворка macOS и %APPDATA%\Python для Windows. Это значение используется для вычисления директорий установки скриптов, файлов данных, модулей Python и т. д. для user installation scheme. См. также PYTHONUSERBASE.

site.main()

Добавляет все стандартные каталоги, специфичные для сайта, в путь поиска модуля. Эта функция вызывается автоматически при импорте этого модуля, если только интерпретатор Python не был запущен с флагом -S.

Изменено в версии 3.3: Раньше эта функция вызывалась безусловно.

site.addsitedir(sitedir, known_paths=None)

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

site.getsitepackages()

Возвращает список, содержащий все глобальные каталоги site-packages.

Added in version 3.2.

site.getuserbase()

Возвращает путь к базовому каталогу пользователя, USER_BASE. Если он еще не инициализирован, эта функция также установит его, соблюдая PYTHONUSERBASE.

Added in version 3.2.

site.getusersitepackages()

Возвращает путь к пользовательскому каталогу site-packages, USER_SITE. Если он еще не инициализирован, эта функция также установит его, соблюдая USER_BASE. Чтобы определить, был ли пользовательский каталог site-packages добавлен в sys.path. следует использовать ENABLE_USER_SITE.

Added in version 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

Выведите путь к директории пользовательского сайта-пакета.

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

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

См.также