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, если произошла ошибка.
См.также
PEP 370 – Каталог пакетов сайта для каждого пользователя
Инициализация пути поиска модуля sys.path – Инициализация
sys.path
.