`site.md`

142 строк · 17.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/site.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`site`](https://python-all.ru/3.9/library/site.html#module-site) – перехватчик конфигурации для конкретного сайта89**Исходный код:** [Lib/site.py](https://python-all.ru/src/3.9/Lib/site.py)1011---1213**Этот модуль автоматически импортируется при инициализации.** Автоматический импорт можно отключить с помощью опции интерпретатора [`-S`](https://python-all.ru/3.9/using/cmdline.html#id3).1415Импорт этого модуля добавляет специфичные для сайта пути в путь поиска модулей и добавляет несколько встроенных функций, если не использовалась опция [`-S`](https://python-all.ru/3.9/using/cmdline.html#id3). В этом случае модуль можно безопасно импортировать без автоматических изменений в пути поиска модулей или добавления встроенных функций. Чтобы явно запустить обычное добавление специфичных для сайта путей, вызовите функцию [`site.main()`](https://python-all.ru/3.9/library/site.html#site.main).1617Изменено в версии 3.3: Раньше импорт модуля запускал изменение путей даже при использовании [`-S`](https://python-all.ru/3.9/using/cmdline.html#id3).1819Он начинает с построения до четырех каталогов из головной и хвостовой частей. Для головной части используются `sys.prefix` и `sys.exec_prefix`; пустые головы пропускаются. Для хвостовой части используется пустая строка, а затем `lib/site-packages` (в Windows) или `lib/pythonX.Y/site-packages` (в Unix и macOS). Для каждой из различных комбинаций голова-хвост проверяется, указывает ли она на существующий каталог, и если да, то добавляется в `sys.path`, а также проверяется вновь добавленный путь на наличие файлов конфигурации.2021Изменено в версии 3.5: Поддержка каталога «site-python» удалена.2223Если файл с именем «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; в противном случае будут.2425Файл конфигурации пути – это файл, имя которого имеет вид `name.pth` и находится в одном из четырёх упомянутых выше каталогов; его содержимое – это дополнительные элементы (по одному на строку), которые добавляются в `sys.path`. Несуществующие элементы никогда не добавляются в `sys.path`, и не проверяется, является ли элемент каталогом, а не файлом. Ни один элемент не добавляется в `sys.path` более одного раза. Пустые строки и строки, начинающиеся с `#`, пропускаются. Строки, начинающиеся с `import` (с последующим пробелом или табуляцией), выполняются.2627> **Примечание**28>29> Исполняемая строка в файле `.pth` выполняется при каждом запуске Python, независимо от того, будет ли фактически использоваться какой-либо конкретный модуль. Поэтому её влияние должно быть минимальным. Основная цель исполняемых строк – сделать соответствующие модули импортируемыми (загрузить сторонние хуки импорта, настроить `PATH` и т.д.). Любая другая инициализация должна выполняться при фактическом импорте модуля, если и когда он происходит. Ограничение фрагмента кода одной строкой – это намеренная мера, чтобы предотвратить размещение здесь чего-то более сложного.3031Например, предположим, что `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` содержит следующее:3233```text34# foo package configuration3536foo37bar38bletch39```4041а `bar.pth` содержит:4243```text44# bar package configuration4546bar47```4849Затем следующие каталоги, зависящие от версии, добавляются в `sys.path` в следующем порядке:5051```text52/usr/local/lib/pythonX.Y/site-packages/bar53/usr/local/lib/pythonX.Y/site-packages/foo54```5556Обратите внимание, что `bletch` пропущен, потому что не существует; каталог `bar` предшествует каталогу `foo`, поскольку `bar.pth` находится по алфавиту перед `foo.pth`; а `spam` пропущен, так как не упоминается ни в одном файле конфигурации путей.5758После этих манипуляций с путём предпринимается попытка импортировать модуль с именем `sitecustomize`. Этот модуль может выполнять произвольные настройки, специфичные для сайта. Обычно он создаётся системным администратором в каталоге site-packages. Если этот импорт завершается ошибкой с исключением [`ImportError`](https://python-all.ru/3.9/library/exceptions.html#ImportError) или его подклассом, и атрибут `name` этого исключения равен `'sitecustomize'`, то ошибка игнорируется. Если Python запущен без доступных потоков вывода, как при использовании `pythonw.exe` в Windows (этот флаг по умолчанию используется для запуска IDLE), то попытка вывода из `sitecustomize` игнорируется. Любое другое исключение вызывает молчаливый и, возможно, загадочный сбой процесса.5960После этого предпринимается попытка импортировать модуль `usercustomize`, который может выполнять произвольные настройки для конкретного пользователя, если [`ENABLE_USER_SITE`](https://python-all.ru/3.9/library/site.html#site.ENABLE_USER_SITE) равно истине. Этот файл должен быть создан в каталоге user site-packages (см. ниже), который является частью `sys.path`, если не отключён параметром [`-s`](https://python-all.ru/3.9/using/cmdline.html#cmdoption-s). Если этот импорт завершается ошибкой с исключением [`ImportError`](https://python-all.ru/3.9/library/exceptions.html#ImportError) или его подклассом, и атрибут `name` этого исключения равен `'usercustomize'`, то ошибка игнорируется.6162Обратите внимание, что для некоторых систем, не являющихся Unix, `sys.prefix` и `sys.exec_prefix` пусты, и манипуляции с путями пропускаются; однако импорт `sitecustomize` и `usercustomize` всё равно предпринимается.6364## Конфигурация Readline6566В системах, поддерживающих [`readline`](https://python-all.ru/3.9/library/readline.html#module-readline), этот модуль также импортирует и настраивает модуль [`rlcompleter`](https://python-all.ru/3.9/library/rlcompleter.html#module-rlcompleter), если Python запущен в [интерактивном режиме](https://python-all.ru/3.9/tutorial/interpreter.html#tut-interactive) и без опции [`-S`](https://python-all.ru/3.9/using/cmdline.html#id3). Поведение по умолчанию – включить автодополнение по табуляции и использовать `~/.python_history` в качестве файла сохранения истории. Чтобы отключить его, удалите (или переопределите) атрибут [`sys.__interactivehook__`](https://python-all.ru/3.9/library/sys.html#sys.__interactivehook__) в модуле `sitecustomize` или `usercustomize` или в файле [`PYTHONSTARTUP`](https://python-all.ru/3.9/using/cmdline.html#envvar-PYTHONSTARTUP).6768Изменено в версии 3.4: Активация rlcompleter и истории стала автоматической.6970## Содержимое модуля7172#### `site.PREFIXES`7374Список префиксов для каталогов site-packages.7576#### `site.ENABLE_USER_SITE`7778Флаг, показывающий статус каталога пользовательских site-packages. `True` означает, что он включён и был добавлен в `sys.path`. `False` означает, что он был отключён по запросу пользователя (с помощью [`-s`](https://python-all.ru/3.9/using/cmdline.html#cmdoption-s) или [`PYTHONNOUSERSITE`](https://python-all.ru/3.9/using/cmdline.html#envvar-PYTHONNOUSERSITE)). `None` означает, что он был отключён по соображениям безопасности (несовпадение идентификатора пользователя или группы с эффективным идентификатором) или администратором.7980#### `site.USER_SITE`8182Путь к пользовательским site-packages для запущенного Python. Может быть `None`, если [`getusersitepackages()`](https://python-all.ru/3.9/library/site.html#site.getusersitepackages) ещё не вызывалась. Значение по умолчанию – `~/.local/lib/pythonX.Y/site-packages` для UNIX и сборок macOS без фреймворка, `~/Library/Python/X.Y/lib/python/site-packages` для сборок macOS с фреймворком, и `%APPDATA%\Python\PythonXY\site-packages` в Windows. Этот каталог является site-каталогом, что означает, что файлы `.pth` в нём будут обработаны.8384#### `site.USER_BASE`8586Путь к базовому каталогу для пользовательских site-packages. Может быть `None`, если [`getuserbase()`](https://python-all.ru/3.9/library/site.html#site.getuserbase) ещё не была вызвана. Значение по умолчанию: `~/.local` для сборок UNIX и macOS без фреймворка, `~/Library/Python/X.Y` для сборок macOS с фреймворком и `%APPDATA%\Python` для Windows. Это значение используется Distutils для вычисления каталогов установки скриптов, файлов данных, модулей Python и т.д. для [схемы установки для пользователя](https://python-all.ru/3.9/install/index.html#inst-alt-install-user). См. также [`PYTHONUSERBASE`](https://python-all.ru/3.9/using/cmdline.html#envvar-PYTHONUSERBASE).8788#### `site.main()`8990Добавляет все стандартные каталоги, специфичные для сайта, в путь поиска модулей. Эта функция вызывается автоматически при импорте этого модуля, если только интерпретатор Python не был запущен с флагом [`-S`](https://python-all.ru/3.9/using/cmdline.html#id3).9192Изменено в версии 3.3: Эта функция ранее вызывалась безоговорочно.9394#### `site.addsitedir(sitedir, known_paths=None)`9596Добавляет каталог в sys.path и обрабатывает его `.pth` файлы. Обычно используется в `sitecustomize` или `usercustomize` (см. выше).9798#### `site.getsitepackages()`99100Возвращает список всех глобальных каталогов site-packages.101102Новое в версии 3.2.103104#### `site.getuserbase()`105106Возвращает путь к базовому каталогу пользователя, [`USER_BASE`](https://python-all.ru/3.9/library/site.html#site.USER_BASE). Если он ещё не инициализирован, эта функция также устанавливает его с учётом [`PYTHONUSERBASE`](https://python-all.ru/3.9/using/cmdline.html#envvar-PYTHONUSERBASE).107108Новое в версии 3.2.109110#### `site.getusersitepackages()`111112Возвращает путь к каталогу site-packages пользователя, [`USER_SITE`](https://python-all.ru/3.9/library/site.html#site.USER_SITE). Если он ещё не инициализирован, эта функция также устанавливает его с учётом [`USER_BASE`](https://python-all.ru/3.9/library/site.html#site.USER_BASE). Чтобы определить, был ли каталог site-packages пользователя добавлен в `sys.path`, следует использовать [`ENABLE_USER_SITE`](https://python-all.ru/3.9/library/site.html#site.ENABLE_USER_SITE).113114Новое в версии 3.2.115116## Интерфейс командной строки117118Модуль [`site`](https://python-all.ru/3.9/library/site.html#module-site) также предоставляет способ получить каталоги пользователя из командной строки:119120```console121$ python3 -m site --user-site122/home/user/.local/lib/python3.3/site-packages123```124125Если он вызывается без аргументов, он выводит содержимое [`sys.path`](https://python-all.ru/3.9/library/sys.html#sys.path) в стандартный вывод, затем значение [`USER_BASE`](https://python-all.ru/3.9/library/site.html#site.USER_BASE) и признак существования каталога, затем то же самое для [`USER_SITE`](https://python-all.ru/3.9/library/site.html#site.USER_SITE), и наконец значение [`ENABLE_USER_SITE`](https://python-all.ru/3.9/library/site.html#site.ENABLE_USER_SITE).126127#### `--user-base`128129Выводит путь к базовому каталогу пользователя.130131#### `--user-site`132133Выводит путь к каталогу site-packages пользователя.134135Если указаны обе опции, будут выведены базовый каталог пользователя и пользовательский каталог site-packages (всегда в этом порядке), разделённые [`os.pathsep`](https://python-all.ru/3.9/library/os.html#os.pathsep).136137Если указана любая опция, скрипт завершится с одним из следующих значений: `0`, если каталог site-packages пользователя включён; `1`, если он отключён пользователем; `2`, если он отключён по соображениям безопасности или администратором; и значение больше 2, если произошла ошибка.138139> **См. также**140>141> [**PEP 370**](https://python-all.ru/3.9/library/site.html) – Каталог site-packages для каждого пользователя142