site — Модуль настройки сайта

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

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

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

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

Если файл с именем “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” с любым значением, кроме “false” (регистронезависимо), то также будут проверяться системные префиксы на наличие site-packages; в противном случае они не будут проверяться.

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

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

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

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

1. Настройка Readline

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

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

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 не-фреймворковых билдов, ~/Library/Python/X.Y для Mac фреймворковых билдов и %APPDATA%\Python в Windows. Это значение используется Distutils для вычисления каталогов установки скриптов, данных, модулей Python и т. д. для схемы установки пользователя. См. также 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. Если он ещё не инициализирован, эта функция также инициализирует его, учитывая PYTHONNOUSERSITE и USER_BASE.

Добавлен в версии 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.

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