site — Site-specific configuration hook

Вихідний код: Lib/site.py

Цей модуль автоматично імпортується під час ініціалізації. Автоматичний імпорт можна придушити за допомогою опції інтерпретатора -S.

Importing this module normally appends site-specific paths to the module search path and adds callables, including help() to the built-in namespace. However, Python startup option -S blocks this and this module can be safely imported with no automatic modifications to the module search path or additions to the builtins. To explicitly trigger the usual site-specific additions, call the main() function.

Змінено в версії 3.3: Імпорт модуля, який використовується для ініціювання маніпуляцій шляхом, навіть якщо використовується -S.

It starts by constructing up to four directories from a head and a tail part. For the head part, it uses sys.prefix and sys.exec_prefix; empty heads are skipped. For the tail part, it uses the empty string and then lib/site-packages (on Windows) or lib/pythonX.Y[t]/site-packages (on Unix and macOS). (The optional suffix «t» indicates the free threading build, and is appended if "t" is present in the sys.abiflags constant.) For each of the distinct head-tail combinations, it sees if it refers to an existing directory, and if so, adds it to sys.path and also inspects the newly added path for configuration files.

Змінено в версії 3.5: Підтримку каталогу «site-python» видалено.

Змінено в версії 3.13: On Unix, Free threading Python installations are identified by the «t» suffix in the version-specific directory name, such as lib/python3.13t/.

Змінено в версії 3.14: site is no longer responsible for updating sys.prefix and sys.exec_prefix on Virtual Environments. This is now done during the path initialization. As a result, under Virtual Environments, sys.prefix and sys.exec_prefix no longer depend on the site initialization, and are therefore unaffected by -S.

When running under a virtual environment, the pyvenv.cfg file in sys.prefix is checked for site-specific configurations. If the include-system-site-packages key exists and is set to true (case-insensitive), the system-level prefixes will be searched for site-packages, otherwise they won’t.

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

Примітка

Виконуваний рядок у файлі .pth запускається під час кожного запуску Python, незалежно від того, чи буде фактично використовуватися певний модуль. Тому його вплив слід звести до мінімуму. Основне призначення рядків виконуваного файлу — зробити відповідний(і) модуль(и) доступним для імпорту (завантажити сторонні перехоплювачі імпорту, налаштувати PATH тощо). Будь-яка інша ініціалізація має виконуватися після фактичного імпорту модуля, якщо і коли це відбувається. Обмеження фрагмента коду одним рядком є навмисним заходом, щоб перешкодити розміщенню тут чогось більш складного.

Змінено в версії 3.13: The .pth files are now decoded by UTF-8 at first and then by the locale encoding if it fails.

Наприклад, припустімо, що 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

After these path manipulations, an attempt is made to import a module named sitecustomize, which can perform arbitrary site-specific customizations. It is typically created by a system administrator in the site-packages directory. If this import fails with an ImportError or its subclass exception, and the exception’s name attribute equals to 'sitecustomize', it is silently ignored. If Python is started without output streams available, as with pythonw.exe on Windows (which is used by default to start IDLE), attempted output from sitecustomize is ignored. Any other exception causes a silent and perhaps mysterious failure of the process.

usercustomize

After this, an attempt is made to import a module named usercustomize, which can perform arbitrary user-specific customizations, if ENABLE_USER_SITE is true. This file is intended to be created in the user site-packages directory (see below), which is part of sys.path unless disabled by -s. If this import fails with an ImportError or its subclass exception, and the exception’s name attribute equals to 'usercustomize', it is silently ignored.

Зауважте, що для деяких не-Unix систем sys.prefix і sys.exec_prefix порожні, а маніпуляції зі шляхом пропускаються; проте спроба імпорту sitecustomize і usercustomize все ще робиться.

Конфігурація Readline

