`site.md`

153 строк · 20.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/library/site.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `site` – перехватчик конфигурации для конкретного сайта89**Исходный код:** [Lib/site.py](https://python-all.ru/src/3.14/Lib/site.py)1011---1213**Этот модуль автоматически импортируется при инициализации.** Автоматический импорт можно отключить с помощью опции интерпретатора [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S).1415Обычно импорт этого модуля добавляет специфичные для сайта пути в путь поиска модулей и добавляет [вызываемые объекты](https://python-all.ru/3.14/library/constants.html#site-consts), включая [`help()`](https://python-all.ru/3.14/library/functions.html#help), в пространство имён встроенных функций. Однако опция запуска Python [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S) блокирует это, и данный модуль можно безопасно импортировать без автоматических изменений пути поиска модулей или добавлений во встроенные пространства имён. Чтобы явно запустить обычные добавления для конкретного сайта, вызовите функцию [`main()`](https://python-all.ru/3.14/library/site.html#site.main).1617Изменено в версии 3.3: Раньше импорт модуля запускал изменение путей даже при использовании [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S).1819Он начинается с построения до четырёх каталогов из начальной и конечной части. Для начальной части используются `sys.prefix` и `sys.exec_prefix`; пустые начальные части пропускаются. Для конечной части используется пустая строка, а затем `lib/site-packages` (в Windows) или `lib/pythonX.Y[t]/site-packages` (в Unix и macOS). (Необязательный суффикс «t» обозначает [сборку со свободной потоковой поддержкой](https://python-all.ru/3.14/glossary.html#term-free-threaded-build) и добавляется, если `"t"` присутствует в константе [`sys.abiflags`](https://python-all.ru/3.14/library/sys.html#sys.abiflags).) Для каждой из различных комбинаций начальной и конечной частей проверяется, существует ли соответствующий каталог; если да, он добавляется в `sys.path`, и вновь добавленный путь также проверяется на наличие файлов конфигурации.2021Изменено в версии 3.5: Поддержка каталога «site-python» удалена.2223Изменено в версии 3.13: В Unix установки Python с [свободной многопоточностью](https://python-all.ru/3.14/glossary.html#term-free-threading) идентифицируются суффиксом «t» в имени каталога, зависящего от версии, например `lib/python3.13t/`.2425Изменено в версии 3.14: `site` больше не отвечает за обновление [`sys.prefix`](https://python-all.ru/3.14/library/sys.html#sys.prefix) и [`sys.exec_prefix`](https://python-all.ru/3.14/library/sys.html#sys.exec_prefix) в [виртуальных окружениях](https://python-all.ru/3.14/library/sys_path_init.html#sys-path-init-virtual-environments). Теперь это делается во время [инициализации путей](https://python-all.ru/3.14/library/sys_path_init.html#sys-path-init). В результате в [виртуальных окружениях](https://python-all.ru/3.14/library/sys_path_init.html#sys-path-init-virtual-environments) `sys.prefix` и `sys.exec_prefix` больше не зависят от инициализации `site` и, следовательно, не подвержены влиянию [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S).2627При запуске в [виртуальном окружении](https://python-all.ru/3.14/library/sys_path_init.html#sys-path-init-virtual-environments) файл `pyvenv.cfg` в [`sys.prefix`](https://python-all.ru/3.14/library/sys.html#sys.prefix) проверяется на наличие специфичных для сайта конфигураций. Если ключ `include-system-site-packages` существует и установлен в `true` (без учёта регистра), будут искаться системные префиксы для site-packages, иначе нет.2829Файл конфигурации пути – это файл, имя которого имеет вид `name.pth` и находится в одном из четырёх упомянутых выше каталогов; его содержимое – это дополнительные элементы (по одному на строку), которые добавляются в `sys.path`. Несуществующие элементы никогда не добавляются в `sys.path`, и не проверяется, является ли элемент каталогом, а не файлом. Ни один элемент не добавляется в `sys.path` более одного раза. Пустые строки и строки, начинающиеся с `#`, пропускаются. Строки, начинающиеся с `import` (с последующим пробелом или табуляцией), выполняются.3031> **Примечание**32>33> Исполняемая строка в файле `.pth` выполняется при каждом запуске Python, независимо от того, будет ли фактически использоваться какой-либо конкретный модуль. Поэтому её влияние должно быть минимальным. Основная цель исполняемых строк – сделать соответствующие модули импортируемыми (загрузить сторонние хуки импорта, настроить `PATH` и т.д.). Любая другая инициализация должна выполняться при фактическом импорте модуля, если и когда он происходит. Ограничение фрагмента кода одной строкой – это намеренная мера, чтобы предотвратить размещение здесь чего-то более сложного.3435Изменено в версии 3.13: Файлы `.pth` теперь сначала декодируются в UTF-8, а затем, в случае неудачи, в [кодировке локали](https://python-all.ru/3.14/glossary.html#term-locale-encoding).3637Например, предположим, что `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` содержит следующее:3839```text40# foo package configuration4142foo43bar44bletch45```4647а `bar.pth` содержит:4849```text50# bar package configuration5152bar53```5455Затем следующие каталоги, зависящие от версии, добавляются в `sys.path` в следующем порядке:5657```text58/usr/local/lib/pythonX.Y/site-packages/bar59/usr/local/lib/pythonX.Y/site-packages/foo60```6162Обратите внимание, что `bletch` пропущен, потому что не существует; каталог `bar` предшествует каталогу `foo`, поскольку `bar.pth` находится по алфавиту перед `foo.pth`; а `spam` пропущен, так как не упоминается ни в одном файле конфигурации путей.6364## `sitecustomize`6566После этих манипуляций с путями предпринимается попытка импортировать модуль с именем `sitecustomize`, который может выполнять произвольные настройки для конкретного сайта. Обычно он создаётся системным администратором в каталоге site-packages. Если этот импорт завершается с исключением [`ImportError`](https://python-all.ru/3.14/library/exceptions.html#ImportError) или его подклассом, и атрибут исключения [`name`](https://python-all.ru/3.14/library/exceptions.html#ImportError.name) равен `'sitecustomize'`, он игнорируется без вывода сообщений. Если Python запущен без доступных потоков вывода, как в случае с `pythonw.exe` на Windows (используется по умолчанию для запуска IDLE), любые попытки вывода из `sitecustomize` игнорируются. Любое другое исключение приводит к тихому и, возможно, загадочному сбою процесса.6768## `usercustomize`6970После этого предпринимается попытка импортировать модуль с именем `usercustomize`, который может выполнять произвольные настройки для конкретного пользователя, если [`ENABLE_USER_SITE`](https://python-all.ru/3.14/library/site.html#site.ENABLE_USER_SITE) истинно. Этот файл должен быть создан в каталоге пользовательских site-packages (см. ниже), который является частью `sys.path`, если не отключён с помощью [`-s`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-s). Если этот импорт завершается с исключением [`ImportError`](https://python-all.ru/3.14/library/exceptions.html#ImportError) или его подклассом, и атрибут исключения [`name`](https://python-all.ru/3.14/library/exceptions.html#ImportError.name) равен `'usercustomize'`, он игнорируется без вывода сообщений.7172Обратите внимание, что для некоторых систем, не являющихся Unix, `sys.prefix` и `sys.exec_prefix` пусты, и манипуляции с путями пропускаются; однако импорт [`sitecustomize`](https://python-all.ru/3.14/library/site.html#module-sitecustomize) и `usercustomize` всё равно предпринимается.7374## Конфигурация Readline7576В системах, поддерживающих [`readline`](https://python-all.ru/3.14/library/readline.html#module-readline), этот модуль также импортирует и настраивает модуль [`rlcompleter`](https://python-all.ru/3.14/library/rlcompleter.html#module-rlcompleter), если Python запущен в [интерактивном режиме](https://python-all.ru/3.14/tutorial/interpreter.html#tut-interactive) и без опции [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S). Поведение по умолчанию – включить автодополнение по табуляции и использовать `~/.python_history` в качестве файла для сохранения истории. Чтобы отключить это, удалите (или переопределите) атрибут [`sys.__interactivehook__`](https://python-all.ru/3.14/library/sys.html#sys.__interactivehook__) в вашем модуле [`sitecustomize`](https://python-all.ru/3.14/library/site.html#module-sitecustomize) или [`usercustomize`](https://python-all.ru/3.14/library/site.html#module-usercustomize), или в файле [`PYTHONSTARTUP`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONSTARTUP).7778Изменено в версии 3.4: Активация rlcompleter и истории стала автоматической.7980## Содержимое модуля8182#### `site.PREFIXES`8384Список префиксов для каталогов site-packages.8586#### `site.ENABLE_USER_SITE`8788Флаг, показывающий статус каталога пользовательских site-packages. `True` означает, что он включён и был добавлен в `sys.path`. `False` означает, что он был отключён по запросу пользователя (с помощью [`-s`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-s) или [`PYTHONNOUSERSITE`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONNOUSERSITE)). `None` означает, что он был отключён по соображениям безопасности (несовпадение идентификатора пользователя или группы с эффективным идентификатором) или администратором.8990#### `site.USER_SITE`9192Путь к пользовательским site-packages для запущенного Python. Может быть `None`, если [`getusersitepackages()`](https://python-all.ru/3.14/library/site.html#site.getusersitepackages) ещё не была вызвана. Значение по умолчанию: `~/.local/lib/pythonX.Y[t]/site-packages` для UNIX и сборок macOS без фреймворка, `~/Library/Python/X.Y/lib/python/site-packages` для сборок macOS с фреймворком и `%APPDATA%\Python\PythonXY\site-packages` для Windows. Необязательный суффикс «t» указывает на сборку со свободной потоковой поддержкой. Этот каталог является сайтовым каталогом, что означает, что файлы `.pth` в нём будут обработаны.9394#### `site.USER_BASE`9596Путь к базовому каталогу для пользовательских site-packages. Может быть `None`, если [`getuserbase()`](https://python-all.ru/3.14/library/site.html#site.getuserbase) ещё не была вызвана. Значение по умолчанию: `~/.local` для UNIX и сборок macOS без фреймворка, `~/Library/Python/X.Y` для сборок macOS с фреймворком и `%APPDATA%\Python` для Windows. Это значение используется для вычисления каталогов установки скриптов, файлов данных, модулей Python и т.д. для [схемы установки для пользователя](https://python-all.ru/3.14/library/sysconfig.html#sysconfig-user-scheme). См. также [`PYTHONUSERBASE`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONUSERBASE).9798#### `site.main()`99100Добавляет все стандартные каталоги, специфичные для сайта, в путь поиска модулей. Эта функция вызывается автоматически при импорте этого модуля, если только интерпретатор Python не был запущен с флагом [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S).101102Изменено в версии 3.3: Эта функция ранее вызывалась безоговорочно.103104#### `site.addsitedir(sitedir, known_paths=None)`105106Добавляет каталог в sys.path и обрабатывает его `.pth` файлы. Обычно используется в [`sitecustomize`](https://python-all.ru/3.14/library/site.html#module-sitecustomize) или [`usercustomize`](https://python-all.ru/3.14/library/site.html#module-usercustomize) (см. выше).107108#### `site.getsitepackages()`109110Возвращает список всех глобальных каталогов site-packages.111112Добавлено в версии 3.2.113114#### `site.getuserbase()`115116Возвращает путь к базовому каталогу пользователя, [`USER_BASE`](https://python-all.ru/3.14/library/site.html#site.USER_BASE). Если он ещё не инициализирован, эта функция также устанавливает его с учётом [`PYTHONUSERBASE`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONUSERBASE).117118Добавлено в версии 3.2.119120#### `site.getusersitepackages()`121122Возвращает путь к каталогу site-packages пользователя, [`USER_SITE`](https://python-all.ru/3.14/library/site.html#site.USER_SITE). Если он ещё не инициализирован, эта функция также устанавливает его с учётом [`USER_BASE`](https://python-all.ru/3.14/library/site.html#site.USER_BASE). Чтобы определить, был ли каталог site-packages пользователя добавлен в `sys.path`, следует использовать [`ENABLE_USER_SITE`](https://python-all.ru/3.14/library/site.html#site.ENABLE_USER_SITE).123124Добавлено в версии 3.2.125126## Интерфейс командной строки127128Модуль `site` также предоставляет способ получить каталоги пользователя из командной строки:129130```console131$ python -m site --user-site132/home/user/.local/lib/python3.11/site-packages133```134135Если он вызывается без аргументов, он выводит содержимое [`sys.path`](https://python-all.ru/3.14/library/sys.html#sys.path) в стандартный вывод, затем значение [`USER_BASE`](https://python-all.ru/3.14/library/site.html#site.USER_BASE) и признак существования каталога, затем то же самое для [`USER_SITE`](https://python-all.ru/3.14/library/site.html#site.USER_SITE), и наконец значение [`ENABLE_USER_SITE`](https://python-all.ru/3.14/library/site.html#site.ENABLE_USER_SITE).136137#### `--user-base`138139Выводит путь к базовому каталогу пользователя.140141#### `--user-site`142143Выводит путь к каталогу site-packages пользователя.144145Если указаны обе опции, будут выведены базовый каталог пользователя и пользовательский каталог site-packages (всегда в этом порядке), разделённые [`os.pathsep`](https://python-all.ru/3.14/library/os.html#os.pathsep).146147Если указана любая опция, скрипт завершится с одним из следующих значений: `0`, если каталог site-packages пользователя включён; `1`, если он отключён пользователем; `2`, если он отключён по соображениям безопасности или администратором; и значение больше 2, если произошла ошибка.148149> **См. также**150>151> - [**PEP 370**](https://python-all.ru/3.14/library/site.html) – Каталог site-packages для каждого пользователя152> - [Инициализация пути поиска модулей sys.path](https://python-all.ru/3.14/library/sys_path_init.html#sys-path-init) – Инициализация [`sys.path`](https://python-all.ru/3.14/library/sys.html#sys.path).153