`site.md`

136 строк · 16.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/library/site.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 29.13. [`site`](https://python-all.ru/3.6/library/site.html#module-site) – Хук конфигурации для конкретного сайта89**Исходный код:** [Lib/site.py](https://python-all.ru/src/3.6/Lib/site.py)1011---1213**Этот модуль автоматически импортируется при инициализации.** Автоматический импорт можно отключить с помощью опции интерпретатора [`-S`](https://python-all.ru/3.6/using/cmdline.html#id3).1415Импорт этого модуля добавляет специфичные для сайта пути в путь поиска модулей и добавляет несколько встроенных функций, если не использовалась опция [`-S`](https://python-all.ru/3.6/using/cmdline.html#id3). В этом случае модуль можно безопасно импортировать без автоматических изменений в пути поиска модулей или добавления встроенных функций. Чтобы явно запустить обычное добавление специфичных для сайта путей, вызовите функцию [`site.main()`](https://python-all.ru/3.6/library/site.html#site.main).1617Изменено в версии 3.3: Раньше импорт модуля запускал изменение путей даже при использовании [`-S`](https://python-all.ru/3.6/using/cmdline.html#id3).1819Процесс начинается с построения до четырёх каталогов из головной и хвостовой частей. В качестве головной части используются `sys.prefix` и `sys.exec_prefix`; пустые головные части пропускаются. В качестве хвостовой части сначала используется пустая строка, а затем `lib/site-packages` (в Windows) или `lib/pythonX.Y/site-packages` (в Unix и Macintosh). Для каждой из различных комбинаций головы и хвоста проверяется, указывает ли она на существующий каталог, и если да, то добавляет его в `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», установленный во что-либо отличное от «false» (без учёта регистра), то системные префиксы всё равно будут проверяться на site-packages; в противном случае – нет.2425Файл конфигурации пути – это файл, имя которого имеет вид `name.pth` и находится в одном из четырёх упомянутых выше каталогов; его содержимое – это дополнительные элементы (по одному на строку), которые добавляются в `sys.path`. Несуществующие элементы никогда не добавляются в `sys.path`, и не проверяется, является ли элемент каталогом, а не файлом. Ни один элемент не добавляется в `sys.path` более одного раза. Пустые строки и строки, начинающиеся с `#`, пропускаются. Строки, начинающиеся с `import` (с последующим пробелом или табуляцией), выполняются.2627Например, предположим, что `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` содержит следующее:2829```text30# foo package configuration3132foo33bar34bletch35```3637а `bar.pth` содержит:3839```text40# bar package configuration4142bar43```4445Затем следующие каталоги, зависящие от версии, добавляются в `sys.path` в следующем порядке:4647```text48/usr/local/lib/pythonX.Y/site-packages/bar49/usr/local/lib/pythonX.Y/site-packages/foo50```5152Обратите внимание, что `bletch` пропущен, потому что не существует; каталог `bar` предшествует каталогу `foo`, поскольку `bar.pth` находится по алфавиту перед `foo.pth`; а `spam` пропущен, так как не упоминается ни в одном файле конфигурации путей.5354После этих манипуляций с путями предпринимается попытка импортировать модуль с именем `sitecustomize`, который может выполнять произвольные настройки для конкретного сайта. Обычно он создается системным администратором в каталоге site-packages. Если этот импорт завершается неудачей с исключением [`ImportError`](https://python-all.ru/3.6/library/exceptions.html#ImportError), оно молча игнорируется. Если Python запущен без доступных выходных потоков, как в случае с `pythonw.exe` в Windows (который используется по умолчанию для запуска IDLE), попытка вывода от `sitecustomize` игнорируется. Любое исключение, отличное от [`ImportError`](https://python-all.ru/3.6/library/exceptions.html#ImportError), вызывает тихий и, возможно, загадочный сбой процесса.5556После этого предпринимается попытка импортировать модуль с именем `usercustomize`, который может выполнять произвольные настройки пользователя, если [`ENABLE_USER_SITE`](https://python-all.ru/3.6/library/site.html#site.ENABLE_USER_SITE) истинно. Этот файл предназначен для создания в каталоге user site-packages (см. ниже), который является частью `sys.path`, если не отключен с помощью [`-s`](https://python-all.ru/3.6/using/cmdline.html#cmdoption-s). Исключение [`ImportError`](https://python-all.ru/3.6/library/exceptions.html#ImportError) будет молча игнорироваться.5758Обратите внимание, что для некоторых систем, не являющихся Unix, `sys.prefix` и `sys.exec_prefix` пусты, и манипуляции с путями пропускаются; однако импорт `sitecustomize` и `usercustomize` всё равно предпринимается.5960## 29.13.1. Конфигурация Readline6162В системах, поддерживающих [`readline`](https://python-all.ru/3.6/library/readline.html#module-readline), этот модуль также импортирует и настраивает модуль [`rlcompleter`](https://python-all.ru/3.6/library/rlcompleter.html#module-rlcompleter), если Python запущен в [интерактивном режиме](https://python-all.ru/3.6/tutorial/interpreter.html#tut-interactive) и без опции [`-S`](https://python-all.ru/3.6/using/cmdline.html#id3). Поведение по умолчанию – включить автодополнение по табуляции и использовать `~/.python_history` в качестве файла сохранения истории. Чтобы отключить его, удалите (или переопределите) атрибут [`sys.__interactivehook__`](https://python-all.ru/3.6/library/sys.html#sys.__interactivehook__) в модуле `sitecustomize` или `usercustomize` или в файле [`PYTHONSTARTUP`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONSTARTUP).6364Изменено в версии 3.4: Активация rlcompleter и истории стала автоматической.6566## 29.13.2. Содержимое модуля6768#### `site.PREFIXES`6970Список префиксов для каталогов site-packages.7172#### `site.ENABLE_USER_SITE`7374Флаг, показывающий статус каталога пользовательских site-packages. `True` означает, что он включён и был добавлен в `sys.path`. `False` означает, что он был отключён по запросу пользователя (с помощью [`-s`](https://python-all.ru/3.6/using/cmdline.html#cmdoption-s) или [`PYTHONNOUSERSITE`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONNOUSERSITE)). `None` означает, что он был отключён по соображениям безопасности (несовпадение идентификатора пользователя или группы с эффективным идентификатором) или администратором.7576#### `site.USER_SITE`7778Путь к пользовательским site-packages для текущего Python. Может быть `None`, если [`getusersitepackages()`](https://python-all.ru/3.6/library/site.html#site.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. Этот каталог является site-каталогом, что означает, что `.pth` файлы в нём будут обработаны.7980#### `site.USER_BASE`8182Путь к базовому каталогу для пользовательских site-packages. Может быть `None`, если [`getuserbase()`](https://python-all.ru/3.6/library/site.html#site.getuserbase) ещё не был вызван. Значение по умолчанию – `~/.local` для сборок UNIX и Mac OS X без фреймворка, `~/Library/Python/X.Y` для сборок Mac с фреймворком и `%APPDATA%\Python` для Windows. Это значение используется Distutils для вычисления каталогов установки скриптов, файлов данных, модулей Python и т.д. для [схемы пользовательской установки](https://python-all.ru/3.6/install/index.html#inst-alt-install-user). См. также [`PYTHONUSERBASE`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONUSERBASE).8384#### `site.main()`8586Добавляет все стандартные каталоги, специфичные для сайта, в путь поиска модулей. Эта функция вызывается автоматически при импорте этого модуля, если только интерпретатор Python не был запущен с флагом [`-S`](https://python-all.ru/3.6/using/cmdline.html#id3).8788Изменено в версии 3.3: Эта функция ранее вызывалась безоговорочно.8990#### `site.addsitedir(sitedir, known_paths=None)`9192Добавляет каталог в sys.path и обрабатывает его `.pth` файлы. Обычно используется в `sitecustomize` или `usercustomize` (см. выше).9394#### `site.getsitepackages()`9596Возвращает список всех глобальных каталогов site-packages.9798Новое в версии 3.2.99100#### `site.getuserbase()`101102Возвращает путь к базовому каталогу пользователя, [`USER_BASE`](https://python-all.ru/3.6/library/site.html#site.USER_BASE). Если он ещё не инициализирован, эта функция также устанавливает его с учётом [`PYTHONUSERBASE`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONUSERBASE).103104Новое в версии 3.2.105106#### `site.getusersitepackages()`107108Возвращает путь к каталогу site-packages для текущего пользователя, [`USER_SITE`](https://python-all.ru/3.6/library/site.html#site.USER_SITE). Если он ещё не инициализирован, эта функция также установит его с учётом [`PYTHONNOUSERSITE`](https://python-all.ru/3.6/using/cmdline.html#envvar-PYTHONNOUSERSITE) и [`USER_BASE`](https://python-all.ru/3.6/library/site.html#site.USER_BASE).109110Новое в версии 3.2.111112Модуль [`site`](https://python-all.ru/3.6/library/site.html#module-site) также предоставляет способ получить каталоги пользователя из командной строки:113114```console115$ python3 -m site --user-site116/home/user/.local/lib/python3.3/site-packages117```118119Если он вызывается без аргументов, он выводит содержимое [`sys.path`](https://python-all.ru/3.6/library/sys.html#sys.path) в стандартный вывод, затем значение [`USER_BASE`](https://python-all.ru/3.6/library/site.html#site.USER_BASE) и признак существования каталога, затем то же самое для [`USER_SITE`](https://python-all.ru/3.6/library/site.html#site.USER_SITE), и наконец значение [`ENABLE_USER_SITE`](https://python-all.ru/3.6/library/site.html#site.ENABLE_USER_SITE).120121#### `--user-base`122123Выводит путь к базовому каталогу пользователя.124125#### `--user-site`126127Выводит путь к каталогу site-packages пользователя.128129Если указаны обе опции, будут выведены базовый каталог пользователя и пользовательский каталог site-packages (всегда в этом порядке), разделённые [`os.pathsep`](https://python-all.ru/3.6/library/os.html#os.pathsep).130131Если указана любая опция, скрипт завершится с одним из следующих значений: `0`, если каталог site-packages пользователя включён; `1`, если он отключён пользователем; `2`, если он отключён по соображениям безопасности или администратором; и значение больше 2, если произошла ошибка.132133> **См. также**134>135> [**PEP 370**](https://python-all.ru/3.6/library/site.html) – Каталог site-packages для каждого пользователя136