Конфігурація ініціалізації Python

Added in version 3.8.

Python можна ініціалізувати за допомогою Py_InitializeFromConfig() і структури PyConfig. Його можна попередньо ініціалізувати за допомогою Py_PreInitialize() і структури PyPreConfig.

Існує два види конфігурації:

  • Налаштування Python можна використовувати для створення налаштованого Python, який веде себе як звичайний Python. Наприклад, змінні середовища та аргументи командного рядка використовуються для налаштування Python.

  • Ізольована конфігурація може бути використана для вбудовування Python у програму. Він ізолює Python від системи. Наприклад, змінні середовища ігноруються, локаль LC_CTYPE не змінюється, а обробник сигналів не реєструється.

Функцію Py_RunMain() можна використовувати для написання спеціальної програми Python.

Дивіться також Ініціалізація, фіналізація та потоки.

Дивись також

PEP 587 «Конфігурація ініціалізації Python».

приклад

Приклад налаштованого Python, який завжди працює в ізольованому режимі:

int main(int argc, char **argv)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);

    return Py_RunMain();

exception:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) {
        return status.exitcode;
    }
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
}

PyWideStringList

type PyWideStringList

Список рядків wchar_t*.

Якщо length не дорівнює нулю, items не мають бути NULL, а всі рядки мають бути не NULL.

Методи:

PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)

Додайте елемент до списку.

Щоб викликати цю функцію, Python має бути попередньо ініціалізований.

PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)

Вставте елемент у список за індексом.

Якщо index більше або дорівнює довжині list, додайте item до list.

index must be greater than or equal to 0.

Щоб викликати цю функцію, Python має бути попередньо ініціалізований.

Поля структури:

Py_ssize_t length

Довжина списку.

wchar_t **items

Список елементів.

PyStatus

type PyStatus

Структура для збереження стану функції ініціалізації: успіх, помилка або вихід.

Для помилки він може зберегти назву функції C, яка створила помилку.

Поля структури:

int exitcode

Код виходу. Аргумент, переданий до exit().

const char *err_msg

Повідомлення про помилку.

const char *func

Ім’я функції, яка створила помилку, може бути NULL.

Функції для створення статусу:

PyStatus PyStatus_Ok(void)

Успіх.

PyStatus PyStatus_Error(const char *err_msg)

Помилка ініціалізації з повідомленням.

err_msg не має бути NULL.

PyStatus PyStatus_NoMemory(void)

Помилка виділення пам’яті (брак пам’яті).

PyStatus PyStatus_Exit(int exitcode)

Вийдіть із Python із вказаним кодом виходу.

Функції для обробки статусу:

int PyStatus_Exception(PyStatus status)

Статус помилка чи вихід? Якщо істина, виняток потрібно обробити; наприклад, викликом Py_ExitStatusException().

int PyStatus_IsError(PyStatus status)

Чи є результат помилкою?

int PyStatus_IsExit(PyStatus status)

Результат – це вихід?

void Py_ExitStatusException(PyStatus status)

Викличте exit(exitcode), якщо status є виходом. Роздрукуйте повідомлення про помилку та вийдіть із ненульовим кодом виходу, якщо статус є помилкою. Потрібно викликати, лише якщо PyStatus_Exception(status) не дорівнює нулю.

Примітка

Внутрішньо Python використовує макроси, які встановлюють PyStatus.func, тоді як функції для створення стану встановлюють func на NULL.

Приклад:

PyStatus alloc(void **ptr, size_t size)
{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) {
        return PyStatus_NoMemory();
    }
    return PyStatus_Ok();
}

int main(int argc, char **argv)
{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
    PyMem_Free(ptr);
    return 0;
}

PyPreConfig

type PyPreConfig

Структура, яка використовується для попередньої ініціалізації Python.

Функція ініціалізації попередньої конфігурації:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)

Ініціалізуйте попередню конфігурацію за допомогою Налаштування Python.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)

Ініціалізуйте попередню конфігурацію за допомогою Ізольованої конфігурації.

Поля структури:

int allocator

Ім’я розподілювачів пам’яті Python:

PYMEM_ALLOCATOR_PYMALLOC і PYMEM_ALLOCATOR_PYMALLOC_DEBUG не підтримуються, якщо Python налаштовано за допомогою --without-pymalloc.

Перегляньте Керування пам’яттю.

Типове значення: PYMEM_ALLOCATOR_NOT_SET.

int configure_locale

Set the LC_CTYPE locale to the user preferred locale.

If equals to 0, set coerce_c_locale and coerce_c_locale_warn members to 0.

Перегляньте locale encoding.

За замовчуванням: 1 у конфігурації Python, 0 в ізольованій конфігурації.

int coerce_c_locale

If equals to 2, coerce the C locale.

