파이썬 초기화 구성¶

PyConfig C API¶

Added in version 3.8.

Python can be initialized with Py_InitializeFromConfig() and the PyConfig structure. It can be preinitialized with Py_PreInitialize() and the PyPreConfig structure.

There are two kinds of configuration:

The Python Configuration can be used to build a customized Python which behaves as the regular Python. For example, environment variables and command line arguments are used to configure Python.
The Isolated Configuration can be used to embed Python into an application. It isolates Python from the system. For example, environment variables are ignored, the LC_CTYPE locale is left unchanged and no signal handler is registered.

The Py_RunMain() function can be used to write a customized Python program.

초기화, 파이널리제이션 및 스레드도 참조하십시오.

PEP 587 “파이썬 초기화 구성”.

Example¶

항상 격리 모드에서 실행되는 사용자 정의 파이썬의 예:

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가 0이 아니면, items는 NULL이 아니어야 하고 모든 문자열은 NULL이 아니어야 합니다.

메서드:

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

item을 list에 추가합니다.

이 함수를 호출하려면 파이썬을 사전 초기화해야 합니다.

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

item을 list의 index에 삽입합니다.

index가 list 길이보다 크거나 같으면, item을 list에 추가(append)합니다.

index must be greater than or equal to 0.

이 함수를 호출하려면 파이썬을 사전 초기화해야 합니다.

구조체 필드:

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 must not be NULL.

PyStatus PyStatus_NoMemory(void)¶: 메모리 할당 실패 (메모리 부족).

PyStatus PyStatus_Exit(int exitcode)¶: 지정된 종료 코드로 파이썬을 종료합니다.

상태를 처리하는 함수:

int PyStatus_Exception(PyStatus status)¶: 상태가 에러입니까? 아니면 종료입니까? 참이면, 예외를 처리해야 합니다; 예를 들어 Py_ExitStatusException() 을 호출하여.

int PyStatus_IsError(PyStatus status)¶: 결과가 에러입니까?

int PyStatus_IsExit(PyStatus status)¶: 결과가 종료입니까?

void Py_ExitStatusException(PyStatus status)¶: status가 종료이면 exit(exitcode)를 호출합니다. status가 에러이면 에러 메시지를 인쇄하고 0이 아닌 종료 코드로 종료합니다. PyStatus_Exception(status)가 0이 아닐 때만 호출해야 합니다.

참고

내부적으로, 파이썬은 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¶

Structure used to preinitialize Python.

사전 구성을 초기화하는 함수:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶: 파이썬 구성으로 사전 구성을 초기화합니다.

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: 격리된 구성으로 사전 구성을 초기화합니다.

구조체 필드:

int allocator¶

Name of the Python memory allocators:

PYMEM_ALLOCATOR_NOT_SET (0): don’t change memory allocators (use defaults).
PYMEM_ALLOCATOR_DEFAULT (1): default memory allocators.
PYMEM_ALLOCATOR_DEBUG (2): default memory allocators with debug hooks.
PYMEM_ALLOCATOR_MALLOC (3): use malloc() of the C library.
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): force usage of malloc() with debug hooks.
PYMEM_ALLOCATOR_PYMALLOC (5): Python pymalloc memory allocator.
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Python pymalloc memory allocator with debug hooks.
PYMEM_ALLOCATOR_MIMALLOC (6): use mimalloc, a fast malloc replacement.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): use mimalloc, a fast malloc replacement with debug hooks.

PYMEM_ALLOCATOR_PYMALLOC and PYMEM_ALLOCATOR_PYMALLOC_DEBUG are not supported if Python is configured using --without-pymalloc.

PYMEM_ALLOCATOR_MIMALLOC and PYMEM_ALLOCATOR_MIMALLOC_DEBUG are not supported if Python is configured using --without-mimalloc or if the underlying atomic support isn’t available.

메모리 관리를 참조하십시오.

Default: 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.

See the locale encoding.

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

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.

See the locale encoding.

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

int coerce_c_locale_warn¶

0이 아니면, C 로케일이 강제될 때 경고가 발생합니다.

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

int dev_mode¶

Python Development Mode: see PyConfig.dev_mode.

Default: -1 in Python mode, 0 in isolated mode.

int isolated¶

Isolated mode: see PyConfig.isolated.

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

int legacy_windows_fs_encoding¶

If non-zero:

Set PyPreConfig.utf8_mode to 0,
Set PyConfig.filesystem_encoding to "mbcs",
Set PyConfig.filesystem_errors to "replace".

