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

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

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

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

site.USER_BASE

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

Выводит путь к каталогу site-packages, специфичному для пользователя.

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

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