If equals to 1, read the LC_CTYPE locale to decide if it should be coerced.

Перегляньте locale encoding.

За замовчуванням: -1 у конфігурації Python, 0 в ізольованій конфігурації.

int coerce_c_locale_warn

Якщо значення відмінне від нуля, видати попередження, якщо локаль C виведена примусово.

За замовчуванням: -1 у конфігурації Python, 0 в ізольованій конфігурації.

int dev_mode

Python Development Mode: see PyConfig.dev_mode.

Типове значення: -1 в режимі Python, 0 в ізольованому режимі.

int isolated

Ізольований режим: див. PyConfig.isolated.

Типове значення: 0 в режимі Python, 1 в ізольованому режимі.

int legacy_windows_fs_encoding

Якщо відмінне від нуля:

Initialized from the PYTHONLEGACYWINDOWSFSENCODING environment variable value.

Доступно лише для Windows. Макрос #ifdef MS_WINDOWS можна використовувати для спеціального коду Windows.

Типове значення: 0.

int parse_argv

Якщо значення відмінне від нуля, Py_PreInitializeFromArgs() і Py_PreInitializeFromBytesArgs() аналізують свій аргумент argv так само, як звичайний Python аналізує аргументи командного рядка: див. Аргументи командного рядка.

За замовчуванням: 1 у конфігурації Python, 0 в ізольованій конфігурації.

int use_environment

Використовувати змінні середовища? Перегляньте PyConfig.use_environment.

За замовчуванням: 1 у конфігурації Python і 0 в ізольованій конфігурації.

int utf8_mode

Якщо не нуль, увімкніть Режим Python UTF-8.

Set to 0 or 1 by the -X utf8 command line option and the PYTHONUTF8 environment variable.

Also set to 1 if the LC_CTYPE locale is C or POSIX.

За замовчуванням: -1 у конфігурації Python і 0 в ізольованій конфігурації.

Попередня ініціалізація Python за допомогою PyPreConfig

Попередня ініціалізація Python:

Поточна попередня конфігурація (тип PyPreConfig) зберігається в _PyRuntime.preconfig.

Функції для попередньої ініціалізації Python:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)

Попередньо ініціалізуйте Python із попередньої конфігурації preconfig.

preconfig не має бути NULL.

PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char *const *argv)

Попередньо ініціалізуйте Python із попередньої конфігурації preconfig.

Проаналізуйте аргументи командного рядка argv (рядки байтів), якщо parse_argv preconfig не дорівнює нулю.

preconfig не має бути NULL.

PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t *const *argv)

Попередньо ініціалізуйте Python із попередньої конфігурації preconfig.

Проаналізуйте аргументи командного рядка argv (широкі рядки), якщо parse_argv preconfig не дорівнює нулю.

preconfig не має бути NULL.

Виклик відповідає за обробку винятків (помилка або вихід) за допомогою PyStatus_Exception() і Py_ExitStatusException().

Для Конфігурації Python (PyPreConfig_InitPythonConfig()), якщо Python ініціалізовано аргументами командного рядка, аргументи командного рядка також потрібно передати для попередньої ініціалізації Python, оскільки вони впливають на попередні конфігурація, як кодування. Наприклад, параметр командного рядка -X utf8 вмикає Режим Python UTF-8.

PyMem_SetAllocator() можна викликати після Py_PreInitialize() і перед Py_InitializeFromConfig(), щоб встановити спеціальний розподільник пам’яті. Його можна викликати перед Py_PreInitialize(), якщо PyPreConfig.allocator має значення PYMEM_ALLOCATOR_NOT_SET.

Функції виділення пам’яті Python, такі як PyMem_RawMalloc(), не можна використовувати до попередньої ініціалізації Python, тоді як прямий виклик malloc() і free() завжди безпечний. Py_DecodeLocale() не можна викликати до попередньої ініціалізації Python.

Приклад використання попередньої ініціалізації для ввімкнення режиму Python UTF-8:

PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) {
    Py_ExitStatusException(status);
}