Initialized from the PYTHONLEGACYWINDOWSFSENCODING environment variable value.

윈도우에서만 사용 가능합니다. #ifdef MS_WINDOWS 매크로는 윈도우 특정 코드에 사용할 수 있습니다.

Default: 0.

int parse_argv¶

0이 아니면, Py_PreInitializeFromArgs()와 Py_PreInitializeFromBytesArgs()는 일반 파이썬이 명령 줄 인자를 구문 분석하는 것과 같은 방식으로 argv 인자를 구문 분석합니다. 명령 줄 인자를 참조하십시오.

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

int use_environment¶

Use environment variables? See PyConfig.use_environment.

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

int utf8_mode¶

If non-zero, enable the Python UTF-8 Mode.

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.

Default: -1 in Python config and 0 in isolated config.

Preinitialize Python with PyPreConfig¶

The preinitialization of Python:

Set the Python memory allocators (PyPreConfig.allocator)
Configure the LC_CTYPE locale (locale encoding)
Set the Python UTF-8 Mode (PyPreConfig.utf8_mode)

The current preconfiguration (PyPreConfig type) is stored in _PyRuntime.preconfig.

파이썬을 사전 초기화하는 함수:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶

preconfig 사전 구성에서 파이썬을 사전 초기화합니다.

preconfig must not be NULL.

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

preconfig 사전 구성에서 파이썬을 사전 초기화합니다.

Parse argv command line arguments (bytes strings) if parse_argv of preconfig is non-zero.

preconfig must not be NULL.

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

preconfig 사전 구성에서 파이썬을 사전 초기화합니다.

Parse argv command line arguments (wide strings) if parse_argv of preconfig is non-zero.

preconfig must not be NULL.

호출자는 PyStatus_Exception()과 Py_ExitStatusException() 을 사용하여 예외(에러나 종료)를 처리해야 합니다.

For Python Configuration (PyPreConfig_InitPythonConfig()), if Python is initialized with command line arguments, the command line arguments must also be passed to preinitialize Python, since they have an effect on the pre-configuration like encodings. For example, the -X utf8 command line option enables the Python UTF-8 Mode.

PyMem_SetAllocator()는 Py_PreInitialize() 이후에 Py_InitializeFromConfig() 이전에 호출하여 사용자 정의 메모리 할당자를 설치할 수 있습니다. PyPreConfig.allocator가 PYMEM_ALLOCATOR_NOT_SET으로 설정되면 Py_PreInitialize() 전에 호출할 수 있습니다.

Python memory allocation functions like PyMem_RawMalloc() must not be used before the Python preinitialization, whereas calling directly malloc() and free() is always safe. Py_DecodeLocale() must not be called before the Python preinitialization.

Example using the preinitialization to enable the Python UTF-8 Mode:

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¶

파이썬을 구성하기 위한 대부분의 파라미터를 포함하는 구조체.

When done, the PyConfig_Clear() function must be used to release the configuration memory.

구조체 메서드:

void PyConfig_InitPythonConfig(PyConfig *config)¶: Initialize configuration with the Python Configuration.

void PyConfig_InitIsolatedConfig(PyConfig *config)¶: Initialize configuration with the Isolated Configuration.

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

와이드 문자열 str을 *config_str로 복사합니다.

Preinitialize Python if needed.

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

Decode str using Py_DecodeLocale() and set the result into *config_str.

Preinitialize Python if needed.

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

Set command line arguments (argv member of config) from the argv list of wide character strings.

Preinitialize Python if needed.

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

Set command line arguments (argv member of config) from the argv list of bytes strings. Decode bytes using Py_DecodeLocale().

Preinitialize Python if needed.

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

와이드 문자열 리스트 list를 length와 items로 설정합니다.

Preinitialize Python if needed.

PyStatus PyConfig_Read(PyConfig *config)¶

모든 파이썬 구성을 읽습니다.

이미 초기화된 필드는 변경되지 않습니다.

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.

Preinitialize Python if needed.

버전 3.10에서 변경: The PyConfig.argv arguments are now only parsed once, PyConfig.parse_argv is set to 2 after arguments are parsed, and arguments are only parsed if PyConfig.parse_argv equals 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)¶: 구성 메모리를 해제합니다.

Most PyConfig methods preinitialize Python if needed. In that case, the Python preinitialization configuration (PyPreConfig) in based on the PyConfig. If configuration fields which are in common with PyPreConfig are tuned, they must be set before calling a PyConfig method:

PyConfig.dev_mode
PyConfig.isolated
PyConfig.parse_argv
PyConfig.use_environment

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¶

Set sys.argv command line arguments based on argv. These parameters are similar to those passed to the program’s main() function with the difference that the first entry should refer to the script file to be executed rather than the executable hosting the Python interpreter. If there isn’t a script that will be run, the first entry in argv can be an empty string.

Set parse_argv to 1 to parse argv the same way the regular Python parses Python command line arguments and then to strip Python arguments from argv.

If argv is empty, an empty string is added to ensure that sys.argv always exists and is never empty.

Default: NULL.

PyConfig를 사용한 초기화¶

Initializing the interpreter from a populated configuration struct is handled by calling Py_InitializeFromConfig().

호출자는 PyStatus_Exception()과 Py_ExitStatusException() 을 사용하여 예외(에러나 종료)를 처리해야 합니다.

If PyImport_FrozenModules(), PyImport_AppendInittab() or PyImport_ExtendInittab() are used, they must be set or called after Python preinitialization and before the Python initialization. If Python is initialized multiple times, PyImport_AppendInittab() or PyImport_ExtendInittab() must be called before each Python initialization.

The current configuration (PyConfig type) is stored in 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() 함수는 시스템에서 파이썬을 격리하는 구성을 만듭니다. 예를 들어, 파이썬을 응용 프로그램에 내장하기 위해.

This configuration ignores global configuration variables, environment variables, command line arguments (PyConfig.argv is not parsed) and user site directory. The C standard streams (ex: stdout) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed.

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.

파이썬 구성¶

PyPreConfig_InitPythonConfig()와 PyConfig_InitPythonConfig() 함수는 일반 파이썬처럼 동작하는 사용자 정의된 파이썬을 빌드하기 위한 구성을 만듭니다.

환경 변수와 명령 줄 인자는 파이썬을 구성하는 데 사용되는 반면, 전역 구성 변수는 무시됩니다.

This function enables C locale coercion (PEP 538) and Python UTF-8 Mode (PEP 540) depending on the LC_CTYPE locale, PYTHONUTF8 and PYTHONCOERCECLOCALE environment variables.

Python Path Configuration¶

PyConfig에는 경로 구성을 위한 여러 필드가 포함되어 있습니다:

경로 구성 입력:
- PyConfig.home
- PyConfig.platlibdir
- PyConfig.pathconfig_warnings
- PyConfig.program_name
- PyConfig.pythonpath_env
- 현재 작업 디렉터리: 절대 경로를 얻기 위해
- (PyConfig.program_name에서) 프로그램 전체 경로를 얻기 위한 PATH 환경 변수
- __PYVENV_LAUNCHER__ 환경 변수
- (윈도우 전용) HKEY_CURRENT_USER와 HKEY_LOCAL_MACHINE의 “SoftwarePythonPythonCoreX.YPythonPath” 아래에 있는 레지스트리의 응용 프로그램 경로 (여기서 X.Y는 파이썬 버전입니다).
경로 구성 출력 필드:

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가 0이면:
- run_module이 설정되면, 현재 디렉터리를 sys.path 앞에 추가합니다. 현재 디렉터리를 읽을 수 없으면 아무것도 하지 않습니다.
- run_filename이 설정되면, 파일명의 디렉터리를 sys.path 앞에 추가합니다.
- 그렇지 않으면, 빈 문자열을 sys.path 앞에 추가합니다.

site_import가 0이 아니면, site 모듈이 sys.path를 수정할 수 있습니다. user_site_directory가 0이 아니고 사용자의 site-package 디렉터리가 존재하면, site 모듈은 사용자의 site-package 디렉터리를 sys.path에 추가합니다.

다음과 같은 구성 파일이 경로 구성에 사용됩니다:

pyvenv.cfg
._pth file (ex: python._pth)
pybuilddir.txt (유닉스 전용)

If a ._pth file is present:

Set isolated to 1.
Set use_environment to 0.
Set site_import to 0.
Set safe_path to 1.

If home is not set and a pyvenv.cfg file is present in the same directory as executable, or its parent, prefix and exec_prefix are set that location. When this happens, base_prefix and base_exec_prefix still keep their value, pointing to the base installation. See Virtual Environments for more information.

The __PYVENV_LAUNCHER__ environment variable is used to set PyConfig.base_executable.