У системах, які підтримують readline, цей модуль також імпортуватиме та налаштовуватиме модуль rlcompleter, якщо Python запущено в інтерактивному режимі і без -S варіант. За замовчуванням увімкнено завершення табуляції та використання ~/.python_history як файлу збереження історії. Щоб вимкнути його, видаліть (або змініть) атрибут sys.__interactivehook__ у вашому модулі sitecustomize або usercustomize або у вашому файлі PYTHONSTARTUP.

Змінено в версії 3.4: Активацію rlcompleter та історії було зроблено автоматично.

Зміст модуля

site.PREFIXES

Список префіксів для каталогів пакетів сайту.

site.ENABLE_USER_SITE

Прапор, який показує статус каталогу пакетів сайтів користувача. True означає, що його ввімкнено та було додано до sys.path. False означає, що його було вимкнено за запитом користувача (з -s або PYTHONNOUSERSITE). None означає, що його було вимкнено з міркувань безпеки (невідповідність між ідентифікатором користувача чи групи та ефективним ідентифікатором) або адміністратором.

site.USER_SITE

Path to the user site-packages for the running Python. Can be None if getusersitepackages() hasn’t been called yet. Default value is ~/.local/lib/pythonX.Y[t]/site-packages for UNIX and non-framework macOS builds, ~/Library/Python/X.Y/lib/python/site-packages for macOS framework builds, and %APPDATA%\Python\PythonXY\site-packages on Windows. The optional «t» indicates the free-threaded build. This directory is a site directory, which means that .pth files in it will be processed.

site.USER_BASE

Path to the base directory for the user site-packages. Can be None if getuserbase() hasn’t been called yet. Default value is ~/.local for UNIX and macOS non-framework builds, ~/Library/Python/X.Y for macOS framework builds, and %APPDATA%\Python for Windows. This value is used to compute the installation directories for scripts, data files, Python modules, etc. for the user installation scheme. See also PYTHONUSERBASE.

site.main()

Додає всі стандартні каталоги сайту до шляху пошуку модуля. Ця функція викликається автоматично під час імпорту цього модуля, якщо інтерпретатор Python не було запущено з прапорцем -S.

Змінено в версії 3.3: Ця функція раніше називалася безумовно.

site.addsitedir(sitedir, known_paths=None)

Додайте каталог до sys.path і обробіть його файли .pth. Зазвичай використовується в sitecustomize або usercustomize (див. вище).

site.getsitepackages()

Повертає список, що містить усі глобальні каталоги пакетів сайту.

Added in version 3.2.

site.getuserbase()

Повертає шлях до каталогу бази користувача, USER_BASE. Якщо він ще не ініціалізований, ця функція також встановить його, поважаючи PYTHONUSERBASE.

Added in version 3.2.

site.getusersitepackages()

Повертає шлях до каталогу пакетів сайтів користувача, USER_SITE. Якщо він ще не ініціалізований, ця функція також встановить його, поважаючи USER_BASE. Щоб визначити, чи було додано специфічні для користувача пакети сайтів до sys.path, слід використовувати ENABLE_USER_SITE.

Added in version 3.2.

Інтерфейс командного рядка

Модуль site також надає спосіб отримати каталоги користувача з командного рядка:

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

Якщо його викликати без аргументів, він надрукує вміст sys.path на стандартному виводі, а потім значення USER_BASE і те, чи існує каталог, потім те саме для USER_SITE і, нарешті, значення ENABLE_USER_SITE.

--user-base

Надрукуйте шлях до каталогу бази користувача.

--user-site

Надрукуйте шлях до каталогу site-packages користувача.

Якщо задано обидва параметри, буде надруковано базу користувачів і сайт користувачів (завжди в такому порядку), розділених os.pathsep.

Якщо вказано будь-який параметр, сценарій завершить роботу з одним із таких значень: 0, якщо каталог пакетів сайту користувача ввімкнено, 1, якщо він був вимкнений користувачем, 2, якщо його вимкнено з міркувань безпеки або адміністратором, і значення більше 2, якщо є помилка.

Дивись також