/* at this point, Python speaks UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();

PyConfig

type PyConfig

Структура, що містить більшість параметрів для налаштування Python.

Після завершення необхідно використати функцію PyConfig_Clear(), щоб звільнити конфігураційну пам’ять.

Методи будови:

void PyConfig_InitPythonConfig(PyConfig *config)

Ініціалізуйте конфігурацію за допомогою Налаштування Python.

void PyConfig_InitIsolatedConfig(PyConfig *config)

Ініціалізуйте конфігурацію за допомогою ізольованої конфігурації.

PyStatus PyConfig_SetString(PyConfig *config, wchar_t *const *config_str, const wchar_t *str)

Скопіюйте широкий символьний рядок str у *config_str.

Попередньо ініціалізуйте Python, якщо потрібно.

PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t *const *config_str, const char *str)

Декодуйте str за допомогою Py_DecodeLocale() і встановіть результат у *config_str.

Попередньо ініціалізуйте Python, якщо потрібно.

PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t *const *argv)

Установіть аргументи командного рядка (argv член config) зі списку argv рядків широких символів.

Попередньо ініціалізуйте Python, якщо потрібно.

PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char *const *argv)

Установіть аргументи командного рядка (argv член config) зі списку argv рядків байтів. Декодуйте байти за допомогою Py_DecodeLocale().

Попередньо ініціалізуйте Python, якщо потрібно.

PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)

Установіть для списку широких рядків list значення length і items.

Попередньо ініціалізуйте Python, якщо потрібно.

PyStatus PyConfig_Read(PyConfig *config)

Прочитайте всю конфігурацію Python.

Поля, які вже ініціалізовані, залишаються без змін.

Fields for path configuration are no longer calculated or modified when calling this function, as of Python 3.11.

The PyConfig_Read() function only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are stripped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

Попередньо ініціалізуйте Python, якщо потрібно.

Змінено в версії 3.10: Аргументи PyConfig.argv тепер аналізуються лише один раз, PyConfig.parse_argv встановлюється на 2 після аналізу аргументів, і аргументи аналізуються, лише якщо PyConfig.parse_argv дорівнює 1.

Змінено в версії 3.11: PyConfig_Read() no longer calculates all paths, and so fields listed under Python Path Configuration may no longer be updated until Py_InitializeFromConfig() is called.

void PyConfig_Clear(PyConfig *config)

Звільніть конфігураційну пам’ять.

Більшість методів PyConfig за необхідності попередньо ініціалізують Python. У цьому випадку конфігурація попередньої ініціалізації Python (PyPreConfig) базується на PyConfig. Якщо поля конфігурації, які є спільними з PyPreConfig, налаштовано, їх потрібно встановити перед викликом методу PyConfig:

Moreover, if PyConfig_SetArgv() or PyConfig_SetBytesArgv() is used, this method must be called before other methods, since the preinitialization configuration depends on command line arguments (if parse_argv is non-zero).

Виклик цих методів відповідає за обробку винятків (помилка або вихід) за допомогою PyStatus_Exception() і Py_ExitStatusException().

Поля структури:

PyWideStringList argv

Command line arguments: sys.argv.

Установіть для parse_argv значення 1, щоб аналізувати argv так само, як звичайний Python аналізує аргументи командного рядка Python, а потім видаляти аргументи Python з argv.

Якщо argv порожній, додається порожній рядок, щоб гарантувати, що sys.argv завжди існує і ніколи не буде порожнім.

Типове значення: NULL.

Дивіться також елемент orig_argv.

int safe_path

If equals to zero, Py_RunMain() prepends a potentially unsafe path to sys.path at startup:

  • If argv[0] is equal to L"-m" (python -m module), prepend the current working directory.

  • If running a script (python script.py), prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.

  • Otherwise (python -c code and python), prepend an empty string, which means the current working directory.

Set to 1 by the -P command line option and the PYTHONSAFEPATH environment variable.

Default: 0 in Python config, 1 in isolated config.

Added in version 3.11.

wchar_t *base_exec_prefix

sys.base_exec_prefix.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

wchar_t *base_executable

Базовий виконуваний файл Python: sys._base_executable.

Встановлюється змінною середовища __PYVENV_LAUNCHER__.

Установити з PyConfig.executable, якщо NULL.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

wchar_t *base_prefix

sys.base_prefix.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

int buffered_stdio

If equals to 0 and configure_c_stdio is non-zero, disable buffering on the C streams stdout and stderr.

Set to 0 by the -u command line option and the PYTHONUNBUFFERED environment variable.

stdin завжди відкривається в режимі буферизації.

Типове значення: 1.

int bytes_warning

If equals to 1, issue a warning when comparing bytes or bytearray with str, or comparing bytes with int.

If equal or greater to 2, raise a BytesWarning exception in these cases.

Збільшується параметром командного рядка -b.

Типове значення: 0.

int warn_default_encoding

Якщо не нуль, видавати попередження EncodingWarning, коли io.TextIOWrapper використовує кодування за замовчуванням. Дивіться Увімкніть EncodingWarning для деталей.

Типове значення: 0.

Added in version 3.10.

int code_debug_ranges

If equals to 0, disables the inclusion of the end line and column mappings in code objects. Also disables traceback printing carets to specific error locations.

Set to 0 by the PYTHONNODEBUGRANGES environment variable and by the -X no_debug_ranges command line option.

Типове значення: 1.

Added in version 3.11.

wchar_t *check_hash_pycs_mode

Керуйте поведінкою перевірки файлів .pyc на основі хешу: значення параметра командного рядка --check-hash-based-pycs.

Дійсні значення:

  • L"always": хеш вихідного файлу для визнання недійсним незалежно від значення позначки „check_source“.

  • L"never": припустимо, що pics на основі хешу завжди дійсні.

  • L"default": прапор „check_source“ у pycs на основі хешу визначає недійсність.

Типове значення: L"default".

Дивіться також PEP 552 «Детерміновані фото».

int configure_c_stdio

Якщо не нуль, налаштуйте стандартні потоки C:

  • У Windows установіть бінарний режим (O_BINARY) для stdin, stdout і stderr.

  • Якщо buffered_stdio дорівнює нулю, вимкніть буферизацію потоків stdin, stdout і stderr.

  • Якщо interactive не дорівнює нулю, увімкніть буферизацію потоку на stdin і stdout (лише stdout у Windows).

За замовчуванням: 1 у конфігурації Python, 0 в ізольованій конфігурації.

int dev_mode

Якщо не нуль, увімкніть Режим розробки Python.

Set to 1 by the -X dev option and the PYTHONDEVMODE environment variable.

Типове значення: -1 в режимі Python, 0 в ізольованому режимі.

int dump_refs

Скинути посилання на Python?

Якщо значення відмінне від нуля, скинути всі об’єкти, які ще живі при виході.

Установіть значення 1 за допомогою змінної середовища PYTHONDUMPREFS.

Need a special build of Python with the Py_TRACE_REFS macro defined: see the configure --with-trace-refs option.

Типове значення: 0.

wchar_t *exec_prefix

Префікс каталогу сайту, де встановлено файли Python, залежні від платформи: sys.exec_prefix.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

wchar_t *executable

Абсолютний шлях виконуваного двійкового файлу для інтерпретатора Python: sys.executable.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

int faulthandler

Увімкнути обробник помилок?

Якщо не нуль, викликати faulthandler.enable() під час запуску.

Установіть значення 1 за допомогою -X faulthandler і змінної середовища PYTHONFAULTHANDLER.

Типове значення: -1 в режимі Python, 0 в ізольованому режимі.

wchar_t *filesystem_encoding

Кодування файлової системи: sys.getfilesystemencoding().

У macOS, Android і VxWorks: використовуйте "utf-8" за умовчанням.

У Windows: використовуйте "utf-8" за замовчуванням або "mbcs", якщо legacy_windows_fs_encoding PyPreConfig не дорівнює нулю.

Стандартне кодування на інших платформах:

  • "utf-8", якщо PyPreConfig.utf8_mode не нульовий.

  • "ascii", якщо Python виявляє, що nl_langinfo(CODESET) повідомляє про кодування ASCII, тоді як функція mbstowcs() декодує з іншого кодування (зазвичай Latin1).

  • "utf-8", якщо nl_langinfo(CODESET) повертає порожній рядок.

  • В іншому випадку використовуйте результат locale encoding: nl_langinfo(CODESET).

Під час запуску Python назва кодування нормалізується до назви кодека Python. Наприклад, "ANSI_X3.4-1968" замінюється на "ascii".

Дивіться також елемент filesystem_errors.

wchar_t *filesystem_errors

Обробник помилок файлової системи: sys.getfilesystemencodeerrors().

У Windows: використовуйте "surrogatepass" за замовчуванням або "replace", якщо legacy_windows_fs_encoding PyPreConfig не дорівнює нулю.

На інших платформах: використовуйте "surrogateescape" за умовчанням.

Підтримувані засоби обробки помилок:

  • "суворий"

  • "сурогатна втеча"

  • "surrogatepass" (підтримується лише з кодуванням UTF-8)

Дивіться також елемент filesystem_encoding.

unsigned long hash_seed
int use_hash_seed

Рандомізоване початкове значення хеш-функції.

Якщо use_hash_seed дорівнює нулю, початкове значення вибирається випадковим чином під час запуску Python, а hash_seed ігнорується.

Встановлюється змінною середовища PYTHONHASHSEED.

Значення use_hash_seed за замовчуванням: -1 у режимі Python, 0 в ізольованому режимі.

wchar_t *home

Python home directory.

If Py_SetPythonHome() has been called, use its argument if it is not NULL.

Встановлюється змінною середовища PYTHONHOME.

Типове значення: NULL.

Частина вхідних даних Налаштування шляху Python.

int import_time

Якщо не нуль, час імпорту профілю.

Установіть 1 за допомогою параметра -X importtime і змінної середовища PYTHONPROFILEIMPORTTIME.

Типове значення: 0.

int inspect

Увійти в інтерактивний режим після виконання сценарію або команди.

If greater than 0, enable inspect: when a script is passed as first argument or the -c option is used, enter interactive mode after executing the script or the command, even when sys.stdin does not appear to be a terminal.

Збільшується параметром командного рядка -i. Установіть значення 1, якщо змінна середовища PYTHONINSPECT не порожня.

Типове значення: 0.

int install_signal_handlers

Установити обробники сигналів Python?

Типове значення: 1 в режимі Python, 0 в ізольованому режимі.

int interactive

If greater than 0, enable the interactive mode (REPL).

Збільшується параметром командного рядка -i.

Типове значення: 0.

int int_max_str_digits

Configures the integer string conversion length limitation. An initial value of -1 means the value will be taken from the command line or environment or otherwise default to 4300 (sys.int_info.default_max_str_digits). A value of 0 disables the limitation. Values greater than zero but less than 640 (sys.int_info.str_digits_check_threshold) are unsupported and will produce an error.

Configured by the -X int_max_str_digits command line flag or the PYTHONINTMAXSTRDIGITS environment variable.

Default: -1 in Python mode. 4300 (sys.int_info.default_max_str_digits) in isolated mode.

Added in version 3.12.

int isolated

If greater than 0, enable isolated mode:

  • Set safe_path to 1: don’t prepend a potentially unsafe path to sys.path at Python startup, such as the current directory, the script’s directory or an empty string.

  • Set use_environment to 0: ignore PYTHON environment variables.

  • Set user_site_directory to 0: don’t add the user site directory to sys.path.

  • Python REPL не імпортує readline і не вмикає стандартну конфігурацію readline в інтерактивних підказках.

Set to 1 by the -I command line option.

Типове значення: 0 в режимі Python, 1 в ізольованому режимі.

See also the Isolated Configuration and PyPreConfig.isolated.

int legacy_windows_stdio

If non-zero, use io.FileIO instead of io._WindowsConsoleIO for sys.stdin, sys.stdout and sys.stderr.

Установіть значення 1, якщо змінна середовища PYTHONLEGACYWINDOWSSTDIO має значення непорожнього рядка.

Доступно лише для Windows. Макрос #ifdef MS_WINDOWS можна використовувати для спеціального коду Windows.

Типове значення: 0.

Дивіться також PEP 528 (Змінити кодування консолі Windows на UTF-8).

int malloc_stats

Якщо значення відмінне від нуля, вивести статистику на Python pymalloc memory allocator при виході.

Установіть значення 1 за допомогою змінної середовища PYTHONMALLOCSTATS.

Параметр ігнорується, якщо Python налаштовано за допомогою параметра --without-pymalloc.

Типове значення: 0.

wchar_t *platlibdir

Назва каталогу бібліотеки платформи: sys.platlibdir.

Встановлюється змінною середовища PYTHONPLATLIBDIR.

Default: value of the PLATLIBDIR macro which is set by the configure --with-platlibdir option (default: "lib", or "DLLs" on Windows).

Частина вхідних даних Налаштування шляху Python.

Added in version 3.9.

Змінено в версії 3.11: This macro is now used on Windows to locate the standard library extension modules, typically under DLLs. However, for compatibility, note that this value is ignored for any non-standard layouts, including in-tree builds and virtual environments.

wchar_t *pythonpath_env

Module search paths (sys.path) as a string separated by DELIM (os.pathsep).

Встановлюється змінною середовища PYTHONPATH.

Типове значення: NULL.

Частина вхідних даних Налаштування шляху Python.

PyWideStringList module_search_paths
int module_search_paths_set

Шляхи пошуку модуля: sys.path.

If module_search_paths_set is equal to 0, Py_InitializeFromConfig() will replace module_search_paths and sets module_search_paths_set to 1.

За замовчуванням: порожній список (module_search_paths) і 0 (module_search_paths_set).

Частина виведення Налаштування шляху Python.

int optimization_level

Рівень оптимізації компіляції:

  • 0: оптимізатор Peephole, встановіть __debug__ на True.

  • 1: Рівень 0, видалити твердження, встановити __debug__ на False.

  • 2: Рівень 1, рядки документації.

Збільшується параметром командного рядка -O. Установіть значення змінної середовища PYTHONOPTIMIZE.

Типове значення: 0.

PyWideStringList orig_argv

Список вихідних аргументів командного рядка, переданих у виконуваний файл Python: sys.orig_argv.

Якщо список orig_argv порожній і argv не є списком, який містить лише порожній рядок, PyConfig_Read() копіює argv в orig_argv перед зміною argv (якщо parse_argv не дорівнює нулю) .

Дивіться також член argv і функцію Py_GetArgcArgv().

За замовчуванням: порожній список.

Added in version 3.10.

int parse_argv

Розібрати аргументи командного рядка?

Якщо дорівнює 1, аналізувати argv так само, як звичайний Python аналізує аргументи командного рядка, і видаляти аргументи Python з argv.

The PyConfig_Read() function only parses PyConfig.argv arguments once: PyConfig.parse_argv is set to 2 after arguments are parsed. Since Python arguments are stripped from PyConfig.argv, parsing arguments twice would parse the application options as Python options.

Типове значення: 1 в режимі Python, 0 в ізольованому режимі.

Змінено в версії 3.10: Аргументи PyConfig.argv тепер аналізуються, лише якщо PyConfig.parse_argv дорівнює 1.

int parser_debug

Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending on compilation options).

Збільшується параметром командного рядка -d. Установіть значення змінної середовища PYTHONDEBUG.

Need a debug build of Python (the Py_DEBUG macro must be defined).

Типове значення: 0.

int pathconfig_warnings

If non-zero, calculation of path configuration is allowed to log warnings into stderr. If equals to 0, suppress these warnings.

Типове значення: 1 в режимі Python, 0 в ізольованому режимі.

Частина вхідних даних Налаштування шляху Python.

Змінено в версії 3.11: Now also applies on Windows.

wchar_t *prefix

Префікс каталогу сайту, де встановлено незалежні від платформи файли Python: sys.prefix.

Типове значення: NULL.

Частина виведення Налаштування шляху Python.

wchar_t *program_name

Ім’я програми, що використовується для ініціалізації executable і в ранніх повідомленнях про помилки під час ініціалізації Python.

  • If Py_SetProgramName() has been called, use its argument.

  • У macOS використовуйте змінну середовища PYTHONEXECUTABLE, якщо встановлено.

  • Якщо визначено макрос WITH_NEXT_FRAMEWORK, використовуйте змінну середовища __PYVENV_LAUNCHER__, якщо встановлено.

  • Використовуйте argv[0] argv, якщо доступний і не є порожнім.

  • В іншому випадку використовуйте L"python" у Windows або L"python3" на інших платформах.

Типове значення: NULL.

Частина вхідних даних Налаштування шляху Python.

wchar_t *pycache_prefix

Каталог, де записуються кешовані файли .pyc: sys.pycache_prefix.

Set by the -X pycache_prefix=PATH command line option and the PYTHONPYCACHEPREFIX environment variable.

Якщо NULL, sys.pycache_prefix має значення None.

Типове значення: NULL.

int quiet

Quiet mode. If greater than 0, don’t display the copyright and version at Python startup in interactive mode.

Збільшується параметром командного рядка -q.

Типове значення: 0.

wchar_t *run_command

Значення параметра командного рядка -c.

Використовується Py_RunMain().

Типове значення: NULL.

wchar_t *run_filename

Filename passed on the command line: trailing command line argument without -c or -m. It is used by the Py_RunMain() function.

For example, it is set to script.py by the python3 script.py arg command line.

See also the PyConfig.skip_source_first_line option.

Типове значення: NULL.

wchar_t *run_module

Значення параметра командного рядка -m.

Використовується Py_RunMain().

Типове значення: NULL.

int show_ref_count

Show total reference count at exit (excluding immortal objects)?

Set to 1 by -X showrefcount command line option.

Need a debug build of Python (the Py_REF_DEBUG macro must be defined).

Типове значення: 0.

int site_import

Імпортувати модуль site під час запуску?

Якщо дорівнює нулю, вимкніть імпорт сайту модуля та залежні від сайту маніпуляції sys.path, які він тягне за собою.

Також вимкніть ці маніпуляції, якщо модуль site буде явно імпортовано пізніше (викличте site.main(), якщо ви хочете, щоб вони були активовані).

Установіть 0 за допомогою параметра командного рядка -S.

sys.flags.no_site is set to the inverted value of site_import.

Типове значення: 1.

int skip_source_first_line

Якщо значення не нульове, пропустіть перший рядок джерела PyConfig.run_filename.

Це дозволяє використовувати не-Unix форми #!cmd. Це призначено лише для спеціального злому DOS.

Установіть значення 1 за допомогою параметра командного рядка -x.

Типове значення: 0.

wchar_t *stdio_encoding
wchar_t *stdio_errors

Кодування та помилки кодування sys.stdin, sys.stdout і sys.stderr (але sys.stderr завжди використовує "backslashreplace" обробник помилок).

If Py_SetStandardStreamEncoding() has been called, use its error and errors arguments if they are not NULL.

Використовуйте змінну середовища PYTHONIOENCODING, якщо вона непорожня.

Стандартне кодування:

Обробник помилок за замовчуванням:

  • У Windows: використовуйте "surrogateescape".

  • "surrogateescape", якщо PyPreConfig.utf8_mode не нульовий, або якщо LC_CTYPE локаль «C» або «POSIX».

  • "строгий" інакше.

int tracemalloc

Увімкнути tracemalloc?

Якщо не нуль, викликати tracemalloc.start() під час запуску.

Встановлюється параметром командного рядка -X tracemalloc=N і змінною середовища PYTHONTRACEMALLOC.

Типове значення: -1 в режимі Python, 0 в ізольованому режимі.

int perf_profiling

Enable compatibility mode with the perf profiler?

If non-zero, initialize the perf trampoline. See Python support for the Linux perf profiler for more information.

Set by -X perf command line option and by the PYTHONPERFSUPPORT environment variable.

Default: -1.

Added in version 3.12.

int use_environment

Використовувати змінні середовища?

Якщо дорівнює нулю, ігноруйте змінні середовища.

Set to 0 by the -E environment variable.

За замовчуванням: 1 у конфігурації Python і 0 в ізольованій конфігурації.

int user_site_directory

Якщо значення не нульове, додайте каталог сайту користувача до sys.path.

Установіть значення 0 за допомогою параметрів командного рядка -s і -I.

Установлено значення 0 за допомогою змінної середовища PYTHONNOUSERSITE.

Типове значення: 1 в режимі Python, 0 в ізольованому режимі.

int verbose

Verbose mode. If greater than 0, print a message each time a module is imported, showing the place (filename or built-in module) from which it is loaded.

If greater than or equal to 2, print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.

Збільшується параметром командного рядка -v.

Set by the PYTHONVERBOSE environment variable value.

Типове значення: 0.

PyWideStringList warnoptions

Параметри модуля warnings для створення фільтрів попереджень, від найнижчого до найвищого пріоритету: sys.warnoptions.

Модуль warnings додає sys.warnoptions у зворотному порядку: останній елемент PyConfig.warnoptions стає першим елементом warnings.filters, який є перевіряється першим (найвищий пріоритет).

Параметр командного рядка -W додає значення до warnoptions, тому його можна використовувати кілька разів.

Змінну середовища PYTHONWARNINGS також можна використовувати для додавання параметрів попередження. Можна вказати декілька параметрів, розділених комами (,).

За замовчуванням: порожній список.

int write_bytecode

If equal to 0, Python won’t try to write .pyc files on the import of source modules.

Установіть значення 0 за допомогою параметра командного рядка -B і змінної середовища PYTHONDONTWRITEBYTECODE.

sys.dont_write_bytecode ініціалізується інвертованим значенням write_bytecode.

Типове значення: 1.

PyWideStringList xoptions

Значення параметрів командного рядка -X: sys._xoptions.

За замовчуванням: порожній список.

Якщо parse_argv не дорівнює нулю, аргументи argv аналізуються так само, як звичайний Python аналізує аргументи командного рядка, і Python аргументи видаляються з argv.

Параметри xoptions аналізуються, щоб встановити інші параметри: дивіться параметр командного рядка -X.

Змінено в версії 3.9: Поле show_alloc_count видалено.

Ініціалізація за допомогою PyConfig

Function to initialize Python:

PyStatus Py_InitializeFromConfig(const PyConfig *config)

Initialize Python from config configuration.

Виклик відповідає за обробку винятків (помилка або вихід) за допомогою PyStatus_Exception() і Py_ExitStatusException().

Якщо PyImport_FrozenModules(), PyImport_AppendInittab() або PyImport_ExtendInittab() використовуються, їх потрібно встановити або викликати після попередньої ініціалізації Python та перед ініціалізацією Python. Якщо Python ініціалізовано кілька разів, перед кожною ініціалізацією Python потрібно викликати PyImport_AppendInittab() або PyImport_ExtendInittab().

Поточна конфігурація (тип PyConfig) зберігається в PyInterpreterState.config.

Приклад налаштування імені програми:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) {
        goto exception;
    }

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) {
        goto exception;
    }
    PyConfig_Clear(&config);
    return;

exception:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
}

More complete example modifying the default configuration, read the configuration, and then override some parameters. Note that since 3.11, many parameters are not calculated until initialization, and so values cannot be read from the configuration structure. Any values set before initialize is called will be left unchanged by initialization:

PyStatus init_python(const char *program_name)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Specify sys.path explicitly */
    /* If you want to modify the default set of paths, finish
       initialization first and then use PySys_GetObject("path") */
    config.module_search_paths_set = 1;
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) {
        goto done;
    }
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) {
        goto done;
    }

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
}