버전 3.14에서 변경: prefix, and exec_prefix, are now set to the pyvenv.cfg directory. This was previously done by site, therefore affected by -S.

PyInitConfig C API¶

C API to configure the Python initialization (PEP 741).

Added in version 3.14.

Create Config¶

struct PyInitConfig¶: Opaque structure to configure the Python initialization.

PyInitConfig *PyInitConfig_Create(void)¶

Create a new initialization configuration using Isolated Configuration default values.

It must be freed by PyInitConfig_Free().

Return NULL on memory allocation failure.

void PyInitConfig_Free(PyInitConfig *config)¶

Free memory of the initialization configuration config.

If config is NULL, no operation is performed.

Error Handling¶

int PyInitConfig_GetError(PyInitConfig *config, const char **err_msg)¶

Get the config error message.

Set *err_msg and return 1 if an error is set.
Set *err_msg to NULL and return 0 otherwise.

An error message is an UTF-8 encoded string.

If config has an exit code, format the exit code as an error message.

The error message remains valid until another PyInitConfig function is called with config. The caller doesn’t have to free the error message.

int PyInitConfig_GetExitCode(PyInitConfig *config, int *exitcode)¶

Get the config exit code.

Set *exitcode and return 1 if config has an exit code set.
Return 0 if config has no exit code set.

Only the Py_InitializeFromInitConfig() function can set an exit code if the parse_argv option is non-zero.

An exit code can be set when parsing the command line failed (exit code 2) or when a command line option asks to display the command line help (exit code 0).

Get Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string.

int PyInitConfig_HasOption(PyInitConfig *config, const char *name)¶

Test if the configuration has an option called name.

Return 1 if the option exists, or return 0 otherwise.

int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)¶

Get an integer configuration option.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)¶

Get a string configuration option as a null-terminated UTF-8 encoded string.

Set *value, and return 0 on success.
Set an error in config and return -1 on error.

*value can be set to NULL if the option is an optional string and the option is unset.

On success, the string must be released with free(value) if it’s not NULL.

int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)¶

Get a string list configuration option as an array of null-terminated UTF-8 encoded strings.

Set *length and *value, and return 0 on success.
Set an error in config and return -1 on error.

On success, the string list must be released with PyInitConfig_FreeStrList(length, items).

void PyInitConfig_FreeStrList(size_t length, char **items)¶: Free memory of a string list created by PyInitConfig_GetStrList().

Set Options¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string.

Some configuration options have side effects on other options. This logic is only implemented when Py_InitializeFromInitConfig() is called, not by the “Set” functions below. For example, setting dev_mode to 1 does not set faulthandler to 1.

int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)¶

Set an integer configuration option.

Return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)¶

Set a string configuration option from a null-terminated UTF-8 encoded string. The string is copied.

Return 0 on success.
Set an error in config and return -1 on error.

int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char *const *items)¶

Set a string list configuration option from an array of null-terminated UTF-8 encoded strings. The string list is copied.

Return 0 on success.
Set an error in config and return -1 on error.

Module¶

int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject *(*initfunc)(void))¶

Add a built-in extension module to the table of built-in modules.

The new module can be imported by the name name, and uses the function initfunc as the initialization function called on the first attempted import.

Return 0 on success.
Set an error in config and return -1 on error.

If Python is initialized multiple times, PyInitConfig_AddModule() must be called at each Python initialization.

Similar to the PyImport_AppendInittab() function.

Initialize Python¶

int Py_InitializeFromInitConfig(PyInitConfig *config)¶

Initialize Python from the initialization configuration.

Return 0 on success.
Set an error in config and return -1 on error.
Set an exit code in config and return -1 if Python wants to exit.

See PyInitConfig_GetExitcode() for the exit code case.

Example¶

Example initializing Python, set configuration options of various types, return -1 on error:

int init_python(void)
{
    PyInitConfig *config = PyInitConfig_Create();
    if (config == NULL) {
        printf("PYTHON INIT ERROR: memory allocation failed\n");
        return -1;
    }

    // Set an integer (dev mode)
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        goto error;
    }

    // Set a list of UTF-8 strings (argv)
    char *argv[] = {"my_program", "-c", "pass"};
    if (PyInitConfig_SetStrList(config, "argv",
                                 Py_ARRAY_LENGTH(argv), argv) < 0) {
        goto error;
    }

    // Set a UTF-8 string (program name)
    if (PyInitConfig_SetStr(config, "program_name", L"my_program") < 0) {
        goto error;
    }

    // Initialize Python with the configuration
    if (Py_InitializeFromInitConfig(config) < 0) {
        goto error;
    }
    PyInitConfig_Free(config);
    return 0;

