Документация Python неофициальный перевод
Содержание страницы

Инициализация sys.path пути поиска модулейThe initialization of the sys.path module search path

Путь поиска модулей инициализируется при запуске Python. Этот путь поиска модулей доступен через sys.path.

Первая запись в пути поиска модулей – это каталог, содержащий входной скрипт, если таковой имеется. В противном случае первой записью является текущий каталог, что бывает при использовании интерактивной оболочки, выполнении команды -c или модуля -m.

Переменная окружения PYTHONPATH часто используется для добавления каталогов в путь поиска. Если эта переменная окружения установлена, её содержимое добавляется в путь поиска модулей.

Примечание

PYTHONPATH повлияет на все установленные версии и окружения Python. Следует проявлять осторожность при установке этого в профиле оболочки или глобальных переменных окружения. Модуль site предлагает более тонкие методы, как описано ниже.

Следующими добавляются каталоги, содержащие стандартные модули Python, а также любые модули расширения, от которых зависят эти модули. Модули расширения – это файлы .pyd в Windows и файлы .so на других платформах. Каталог с платформенно-независимыми модулями Python называется prefix. Каталог с модулями расширения называется exec_prefix.

Переменная окружения PYTHONHOME может использоваться для задания расположения prefix и exec_prefix. В противном случае эти каталоги находятся с использованием исполняемого файла Python в качестве отправной точки и последующего поиска различных «опознавательных» файлов и каталогов. Обратите внимание, что символические ссылки разрешаются, поэтому в качестве начальной точки поиска используется реальное расположение исполняемого файла Python. Расположение исполняемого файла Python называется home.

После определения 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 и PYTHONPLATLIBDIR.

После обнаружения prefix и exec_prefix доступны по адресу sys.prefix и sys.exec_prefix соответственно.

Наконец, обрабатывается модуль site, и каталоги site-packages добавляются в путь поиска модулей. Распространённый способ настройки пути поиска – создание модулей sitecustomize или usercustomize, как описано в документации модуля site.

Примечание

Некоторые параметры командной строки могут дополнительно влиять на вычисление путей. Подробнее см. -E, -I, -s и -S.

Виртуальные окруженияVirtual environments

Если Python запускается в виртуальном окружении (как описано в Виртуальные окружения и пакеты), то prefix и exec_prefix относятся только к этому виртуальному окружению.

Если файл pyvenv.cfg найден рядом с основным исполняемым файлом или в каталоге на один уровень выше исполняемого файла, применяются следующие варианты:

  • Если home является абсолютным путём, а PYTHONHOME не задан, этот путь используется вместо пути к основному исполняемому файлу при определении prefix и exec_prefix.

Файлы _pth_pth files

Чтобы полностью переопределить sys.path, создайте файл ._pth с тем же именем, что и у общей библиотеки или исполняемого файла (python._pth или python311._pth). Путь к общей библиотеке всегда известен в Windows, однако на других платформах он может быть недоступен. В файле ._pth укажите по одной строке для каждого пути, добавляемого в sys.path. Файл, основанный на имени общей библиотеки, переопределяет файл, основанный на исполняемом файле, что позволяет при желании ограничить пути для любой программы, загружающей среду выполнения.

Если файл существует, все реестровые и переменные окружения игнорируются, включается изолированный режим, и site не импортируется, если только одна из строк файла не указывает import site. Пустые пути и строки, начинающиеся с #, игнорируются. Каждый путь может быть абсолютным или относительным относительно расположения файла. Операторы импорта, кроме site, не допускаются, и произвольный код не может быть задан.

Обратите внимание, что файлы .pth (без ведущего подчёркивания) будут обрабатываться модулем site в обычном порядке, если указан import site.

Встраиваемый PythonEmbedded Python

Если Python встроен в другое приложение Py_InitializeFromConfig() и может использоваться структура PyConfig для инициализации Python. Подробности о пути описаны в Конфигурация пути Python. В качестве альтернативы можно использовать более старый Py_SetPath() для обхода инициализации пути поиска модулей.

См. также