Ізольована конфігурація

Функції PyPreConfig_InitIsolatedConfig() і PyConfig_InitIsolatedConfig() створюють конфігурацію для ізоляції Python від системи. Наприклад, щоб вбудувати Python у програму.

Ця конфігурація ігнорує глобальні змінні конфігурації, змінні середовища, аргументи командного рядка (PyConfig.argv не аналізується) і каталог сайту користувача. Стандартні потоки C (наприклад: stdout) і локаль LC_CTYPE залишаються без змін. Обробники сигналів не встановлені.

Configuration files are still used with this configuration to determine paths that are unspecified. Ensure PyConfig.home is specified to avoid computing the default path configuration.

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

Функції PyPreConfig_InitPythonConfig() і PyConfig_InitPythonConfig() створюють конфігурацію для створення налаштованого Python, який веде себе як звичайний Python.

Для налаштування Python використовуються змінні середовища та аргументи командного рядка, тоді як глобальні змінні конфігурації ігноруються.

Ця функція вмикає примусове налаштування локалі C (PEP 538) і Python UTF-8 Mode (PEP 540) залежно від локалі LC_CTYPE, PYTHONUTF8 і Змінні середовища PYTHONCOERCECLOCALE.

Конфігурація шляху Python

PyConfig містить кілька полів для конфігурації шляху:

If at least one «output field» is not set, Python calculates the path configuration to fill unset fields. If module_search_paths_set is equal to 0, module_search_paths is overridden and module_search_paths_set is set to 1.

It is possible to completely ignore the function calculating the default path configuration by setting explicitly all path configuration output fields listed above. A string is considered as set even if it is non-empty. module_search_paths is considered as set if module_search_paths_set is set to 1. In this case, module_search_paths will be used without modification.

Set pathconfig_warnings to 0 to suppress warnings when calculating the path configuration (Unix only, Windows does not log any warning).

Якщо поля base_prefix або base_exec_prefix не встановлені, вони успадковують свої значення від prefix і exec_prefix відповідно.

Py_RunMain() і Py_Main() змінюють sys.path:

  • Якщо run_filename встановлено і це каталог, який містить сценарій __main__.py, додайте run_filename до sys.path.

  • Якщо isolated дорівнює нулю:

    • Якщо встановлено run_module, додайте поточний каталог до sys.path. Нічого не робити, якщо поточний каталог неможливо прочитати.

    • Якщо встановлено run_filename, додайте каталог імені файлу перед sys.path.

    • В іншому випадку додайте порожній рядок до sys.path.

Якщо site_import не дорівнює нулю, sys.path можна змінити за допомогою модуля site. Якщо user_site_directory не дорівнює нулю, а каталог пакетів сайту користувача існує, модуль site додає каталог пакетів сайту користувача до sys.path.