error:
    {
        // Display the error message
        // This uncommon braces style is used, because you cannot make
        // goto targets point to variable declarations.
        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);

        return -1;
    }
}

Runtime Python configuration API¶

The configuration option name parameter must be a non-NULL null-terminated UTF-8 encoded string.

Some options are read from the sys attributes. For example, the option "argv" is read from sys.argv.

PyObject *PyConfig_Get(const char *name)¶

Get the current runtime value of a configuration option as a Python object.

Return a new reference on success.
Set an exception and return NULL on error.

The object type depends on the configuration option. It can be:

bool
int
str
list[str]
dict[str, str]

The caller must hold the GIL. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

int PyConfig_GetInt(const char *name, int *value)¶

Similar to PyConfig_Get(), but get the value as a C int.

Return 0 on success.
Set an exception and return -1 on error.

Added in version 3.14.

PyObject *PyConfig_Names(void)¶

Get all configuration option names as a frozenset.

Return a new reference on success.
Set an exception and return NULL on error.

The caller must hold the GIL. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

int PyConfig_Set(const char *name, PyObject *value)¶

Set the current runtime value of a configuration option.

Raise a ValueError if there is no option name.
Raise a ValueError if value is an invalid value.
Raise a ValueError if the option is read-only (cannot be set).
Raise a TypeError if value has not the proper type.

The caller must hold the GIL. The function cannot be called before Python initialization nor after Python finalization.

Added in version 3.14.

Py_GetArgcArgv()¶

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

파이썬이 수정하기 전의, 원래 명령 줄 인자를 가져옵니다.

다단계 초기화 비공개 잠정적 API¶

This section is a private provisional API introducing multi-phase initialization, the core feature of PEP 432:

“핵심(Core)” 초기화 단계, “최소한의 파이썬”:
- 내장형;
- 내장 예외;
- 내장과 프로즌 모듈(frozen modules);
- sys 모듈은 부분적으로만 초기화됩니다 (예를 들어: sys.path는 아직 존재하지 않습니다).
“주(Main)” 초기화 단계, 파이썬이 완전히 초기화됩니다:
- importlib를 설치하고 구성합니다;
- 경로 구성을 적용합니다;
- 시그널 처리기를 설치합니다;
- sys 모듈 초기화를 완료합니다 (예를 들어: sys.stdout과 sys.path를 만듭니다);
- faulthandler와 tracemalloc과 같은 선택적 기능을 활성화합니다;
- site 모듈을 임포트 합니다;
- 등등

비공개 잠정적 API:

PyConfig._init_main: if set to 0, Py_InitializeFromConfig() stops at the “Core” initialization phase.

PyStatus _Py_InitializeMain(void)¶: “주” 초기화 단계로 이동하여, 파이썬 초기화를 완료합니다.

“핵심” 단계에서는 아무런 모듈도 임포트 하지 않고 importlib 모듈이 구성되지 않습니다: 경로 구성은 “주” 단계에서만 적용됩니다. 경로 구성을 재정의하거나 조정하기 위해 파이썬에서 파이썬을 사용자 정의할 수 있으며, 사용자 정의 sys.meta_path 임포터(importer)나 임포트 훅 등을 설치할 수 있습니다.

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.

“핵심” 단계가 제대로 정의되지 않았습니다: 이 단계에서 무엇을 사용할 수 있고, 무엇이 그렇지 않아야 하는지는 아직 지정되지 않았습니다. API는 비공개이자 잠정적인 것으로 표시됩니다: 적절한 공개 API가 설계될 때까지 언제든지 API를 수정하거나 제거할 수 있습니다.

“핵심”과 “주” 초기화 단계 사이에서 파이썬 코드를 실행하는 예제:

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);
    }
}

파이썬 초기화 구성¶

PyConfig C API¶

Example¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

Preinitialize Python with PyPreConfig¶

PyConfig¶

PyConfig를 사용한 초기화¶

격리된 구성¶

파이썬 구성¶

Python Path Configuration¶

PyInitConfig C API¶

Create Config¶

Error Handling¶

Get Options¶

Set Options¶

Module¶

Initialize Python¶

Example¶

Runtime Python configuration API¶

Py_GetArgcArgv()¶

다단계 초기화 비공개 잠정적 API¶

목차

이전 항목

다음 항목

이 페이지