site — Сайт-специфичный хук конфигурации

Исходный код: Lib/site.py

---

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

При импорте этого модуля к пути поиска модуля добавляются сайт-специфичные пути и добавляется несколько построений, если -S не было используемый. В этом случае этот модуль можно безопасно импортировать без автоматического изменения пути поиска модуля или добавления к компоновкам. Для явного запуска обычных сайт-специфичные добавлений, вызовите функцию site.main().

Изменено в версии 3.3: Импорт модуля используемый для запуска управления путями даже при использовании -S.

Начинается с построения до четырёх каталогов из головы и хвостовой части. Для головной части используется sys.prefix и sys.exec_prefix; пустые головы пропускаются. Для хвостовой части используется пустой строка, а затем lib/site-packages (в Windows) или lib/pythonX.Y/site-packages (в Unix и Macintosh). Для каждой из различных комбинаций «голова-хвост» он видит, относится ли он к существующему каталогу, и, если да, добавляет его в sys.path, а также проверяет вновь добавленный путь для файлов конфигурации.

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

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

Например, предположим, что sys.prefix и sys.exec_prefix имеют значение /usr/local. Затем в /usr/local/lib/pythonX.Y устанавливается библиотека Python X.Y. Предположим, у него есть подкаталог /usr/local/lib/pythonX.Y/site-packages с тремя подкаталогами, foo, bar и spam, и два файла конфигурации пути, foo.pth и bar.pth. Предположим, foo.pth содержит следующее:

# foo конфигурация пакета

foo
bar
bletch

и bar.pth содержит:

# bar конфигурация пакета

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, который может выполнять произвольные настройки для конкретного сайта. Как правило, он создается системным администратором в каталоге site-packages. Если этот импорт терпит неудачу с ImportError или его исключением подкласс, и name атрибут исключения равняется 'sitecustomize', он тихо проигнорирован. Если Python запускается без доступных выходных потоков, как в pythonw.exe в Windows (который по умолчанию используемый для запуска IDLE), попытка вывода из sitecustomize игнорируется. Любое другое исключение вызывает молчаливый и, возможно, загадочный провал процесса.

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

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

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/site-packages для сборок UNIX и не-фреймворк Mac OS X, ~/Library/Python/X.Y/lib/python/site-packages для сборок Mac фреймворк и %APPDATA%\Python\PythonXY\site-packages в Windows. Этот каталог является каталогом сайта, что означает, что .pth файлы в нем будут обрабатываться.

site.USER_BASE

Путь к базовому каталогу для пользовательских site-packages. Может быть None, если getuserbase() еще не звонили. Дефолт значение - ~/.local для UNIX и Mac OS X non-фреймворк, строит, ~/Library/Python/X.Y для Mac фреймворк строит, и %APPDATA%\Python для Windows. Этот значение используемый Distutils для вычисления установочных каталогов для сценариев, файлов данных, модулей 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.

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

site.getuserbase()

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

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

site.getusersitepackages()

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

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

Интерфейс командной строки

Модуль site также предоставляет способ получения пользовательских каталогов из командной строки:

$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages

Если он вызывается без аргументов, он печатает содержимое sys.path на стандартном выходе, после чего следует значение USER_BASE и существует ли каталог, затем то же самое для USER_SITE и, наконец, значение ENABLE_USER_SITE.

--user-base

Печать пути к базовому каталогу пользователя.

--user-site

Печать пути к каталогу пользовательских site-packages.

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

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

См.также

PEP 370 – пользовательский каталог site-packages