У конфігурації шляху використовуються такі файли конфігурації:

  • pyvenv.cfg

  • ._pth file (ex: python._pth)

  • pybuilddir.txt (лише Unix)

If a ._pth file is present:

The __PYVENV_LAUNCHER__ environment variable is used to set PyConfig.base_executable

Py_RunMain()

int Py_RunMain(void)

Execute the command (PyConfig.run_command), the script (PyConfig.run_filename) or the module (PyConfig.run_module) specified on the command line or in the configuration.

By default and when if -i option is used, run the REPL.

Finally, finalizes Python and returns an exit status that can be passed to the exit() function.

See Python Configuration for an example of customized Python always running in isolated mode using Py_RunMain().

Py_GetArgcArgv()

void Py_GetArgcArgv(int *argc, wchar_t ***argv)

Отримайте оригінальні аргументи командного рядка до того, як Python їх змінив.

Дивіться також член PyConfig.orig_argv.

Приватний тимчасовий API багатофазної ініціалізації

Цей розділ є приватним тимчасовим API, який представляє багатофазову ініціалізацію, основну функцію PEP 432:

  • Фаза ініціалізації «Core», «мінімум Python»:

    • Вбудовані типи;

    • Вбудовані винятки;

    • Вбудовані та заморожені модулі;

    • Модуль sys ініціалізовано лише частково (наприклад: sys.path ще не існує).

  • «Основна» фаза ініціалізації, Python повністю ініціалізовано:

Приватний тимчасовий API:

PyStatus _Py_InitializeMain(void)

Перейдіть до фази ініціалізації «Main», завершіть ініціалізацію Python.

Жоден модуль не імпортується під час фази «Core», а модуль importlib не налаштовано: Конфігурація шляху застосовується лише під час фази «Main». Це може дозволити налаштувати Python у Python, щоб перевизначити або налаштувати Конфігурацію шляху, можливо, встановити спеціальний імпортер sys.meta_path або хук імпорту тощо.

It may become possible to calculate the Path Configuration in Python, after the Core phase and before the Main phase, which is one of the PEP 432 motivation.

Фаза «Core» не визначена належним чином: що має бути, а що не має бути доступним на цій фазі, ще не визначено. API позначено як приватний і тимчасовий: API можна змінити або навіть видалити в будь-який час, доки не буде розроблено відповідний публічний API.

Приклад виконання коду Python між фазами ініціалізації «Core» і «Main»:

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&config);
    PyConfig_Clear(&config);
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) {
        Py_ExitStatusException(status);
    }
}