# `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, якщо є помилка.

Дивись також

- PEP 370 – Каталог пакетів сайту для кожного користувача

- The initialization of the sys.path module search path – The initialization of `sys.path`.