29.13. site – Перехватчик конфигурации для конкретного сайта¶site – Site-specific configuration hook

Исходный код: Lib/site.py

Этот модуль автоматически импортируется при инициализации. Автоматический импорт можно подавить с помощью флага интерпретатора -S.

Если не использовался флаг -S, импорт этого модуля добавляет специфичные для сайта пути в список поиска модулей и несколько встроенных объектов. В противном случае модуль можно безопасно импортировать без автоматических изменений пути поиска модулей или дополнений встроенных объектов. Чтобы явно запустить обычные добавления для сайта, вызовите функцию site.main().

Сначала создаются до четырёх каталогов из головной и хвостовой частей. В качестве головной части используются sys.prefix и sys.exec_prefix; пустые головные части пропускаются. В качестве хвостовой части используется пустая строка, затем lib/site-packages (в Windows) или lib/pythonX.Y/site-packages, а затем lib/site-python (в Unix и Macintosh). Для каждой уникальной комбинации головной и хвостовой частей проверяется, указывает ли она на существующий каталог; если да, он добавляется в sys.path, и также проверяется добавленный путь на наличие файлов конфигурации.

Если на один каталог выше 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; в противном случае – нет.

Файл конфигурации пути – это файл, имя которого имеет форму name.pth и находится в одном из четырёх указанных выше каталогов; его содержимое – дополнительные элементы (по одному на строку), которые добавляются в sys.path. Несуществующие элементы никогда не добавляются в sys.path, и не проверяется, ссылается ли элемент на каталог, а не на файл. Ни один элемент не добавляется в sys.path более одного раза. Пустые строки и строки, начинающиеся с символа #, пропускаются. Строки, начинающиеся с import (с последующим пробелом или табуляцией), выполняются.

Например, предположим, что 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 содержит следующее:

# foo package configuration

foo
bar
bletch

а bar.pth содержит:

# bar package configuration

bar

Тогда в sys.path добавляются следующие специфические для версии каталоги (в указанном порядке):

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

Обратите внимание, что bletch пропущен, потому что не существует; каталог bar предшествует каталогу foo, так как bar.pth идёт раньше foo.pth в алфавитном порядке; а spam пропущен, потому что не упоминается ни в одном из файлов конфигурации пути.

После этих манипуляций с путём предпринимается попытка импортировать модуль с именем sitecustomize, который может выполнять произвольные настройки для конкретного сайта. Обычно он создаётся системным администратором в каталоге site-packages. Если этот импорт завершается с исключением ImportError, оно молча игнорируется. Если Python запущен без доступных выходных потоков, как в случае с pythonw.exe в Windows (который используется по умолчанию для запуска IDLE), попытка вывода из sitecustomize игнорируется. Любое исключение, отличное от ImportError, приводит к молчаливому и, возможно, загадочному сбою процесса.

После этого предпринимается попытка импортировать модуль с именем usercustomize, который может выполнять произвольные пользовательские настройки, если ENABLE_USER_SITE истинно. Этот файл предназначен для создания в каталоге пользовательских site-packages (см. ниже), который является частью sys.path, если не отключён флагом -s. Исключение ImportError будет молча проигнорировано.

Обратите внимание, что для некоторых систем, не основанных на Unix, sys.prefix и sys.exec_prefix пусты, и манипуляции с путём пропускаются; однако попытка импорта sitecustomize и usercustomize всё равно предпринимается.

$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages