`site.md`

126 строк · 14.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/library/site.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 28.13. [`site`](https://python-all.ru/3.3/library/site.html#module-site) – Конфигурационный хук, специфичный для сайта89**Исходный код:** [Lib/site.py](https://python-all.ru/src/3.3/Lib/site.py)1011---1213**Этот модуль автоматически импортируется при инициализации.** Автоматический импорт можно подавить с помощью флага интерпретатора [*-S*](https://python-all.ru/3.3/using/cmdline.html#cmdoption-S).1415Если не использовался флаг [*-S*](https://python-all.ru/3.3/using/cmdline.html#cmdoption-S), импорт этого модуля добавляет специфичные для сайта пути в список поиска модулей и несколько встроенных объектов. В противном случае модуль можно безопасно импортировать без автоматических изменений пути поиска модулей или дополнений встроенных объектов. Чтобы явно запустить обычные добавления для сайта, вызовите функцию [`site.main()`](https://python-all.ru/3.3/library/site.html#site.main).1617Изменено в версии 3.3: Раньше импорт модуля вызывал манипуляции с путями даже при использовании [*-S*](https://python-all.ru/3.3/using/cmdline.html#cmdoption-S).1819Сначала создаются до четырёх каталогов из головной и хвостовой частей. В качестве головной части используются `sys.prefix` и `sys.exec_prefix`; пустые головные части пропускаются. В качестве хвостовой части используется пустая строка, затем `lib/site-packages` (в Windows) или `lib/pythonX.Y/site-packages`, а затем `lib/site-python` (в Unix и Macintosh). Для каждой уникальной комбинации головной и хвостовой частей проверяется, указывает ли она на существующий каталог; если да, он добавляется в `sys.path`, и также проверяется добавленный путь на наличие файлов конфигурации.2021Если на один каталог выше sys.executable существует файл с именем «pyvenv.cfg», то sys.prefix и sys.exec\_prefix устанавливаются в этот каталог, и он также проверяется на наличие site-packages и site-python (sys.base\_prefix и sys.base\_exec\_prefix всегда будут «настоящими» префиксами установки Python). Если в файле «pyvenv.cfg» (файл начальной загрузки конфигурации) ключ «include-system-site-packages» имеет значение, отличное от «false» (без учёта регистра), системные префиксы всё равно будут проверяться на наличие site-packages; в противном случае – нет.2223Файл конфигурации пути – это файл, имя которого имеет форму `name.pth` и находится в одном из четырёх указанных выше каталогов; его содержимое – дополнительные элементы (по одному на строку), которые добавляются в `sys.path`. Несуществующие элементы никогда не добавляются в `sys.path`, и не проверяется, ссылается ли элемент на каталог, а не на файл. Ни один элемент не добавляется в `sys.path` более одного раза. Пустые строки и строки, начинающиеся с символа `#`, пропускаются. Строки, начинающиеся с `import` (с последующим пробелом или табуляцией), выполняются.2425Например, предположим, что `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` содержит следующее:2627```text28# foo package configuration2930foo31bar32bletch33```3435а `bar.pth` содержит:3637```text38# bar package configuration3940bar41```4243Тогда в `sys.path` добавляются следующие специфические для версии каталоги (в указанном порядке):4445```text46/usr/local/lib/pythonX.Y/site-packages/bar47/usr/local/lib/pythonX.Y/site-packages/foo48```4950Обратите внимание, что `bletch` пропущен, потому что не существует; каталог `bar` предшествует каталогу `foo`, так как `bar.pth` идёт раньше `foo.pth` в алфавитном порядке; а `spam` пропущен, потому что не упоминается ни в одном из файлов конфигурации пути.5152После этих манипуляций с путями предпринимается попытка импортировать модуль с именем `sitecustomize`, который может выполнять произвольные настройки, специфичные для сайта. Обычно он создаётся системным администратором в каталоге site-packages. Если этот импорт завершается неудачей с исключением [`ImportError`](https://python-all.ru/3.3/library/exceptions.html#ImportError), это бесшумно игнорируется.5354После этого предпринимается попытка импортировать модуль с именем `usercustomize`, который может выполнять произвольные пользовательские настройки, если [`ENABLE_USER_SITE`](https://python-all.ru/3.3/library/site.html#site.ENABLE_USER_SITE) истинно. Этот файл предназначен для создания в каталоге пользовательских site-packages (см. ниже), который является частью `sys.path`, если не отключён флагом [*-s*](https://python-all.ru/3.3/using/cmdline.html#cmdoption-s). Исключение [`ImportError`](https://python-all.ru/3.3/library/exceptions.html#ImportError) будет молча проигнорировано.5556Обратите внимание, что для некоторых систем, не основанных на Unix, `sys.prefix` и `sys.exec_prefix` пусты, и манипуляции с путём пропускаются; однако попытка импорта `sitecustomize` и `usercustomize` всё равно предпринимается.5758#### `site.PREFIXES`5960Список префиксов для каталогов site-packages.6162#### `site.ENABLE_USER_SITE`6364Флаг, показывающий статус пользовательского каталога site-packages. Значение `True` означает, что он включён и добавлен в `sys.path`. `False` означает, что он был отключён по запросу пользователя (с помощью [*-s*](https://python-all.ru/3.3/using/cmdline.html#cmdoption-s) или [`PYTHONNOUSERSITE`](https://python-all.ru/3.3/using/cmdline.html#envvar-PYTHONNOUSERSITE)). `None` означает, что он был отключён по соображениям безопасности (несовпадение идентификатора пользователя или группы с эффективным идентификатором) или администратором.6566#### `site.USER_SITE`6768Путь к пользовательским site-packages для запущенного Python. Может быть равен `None`, если [`getusersitepackages()`](https://python-all.ru/3.3/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` в нём будут обработаны.6970#### `site.USER_BASE`7172Путь к базовому каталогу для пользовательских site-packages. Может быть равен `None`, если [`getuserbase()`](https://python-all.ru/3.3/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.3/install/index.html#inst-alt-install-user). См. также [`PYTHONUSERBASE`](https://python-all.ru/3.3/using/cmdline.html#envvar-PYTHONUSERBASE).7374#### `site.main()`7576Добавляет все стандартные каталоги, специфичные для сайта, в путь поиска модулей. Эта функция вызывается автоматически при импорте этого модуля, если только интерпретатор **python** не был запущен с флагом [*-S*](https://python-all.ru/3.3/using/cmdline.html#cmdoption-S).7778Изменено в версии 3.3: Раньше эта функция вызывалась безусловно.7980#### `site.addsitedir(sitedir, known_paths=None)`8182Добавляет каталог в sys.path и обрабатывает его файлы `.pth`. Обычно используется в файлах `sitecustomize` или `usercustomize` (см. выше).8384#### `site.getsitepackages()`8586Возвращает список, содержащий все глобальные каталоги site-packages (и, возможно, site-python).8788Новое в версии 3.2.8990#### `site.getuserbase()`9192Возвращает путь к базовому каталогу пользователя [`USER_BASE`](https://python-all.ru/3.3/library/site.html#site.USER_BASE). Если он ещё не инициализирован, эта функция также установит его, учитывая [`PYTHONUSERBASE`](https://python-all.ru/3.3/using/cmdline.html#envvar-PYTHONUSERBASE).9394Новое в версии 3.2.9596#### `site.getusersitepackages()`9798Возвращает путь к каталогу site-packages, специфичному для пользователя, [`USER_SITE`](https://python-all.ru/3.3/library/site.html#site.USER_SITE). Если он ещё не инициализирован, эта функция также устанавливает его, учитывая [`PYTHONNOUSERSITE`](https://python-all.ru/3.3/using/cmdline.html#envvar-PYTHONNOUSERSITE) и [`USER_BASE`](https://python-all.ru/3.3/library/site.html#site.USER_BASE).99100Новое в версии 3.2.101102Модуль [`site`](https://python-all.ru/3.3/library/site.html#module-site) также предоставляет способ получить пользовательские каталоги из командной строки:103104```sh105$ python3 -m site --user-site106/home/user/.local/lib/python3.3/site-packages107```108109Если он вызывается без аргументов, он выводит содержимое [`sys.path`](https://python-all.ru/3.3/library/sys.html#sys.path) на стандартный вывод, затем значение [`USER_BASE`](https://python-all.ru/3.3/library/site.html#site.USER_BASE) и существует ли этот каталог, затем то же самое для [`USER_SITE`](https://python-all.ru/3.3/library/site.html#site.USER_SITE), и наконец значение [`ENABLE_USER_SITE`](https://python-all.ru/3.3/library/site.html#site.ENABLE_USER_SITE).110111#### `--user-base`112113Выводит путь к базовому каталогу пользователя.114115#### `--user-site`116117Выводит путь к каталогу site-packages пользователя.118119Если указаны оба параметра, будут выведены базовый каталог пользователя и пользовательский каталог site-packages (всегда в этом порядке), разделённые [`os.pathsep`](https://python-all.ru/3.3/library/os.html#os.pathsep).120121Если указан любой из параметров, сценарий завершится с одним из следующих значений: `O`, если каталог site-packages пользователя включён, `1`, если он был отключён пользователем, `2`, если он отключён по соображениям безопасности или администратором, а значение больше 2 в случае ошибки.122123> **См. также**124>125> [**PEP 370**](https://python-all.ru/3.3/library/site.html) – Каталог site-packages для каждого пользователя126