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, а также проверяется наличие пакетов сайта (sys.base_prefix и sys.base_exec_prefix всегда будут «настоящими» префиксами при установке Python). Если «pyvenv.cfg» (файл конфигурации начальной загрузки) содержит ключ «include-system-site-packages», для которого установлено значение, отличное от «true» (без учета регистра), поиск пакетов сайта на системном уровне не будет выполняться; в противном случае он будет выполняться.

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

Примечание

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

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

sitecustomize

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

usercustomize

После этого предпринимается попытка импортировать модуль с именем usercustomize, который может выполнять произвольные пользовательские настройки, если значение ENABLE_USER_SITE равно true. Этот файл предназначен для создания в каталоге user site-packages (см. ниже), который является частью sys.path, если он не отключен по -s. Если этот импорт завершается ошибкой с исключением ImportError или его подкласса, а атрибут исключения name равен 'usercustomize', он автоматически игнорируется.

Обратите внимание, что в некоторых системах, отличных от Unix, sys.prefix и sys.exec_prefix являются пустыми, и манипуляции с путями пропускаются; однако импорт sitecustomize и usercustomize все еще выполняется.

Конфигурация строки чтения

В системах, поддерживающих readline, этот модуль также импортирует и настраивает модуль rlcompleter, если Python запущен в interactive mode и без опции -S. По умолчанию используется включение завершения работы с вкладками и использование ~/.python_history в качестве файла сохранения истории. Чтобы отключить его, удалите (или переопределите) атрибут sys.__interactivehook__ в вашем модуле sitecustomize или usercustomize или в вашем файле PYTHONSTARTUP.

Изменено в версии 3.4: Активация rlcompleter и history была произведена автоматически.

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

site.PREFIXES

Список префиксов для каталогов пакетов сайтов.

site.ENABLE_USER_SITE

Флаг, показывающий статус каталога пользовательских сайтов-пакетов. 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 framework и %APPDATA%\Python\PythonXY\site-packages для Windows. Этот каталог является каталогом сайта, что означает, что .pth файлов в нем будут обработаны.

site.USER_BASE

Путь к базовому каталогу для пользовательского сайта-пакеты. Может быть None, если getuserbase() еще не вызывался. Значением по умолчанию является ~/.local для сборок UNIX и macOS, не относящихся к фреймворку, ~/Library/Python/X.Y для сборок macOS framework и %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()

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

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

site.getuserbase()

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

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

site.getusersitepackages()

Возвращает путь к каталогу пользовательских пакетов сайта, 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

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

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

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

См.также

inspect — Осматривать живые объекты
Пользовательские интерпретаторы Python
Вернуться на верх