`sys_path_init.md`

69 строк · 13.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/library/sys_path_init.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Инициализация [`sys.path`](https://python-all.ru/3.14/library/sys.html#sys.path) пути поиска модулей89Путь поиска модулей инициализируется при запуске Python. Этот путь поиска модулей доступен через [`sys.path`](https://python-all.ru/3.14/library/sys.html#sys.path).1011Первая запись в пути поиска модулей – это каталог, содержащий входной скрипт, если таковой имеется. В противном случае первой записью является текущий каталог, что бывает при использовании интерактивной оболочки, выполнении команды [`-c`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-c) или модуля [`-m`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-m).1213Переменная окружения [`PYTHONPATH`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONPATH) часто используется для добавления каталогов в путь поиска. Если эта переменная окружения установлена, её содержимое добавляется в путь поиска модулей.1415> **Примечание**16>17> [`PYTHONPATH`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONPATH) повлияет на все установленные версии и окружения Python. Следует проявлять осторожность при установке этого в профиле оболочки или глобальных переменных окружения. Модуль [`site`](https://python-all.ru/3.14/library/site.html#module-site) предлагает более тонкие методы, как описано ниже.1819Следующими добавляются каталоги, содержащие стандартные модули Python, а также любые [модули расширения](https://python-all.ru/3.14/glossary.html#term-extension-module), от которых зависят эти модули. Модули расширения – это файлы `.pyd` в Windows и файлы `.so` на других платформах. Каталог с платформенно-независимыми модулями Python называется `prefix`. Каталог с модулями расширения называется `exec_prefix`.2021Переменная окружения [`PYTHONHOME`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONHOME) может использоваться для задания расположения `prefix` и `exec_prefix`. В противном случае эти каталоги находятся с использованием исполняемого файла Python в качестве отправной точки и последующего поиска различных «опознавательных» файлов и каталогов. Обратите внимание, что символические ссылки разрешаются, поэтому в качестве начальной точки поиска используется реальное расположение исполняемого файла Python. Расположение исполняемого файла Python называется `home`.2223После определения `home` каталог `prefix` находится путём первоначального поиска `pythonmajorversionminorversion.zip` (`python311.zip`). В Windows zip-архив ищется в `home`, а в Unix архив ожидается в `lib`. Обратите внимание, что ожидаемое расположение zip-архива добавляется в путь поиска модулей, даже если архив не существует. Если архив не найден, Python в Windows продолжит поиск `prefix`, разыскивая `Lib\os.py`. Python в Unix будет искать `lib/pythonmajorversion.minorversion/os.py` (`lib/python3.11/os.py`). В Windows `prefix` и `exec_prefix` совпадают, однако на других платформах `lib/pythonmajorversion.minorversion/lib-dynload` (`lib/python3.11/lib-dynload`) ищется и используется как привязка для `exec_prefix`. На некоторых платформах `lib` может быть `lib64` или другим значением, см. [`sys.platlibdir`](https://python-all.ru/3.14/library/sys.html#sys.platlibdir) и [`PYTHONPLATLIBDIR`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONPLATLIBDIR).2425После обнаружения `prefix` и `exec_prefix` доступны через [`sys.base_prefix`](https://python-all.ru/3.14/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.14/library/sys.html#sys.base_exec_prefix) соответственно.2627Если [`PYTHONHOME`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONHOME) не установлена, и файл `pyvenv.cfg` найден рядом с основным исполняемым файлом или в его родительском каталоге, то [`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) устанавливаются в каталог, содержащий `pyvenv.cfg`; в противном случае они устанавливаются в то же значение, что и [`sys.base_prefix`](https://python-all.ru/3.14/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.14/library/sys.html#sys.base_exec_prefix) соответственно. Это используется [виртуальными окружениями](https://python-all.ru/3.14/library/sys_path_init.html#sys-path-init-virtual-environments).2829Наконец, обрабатывается модуль [`site`](https://python-all.ru/3.14/library/site.html#module-site), и каталоги `site-packages` добавляются в путь поиска модулей. Распространённый способ настройки пути поиска – создание модулей [`sitecustomize`](https://python-all.ru/3.14/library/site.html#module-sitecustomize) или [`usercustomize`](https://python-all.ru/3.14/library/site.html#module-usercustomize), как описано в документации модуля `site`.3031> **Примечание**32>33> Некоторые параметры командной строки могут дополнительно влиять на вычисление путей. Подробнее см. [`-E`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-E), [`-I`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-I), [`-s`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-s) и [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S).3435Изменено в версии 3.14: [`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) теперь устанавливаются в каталог `pyvenv.cfg` во время инициализации пути. Ранее это выполнялось [`site`](https://python-all.ru/3.14/library/site.html#module-site), поэтому на него влияли [`-S`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-S).3637## Виртуальные окружения3839Виртуальные окружения помещают файл `pyvenv.cfg` в свой префикс, что заставляет [`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) указывать на них, а не на базовую установку.4041Значения `prefix` и `exec_prefix` базовой установки доступны через [`sys.base_prefix`](https://python-all.ru/3.14/library/sys.html#sys.base_prefix) и [`sys.base_exec_prefix`](https://python-all.ru/3.14/library/sys.html#sys.base_exec_prefix).4243Помимо использования в качестве маркера для идентификации виртуальных окружений, `pyvenv.cfg` также может использоваться для настройки инициализации [`site`](https://python-all.ru/3.14/library/site.html#module-site). Обратитесь к [документации по виртуальным окружениям](https://python-all.ru/3.14/library/site.html#site-virtual-environments-configuration) `site`.4445> **Примечание**46>47> [`PYTHONHOME`](https://python-all.ru/3.14/using/cmdline.html#envvar-PYTHONHOME) переопределяет обнаружение `pyvenv.cfg`.4849> **Примечание**50>51> Существуют и другие способы реализации «виртуальных окружений»; данная документация относится к реализациям, основанным на механизме `pyvenv.cfg`, таким как [`venv`](https://python-all.ru/3.14/library/venv.html#module-venv). Большинство реализаций виртуальных окружений следуют модели, заданной `venv`, но могут существовать и экзотические реализации, отклоняющиеся от неё.5253## Файлы \_pth5455Чтобы полностью переопределить [`sys.path`](https://python-all.ru/3.14/library/sys.html#sys.path), создайте файл `._pth` с тем же именем, что и у общей библиотеки или исполняемого файла (`python._pth` или `python311._pth`). Путь к общей библиотеке всегда известен в Windows, однако на других платформах он может быть недоступен. В файле `._pth` укажите по одной строке для каждого пути, добавляемого в `sys.path`. Файл, основанный на имени общей библиотеки, переопределяет файл, основанный на исполняемом файле, что позволяет при желании ограничить пути для любой программы, загружающей среду выполнения.5657Если файл существует, все реестровые и переменные окружения игнорируются, включается изолированный режим, и [`site`](https://python-all.ru/3.14/library/site.html#module-site) не импортируется, если только одна из строк файла не указывает `import site`. Пустые пути и строки, начинающиеся с `#`, игнорируются. Каждый путь может быть абсолютным или относительным относительно расположения файла. Операторы импорта, кроме `site`, не допускаются, и произвольный код не может быть задан.5859Обратите внимание, что файлы `.pth` (без ведущего подчёркивания) будут обрабатываться модулем [`site`](https://python-all.ru/3.14/library/site.html#module-site) в обычном порядке, если указан `import site`.6061## Встраиваемый Python6263Если Python встраивается в другое приложение, [`Py_InitializeFromConfig()`](https://python-all.ru/3.14/c-api/interp-lifecycle.html#c.Py_InitializeFromConfig) и структура [`PyConfig`](https://python-all.ru/3.14/c-api/init_config.html#c.PyConfig) могут использоваться для инициализации Python. Подробности, касающиеся пути, описаны в [конфигурации пути поиска Python](https://python-all.ru/3.14/c-api/init_config.html#init-path-config).6465> **См. также**66>67> - [Поиск модулей](https://python-all.ru/3.14/using/windows.html#windows-finding-modules) для подробных замечаний по Windows.68> - [Использование Python на платформах Unix](https://python-all.ru/3.14/using/unix.html#using-on-unix) для подробностей по Unix.69