This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `site` — Site-specific configuration hook

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

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

Importing this module will append site-specific paths to the module search path and add a few builtins, unless `-S` was used. In that case, 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 `site.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/site-packages` (on Unix and macOS). 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» видалено.

Якщо файл із назвою «pyvenv.cfg» існує на один каталог вище sys.executable, sys.prefix і sys.exec_prefix встановлюються для цього каталогу, а також перевіряється наявність пакетів сайту (sys.base_prefix і sys.base_exec_prefix завжди будуть «справжні» префікси інсталяції Python). Якщо «pyvenv.cfg» (файл конфігурації початкового завантаження) містить ключ «include-system-site-packages» зі значенням, відмінним від «true» (незалежно від регістру), у префіксах системного рівня не здійснюватиметься пошук site- пакети; інакше вони будуть.

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

Примітка

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

Наприклад, припустімо, що `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` пропущено, оскільки він не згадується в обох файлах конфігурації шляху.

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.

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/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. 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 by Distutils 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`()

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

  Нове в версії 3.2.

`site.``getuserbase`()

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

  Нове в версії 3.2.

`site.``getusersitepackages`()

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

  Нове в версії 3.2.

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

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

    $ python3 -m site --user-site
    /home/user/.local/lib/python3.3/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 – Каталог пакетів сайту для кожного користувача