Инициализация пути поиска модуля sys.path

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

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

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

Примечание

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

Следующими добавленными элементами являются каталоги, содержащие стандартные модули Python, а также любые extension module, от которых зависят эти модули. Модулями расширения являются .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.

Виртуальные среды

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

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

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

_pth файлы

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

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

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

Встроенный Python

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

См.также

importlib.metadata – Доступ к метаданным пакета
Языковые сервисы Python
Вернуться на верх