Python 初期化設定¶

PyInitConfig C API¶

Added in version 3.14.

Python は Py_InitializeFromInitConfig() で初期化できます。

Py_RunMain() 関数は、カスタマイズされた Python プログラムを書くために使用できます。

Initialization, Finalization, and Threads も参照してください。

参考

PEP 741 "Python Configuration C API".

使用例¶

常に Python 開発モードが有効化された状態で実行されるカスタマイズされた Python の例。エラー時は -1 を返します:

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

    // Python 開発モードを有効化
    if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
        goto error;
    }

    // Python を設定付きで初期化
    if (Py_InitializeFromInitConfig(config) < 0) {
        goto error;
    }
    PyInitConfig_Free(config);
    return 0;

error:
    {
        // エラーメッセージを表示する。
        //
        // この稀な括弧スタイルは、変数宣言を指す goto ターゲットを
        // 作ることができないために使用されています。

        const char *err_msg;
        (void)PyInitConfig_GetError(config, &err_msg);
        printf("PYTHON INIT ERROR: %s\n", err_msg);
        PyInitConfig_Free(config);
        return -1;
    }
}

設定の作成¶

struct PyInitConfig¶: Python の初期化を構成するための不透明な構造体です。

PyInitConfig *PyInitConfig_Create(void)¶

隔離設定のデフォルト値を使って、新しい初期化設定を作成します。

PyInitConfig_Free() で解放しなければなりません。

メモリの確保に失敗した場合は NULL を返します。

void PyInitConfig_Free(PyInitConfig *config)¶

初期化設定 config のメモリを解放します。

config が NULL の場合は、何も行いません。

エラー処理¶

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

config のエラーメッセージを取得します。

エラーが設定されていれば、*err_msg を設定して 1 を返します。
それ以外の場合は、*err_msg を NULL に設定して 0 を返します。

エラーメッセージは、UTF-8 でエンコードされた文字列です。

config に終了コードがある場合は、その終了コードをエラーメッセージの形式にします。

エラーメッセージは、config を使って別の PyInitConfig 関数を呼び出すまで有効です。呼び出し元がエラーメッセージを解放する必要はありません。

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

config の終了コードを取得します。

config に終了コードが設定されていれば、*exitcode を設定して 1 を返します。
config に終了コードが設定されていなければ 0 を返します。

終了コードを設定できるのは、parse_argv オプションがゼロ以外の場合の Py_InitializeFromInitConfig() 関数だけです。

コマンドラインの解析に失敗した場合 (終了コード 2) や、コマンドラインオプションでヘルプの表示が要求された場合 (終了コード 0) に、終了コードが設定されることがあります。

オプションの取得¶

設定オプションの name 引数は、NULL でない、null 終端の UTF-8 エンコード文字列でなければなりません。設定オプションを参照してください。

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

設定に name というオプションがあるかを調べます。

オプションがあれば 1、なければ 0 を返します。

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

整数の設定オプションを取得します。

成功時は *value を設定し、0 を返します。
エラー時は config にエラーを設定し、-1 を返します。

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

文字列の設定オプションを、null 終端の UTF-8 エンコード文字列として取得します。

成功時は *value を設定し、0 を返します。
エラー時は config にエラーを設定し、-1 を返します。

オプションが省略可能な文字列で、設定されていない場合は、*value が NULL に設定されることがあります。

成功時に取得した文字列が NULL でなければ、呼び出し元で free(value) を使って解放しなければなりません。

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

文字列リストの設定オプションを、null 終端の UTF-8 エンコード文字列の配列として取得します。

Set *length and *value, and return 0 on success.
エラー時は config にエラーを設定し、-1 を返します。

成功時は、PyInitConfig_FreeStrList(length, items) で文字列リストを解放しなければなりません。

void PyInitConfig_FreeStrList(size_t length, char **items)¶: PyInitConfig_GetStrList() で作成した文字列リストのメモリを解放します。

オプションの設定¶

設定オプションの name 引数は、NULL でない、null 終端の UTF-8 エンコード文字列でなければなりません。設定オプションを参照してください。

一部の設定オプションは、ほかのオプションに影響します。この処理は Py_InitializeFromInitConfig() の呼び出し時にのみ行われ、以下の設定関数では行われません。例えば、dev_mode を 1 に設定しても、faulthandler は 1 になりません。

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

整数の設定オプションを設定します。

成功時は 0 を返します。
エラー時は config にエラーを設定し、-1 を返します。

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

文字列の設定オプションを、null 終端の UTF-8 エンコード文字列で設定します。文字列はコピーされます。

成功時は 0 を返します。
エラー時は config にエラーを設定し、-1 を返します。

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

文字列リストの設定オプションを、null 終端の UTF-8 エンコード文字列の配列で設定します。文字列リストはコピーされます。

成功時は 0 を返します。
エラー時は config にエラーを設定し、-1 を返します。

モジュール¶

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

組み込みモジュールのテーブルに、組み込みの拡張モジュールを追加します。

新しいモジュールは name という名前でインポートでき、最初のインポートの試行時に呼び出す初期化関数として initfunc を使います。

成功時は 0 を返します。
エラー時は config にエラーを設定し、-1 を返します。

Python を複数回初期化する場合は、初期化のたびに PyInitConfig_AddModule() を呼び出さなければなりません。

PyImport_AppendInittab() 関数と同様です。

Python の初期化¶

int Py_InitializeFromInitConfig(PyInitConfig *config)¶

初期化設定から Python を初期化します。

成功時は 0 を返します。
エラー時は config にエラーを設定し、-1 を返します。
Python が終了を要求する場合は、config に終了コードを設定して -1 を返します。

終了コードが設定された場合については、PyInitConfig_GetExitcode() を参照してください。

設定オプション¶

オプション	PyConfig/PyPreConfig のメンバー	型	可視性
`"allocator"`	`allocator`	`int`	読み出し専用
`"argv"`	`argv`	`list[str]`	公開
`"base_exec_prefix"`	`base_exec_prefix`	`str`	公開
`"base_executable"`	`base_executable`	`str`	公開
`"base_prefix"`	`base_prefix`	`str`	公開
`"buffered_stdio"`	`buffered_stdio`	`bool`	読み出し専用
`"bytes_warning"`	`bytes_warning`	`int`	公開
`"check_hash_pycs_mode"`	`check_hash_pycs_mode`	`str`	読み出し専用
`"code_debug_ranges"`	`code_debug_ranges`	`bool`	読み出し専用
`"coerce_c_locale"`	`coerce_c_locale`	`bool`	読み出し専用
`"coerce_c_locale_warn"`	`coerce_c_locale_warn`	`bool`	読み出し専用
`"configure_c_stdio"`	`configure_c_stdio`	`bool`	読み出し専用
`"configure_locale"`	`configure_locale`	`bool`	読み出し専用
`"cpu_count"`	`cpu_count`	`int`	公開
`"dev_mode"`	`dev_mode`	`bool`	読み出し専用
`"dump_refs"`	`dump_refs`	`bool`	読み出し専用
`"dump_refs_file"`	`dump_refs_file`	`str`	読み出し専用
`"exec_prefix"`	`exec_prefix`	`str`	公開
`"executable"`	`executable`	`str`	公開
`"faulthandler"`	`faulthandler`	`bool`	読み出し専用
`"filesystem_encoding"`	`filesystem_encoding`	`str`	読み出し専用
`"filesystem_errors"`	`filesystem_errors`	`str`	読み出し専用
`"hash_seed"`	`hash_seed`	`int`	読み出し専用
`"home"`	`home`	`str`	読み出し専用
`"import_time"`	`import_time`	`int`	読み出し専用
`"inspect"`	`inspect`	`bool`	公開
`"install_signal_handlers"`	`install_signal_handlers`	`bool`	読み出し専用
`"int_max_str_digits"`	`int_max_str_digits`	`int`	公開
`"interactive"`	`interactive`	`bool`	公開
`"isolated"`	`isolated`	`bool`	読み出し専用
`"legacy_windows_fs_encoding"`	`legacy_windows_fs_encoding`	`bool`	読み出し専用
`"legacy_windows_stdio"`	`legacy_windows_stdio`	`bool`	読み出し専用
`"malloc_stats"`	`malloc_stats`	`bool`	読み出し専用
`"module_search_paths"`	`module_search_paths`	`list[str]`	公開
`"optimization_level"`	`optimization_level`	`int`	公開
`"orig_argv"`	`orig_argv`	`list[str]`	読み出し専用
`"parse_argv"`	`parse_argv`	`bool`	読み出し専用
`"parser_debug"`	`parser_debug`	`bool`	公開
`"pathconfig_warnings"`	`pathconfig_warnings`	`bool`	読み出し専用
`"perf_profiling"`	`perf_profiling`	`bool`	読み出し専用
`"platlibdir"`	`platlibdir`	`str`	公開
`"prefix"`	`prefix`	`str`	公開
`"program_name"`	`program_name`	`str`	読み出し専用
`"pycache_prefix"`	`pycache_prefix`	`str`	公開
`"quiet"`	`quiet`	`bool`	公開
`"run_command"`	`run_command`	`str`	読み出し専用
`"run_filename"`	`run_filename`	`str`	読み出し専用
`"run_module"`	`run_module`	`str`	読み出し専用
`"run_presite"`	`run_presite`	`str`	読み出し専用
`"safe_path"`	`safe_path`	`bool`	読み出し専用
`"show_ref_count"`	`show_ref_count`	`bool`	読み出し専用
`"site_import"`	`site_import`	`bool`	読み出し専用
`"skip_source_first_line"`	`skip_source_first_line`	`bool`	読み出し専用
`"stdio_encoding"`	`stdio_encoding`	`str`	読み出し専用
`"stdio_errors"`	`stdio_errors`	`str`	読み出し専用
`"stdlib_dir"`	`stdlib_dir`	`str`	公開
`"tracemalloc"`	`tracemalloc`	`int`	読み出し専用
`"use_environment"`	`use_environment`	`bool`	公開
`"use_frozen_modules"`	`use_frozen_modules`	`bool`	読み出し専用
`"use_hash_seed"`	`use_hash_seed`	`bool`	読み出し専用
`"use_system_logger"`	`use_system_logger`	`bool`	読み出し専用
`"user_site_directory"`	`user_site_directory`	`bool`	読み出し専用
`"utf8_mode"`	`utf8_mode`	`bool`	読み出し専用
`"verbose"`	`verbose`	`int`	公開
`"warn_default_encoding"`	`warn_default_encoding`	`bool`	読み出し専用
`"warnoptions"`	`warnoptions`	`list[str]`	公開
`"write_bytecode"`	`write_bytecode`	`bool`	公開
`"xoptions"`	`xoptions`	`dict[str, str]`	公開
`"_pystats"`	`_pystats`	`bool`	読み出し専用

可視性:

公開: PyConfig_Get() で取得でき、PyConfig_Set() で設定できます。
読み取り専用: PyConfig_Get() で取得できますが、PyConfig_Set() では設定できません。

実行時の Python 設定 API¶

実行時には、PyConfig_Get() と PyConfig_Set() を使って設定オプションを取得・設定できます。

設定オプションの name 引数は、NULL でない、null 終端の UTF-8 エンコード文字列でなければなりません。設定オプションを参照してください。

一部のオプションは sys の属性から読み取ります。例えば、"argv" オプションは sys.argv から読み取ります。

PyObject *PyConfig_Get(const char *name)¶

設定オプションの現在の実行時の値を、Python オブジェクトとして取得します。

成功時は新しい参照を返します。
エラー時は例外を設定して NULL を返します。

オブジェクトの型は設定オプションによって異なり、次のいずれかになります。

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

呼び出し元にはスレッド状態がアタッチされていなければなりません。 Python の初期化前や終了処理後には呼び出せません。

Added in version 3.14.

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

PyConfig_Get() と同様ですが、値を C の int として取得します。

成功時は 0 を返します。
エラー時は例外を設定して -1 を返します。

Added in version 3.14.

PyObject *PyConfig_Names(void)¶

すべての設定オプションの名前を frozenset として取得します。

成功時は新しい参照を返します。
エラー時は例外を設定して NULL を返します。

呼び出し元にはスレッド状態がアタッチされていなければなりません。 Python の初期化前や終了処理後には呼び出せません。

Added in version 3.14.

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

設定オプションの現在の実行時の値を設定します。

name というオプションがなければ ValueError を送出します。
value が無効な値の場合は ValueError を送出します。
オプションが読み取り専用で設定できない場合は ValueError を送出します。
value の型が正しくない場合は TypeError を送出します。

呼び出し元にはスレッド状態がアタッチされていなければなりません。 Python の初期化前や終了処理後には呼び出せません。

引数 name、value を指定して、監査イベント cpython.PyConfig_Set を送出します。

Added in version 3.14.

バージョン 3.15 で変更: sys.flags をその場で変更するのではなく、新しいオブジェクトを作成して sys.flags を置き換えるようになりました。

PyConfig C API¶

Added in version 3.8.

Pythonは Py_InitializeFromConfig() と PyConfig 構造体を使って初期化できます。Py_PreInitialize() と PyPreConfig 構造体によって事前に初期化できます。

設定には二つの種類があります:

Python Configuration は、通常の Python と同じ振る舞いをするカスタマイズされた Python を構築するために使用されます。例えば、環境変数やコマンドライン引数がPythonを設定するために使用されます。
隔離設定は、Python をアプリケーションに組み込むために使えます。 Python をシステムから隔離します。例えば、環境変数を無視し、LC_CTYPE ロケールを変更せず、シグナルハンドラーを登録しません。

Py_RunMain() 関数は、カスタマイズされた Python プログラムを書くために使用できます。

Initialization, Finalization, and Threads も参照してください。

参考

PEP 587 "Python 初期化設定"

使用例¶

常に隔離モードで実行するようカスタマイズした Python の例です。

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

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

    /* コマンドライン引数をデコードする。
       Python を暗黙に事前初期化する (隔離モード)。 */
    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;
    }
    /* エラーメッセージを表示し、ゼロ以外の終了コードで
       プロセスを終了する */
    Py_ExitStatusException(status);
}

PyWideStringList¶

type PyWideStringList¶

wchar_t* 文字列のリスト。

length が非ゼロの場合は、items は非 NULL かつすべての文字列は非 NULL でなければなりません。

メソッド:

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

item を list に追加します。

呼び出す前に、Python を事前初期化しておく必要があります。

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

item を list の index の位置に挿入します。

index が list の長さ以上の場合、item を list の末尾に追加します。

index は 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)¶: 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_RawFree(ptr);
    return 0;
}

PyPreConfig¶

type PyPreConfig¶

Python の事前初期化に使う構造体です。

事前設定を初期化する関数:

void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)¶: Python 設定で事前設定を初期化します。

void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)¶: 隔離設定で事前設定を初期化します。

構造体フィールド:

int allocator¶

Python のメモリアロケーターの名前:

PYMEM_ALLOCATOR_NOT_SET (0): メモリアロケーターを変更せず、デフォルトを使います。
PYMEM_ALLOCATOR_DEFAULT (1): デフォルトのメモリアロケーター。
PYMEM_ALLOCATOR_DEBUG (2): デフォルトのメモリアロケーターにデバッグフックを付けます。
PYMEM_ALLOCATOR_MALLOC (3): C ライブラリの malloc() を使います。
PYMEM_ALLOCATOR_MALLOC_DEBUG (4): デバッグフック付きの malloc() の使用を強制します。
PYMEM_ALLOCATOR_PYMALLOC (5): Python の pymalloc メモリアロケーター。
PYMEM_ALLOCATOR_PYMALLOC_DEBUG (6): Python の pymalloc メモリアロケーターにデバッグフックを付けます。
PYMEM_ALLOCATOR_MIMALLOC (7): use mimalloc, a fast malloc replacement.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (8): use mimalloc, a fast malloc replacement with debug hooks.

Python を --without-pymalloc で構成した 場合、PYMEM_ALLOCATOR_PYMALLOC と PYMEM_ALLOCATOR_PYMALLOC_DEBUG はサポートされません。

Python を --without-mimalloc で構成した 場合や、必要なアトミック操作を利用できない場合、PYMEM_ALLOCATOR_MIMALLOC と PYMEM_ALLOCATOR_MIMALLOC_DEBUG はサポートされません。

メモリ管理を参照してください。

デフォルト: PYMEM_ALLOCATOR_NOT_SET。

int configure_locale¶

LC_CTYPE ロケールを、ユーザーが選択したロケールに設定します。

0 の場合、coerce_c_locale と coerce_c_locale_warn メンバーを 0 に設定します。

ロケールエンコーディングを参照してください。

デフォルト: Python 設定では 1、隔離設定では 0。

int coerce_c_locale¶

2 の場合、C ロケールを置き換えます。

1 の場合、LC_CTYPE ロケールを調べ、置き換える必要があるかを判断します。

ロケールエンコーディングを参照してください。

デフォルト: Python 設定では -1、隔離設定では 0。

int coerce_c_locale_warn¶

ゼロ以外の場合、C ロケールを置き換えたときに警告を出します。

デフォルト: Python 設定では -1、隔離設定では 0。

int dev_mode¶

Python 開発モード。 PyConfig.dev_mode を参照してください。

デフォルト: Python モードでは -1、隔離モードでは 0。

int isolated¶

隔離モード。 PyConfig.isolated を参照してください。

デフォルト: Python モードでは 0、隔離モードでは 1。

int legacy_windows_fs_encoding¶

ゼロ以外の場合:

PyPreConfig.utf8_mode を 0 に設定します。
PyConfig.filesystem_encoding を "mbcs" に設定します。
PyConfig.filesystem_errors を "replace" に設定します。

PYTHONLEGACYWINDOWSFSENCODING 環境変数の値から初期化されます。

Windows でのみ利用できます。 Windows 固有のコードには、#ifdef MS_WINDOWS マクロを使えます。

デフォルト: 0。

int parse_argv¶

ゼロ以外の場合、Py_PreInitializeFromArgs() と Py_PreInitializeFromBytesArgs() は、通常の Python がコマンドライン引数を解析するのと同じように argv 引数を解析します。コマンドライン引数を参照してください。

デフォルト: Python 設定では 1、隔離設定では 0。

int use_environment¶

環境変数を使うかどうか。 PyConfig.use_environment を参照してください。

デフォルト: Python 設定では 1、隔離設定では 0。

int utf8_mode¶

ゼロ以外の場合、Python UTF-8 モードを有効にします。

-X utf8 コマンドラインオプションと PYTHONUTF8 環境変数によって、0 または 1 に設定されます。

デフォルト: 1。

PyPreConfig による Python の事前初期化¶

Python の事前初期化では、次の処理を行います。

Python のメモリアロケーターを設定する (PyPreConfig.allocator)
LC_CTYPE ロケールを設定する (ロケールエンコーディング)
Python UTF-8 モードを設定する (PyPreConfig.utf8_mode)

現在の事前設定 (PyPreConfig 型) は、_PyRuntime.preconfig に保存されています。

Python を事前初期化する関数:

PyStatus Py_PreInitialize(const PyPreConfig *preconfig)¶

事前設定 preconfig から Python を事前初期化します。

preconfig は NULL であってはなりません。

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

事前設定 preconfig から Python を事前初期化します。

preconfig の parse_argv がゼロ以外の場合、コマンドライン引数 argv (バイト文字列) を解析します。

preconfig は NULL であってはなりません。

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

事前設定 preconfig から Python を事前初期化します。

preconfig の parse_argv がゼロ以外の場合、コマンドライン引数 argv (ワイド文字列) を解析します。

preconfig は NULL であってはなりません。

呼び出し元は、PyStatus_Exception() と Py_ExitStatusException() を使って、エラーまたは終了の状態を処理する責任があります。

Python 設定 (PyPreConfig_InitPythonConfig()) で、コマンドライン引数を使って Python を初期化する場合は、事前初期化にもそのコマンドライン引数を渡さなければなりません。エンコーディングなどの事前設定に影響するためです。例えば、-X utf8 コマンドラインオプションは Python UTF-8 モードを有効にします。

カスタムのメモリアロケーターを設定するには、Py_PreInitialize() の後、Py_InitializeFromConfig() の前に PyMem_SetAllocator() を呼び出せます。 PyPreConfig.allocator が PYMEM_ALLOCATOR_NOT_SET に設定されている場合は、Py_PreInitialize() より前にも呼び出せます。

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

/* この時点で Python は UTF-8 を使う */

Py_Initialize();
/* ... ここで Python API を使う ... */
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 の設定をすべて読み込みます。

すでに初期化されているフィールドは変更しません。

Python 3.11 以降、この関数を呼び出してもパス設定のフィールドは計算・変更されません。

PyConfig_Read() は PyConfig.argv の引数を一度しか解析しません。解析後には PyConfig.parse_argv を 2 に設定します。 Python 自体への引数は PyConfig.argv から取り除かれるため、二度解析するとアプリケーションのオプションを Python のオプションとして解析してしまいます。

必要なら Python を事前初期化します。

バージョン 3.10 で変更: PyConfig.argv の引数は一度だけ解析され、解析後は PyConfig.parse_argv が 2 に設定されるようになりました。また、PyConfig.parse_argv が 1 の場合にのみ引数を解析するようになりました。

バージョン 3.11 で変更: PyConfig_Read() は、すべてのパスを計算しなくなりました。そのため、Python のパス設定に挙げたフィールドは、Py_InitializeFromConfig() を呼び出すまで更新されない場合があります。

void PyConfig_Clear(PyConfig *config)¶: 設定のメモリを解放します。

PyConfig のメソッドの多くは、必要に応じて Python を事前初期化します。この場合、Python の事前初期化設定 (PyPreConfig) は PyConfig に基づいて作成されます。 PyPreConfig と共通の以下のフィールドを調整する場合は、PyConfig のメソッドを呼び出す前に設定しなければなりません。

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

さらに、PyConfig_SetArgv() または PyConfig_SetBytesArgv() を使う場合は、ほかのメソッドより先に呼び出さなければなりません。 parse_argv がゼロ以外の場合、事前初期化設定がコマンドライン引数に依存するためです。

これらのメソッドの呼び出し元は、PyStatus_Exception() と Py_ExitStatusException() を使って、エラーまたは終了の状態を処理する責任があります。

構造体フィールド:

PyWideStringList argv¶

argv に基づいて、sys.argv のコマンドライン引数を設定します。これらはプログラムの main() 関数に渡す引数と似ていますが、最初の要素は Python インタープリタを組み込む実行ファイルではなく、実行するスクリプトファイルを指す点が異なります。実行するスクリプトがなければ、argv の最初の要素は空文字列でも構いません。

parse_argv を 1 に設定すると、通常の Python がコマンドライン引数を解析するのと同じように argv を解析し、Python 自体への引数を argv から取り除きます。

argv が空の場合は、sys.argv が常に存在し、空にならないよう、空文字列を 1 つ追加します。

デフォルト: NULL。

orig_argv メンバーも参照してください。

int safe_path¶

ゼロの場合、Py_RunMain() は起動時に、安全でない可能性があるパスを sys.path の先頭に追加します。

argv[0] が L"-m" の場合 (python -m module)、現在の作業ディレクトリを先頭に追加します。
スクリプトを実行する場合 (python script.py)、スクリプトのディレクトリを先頭に追加します。シンボリックリンクの場合は、リンクを解決します。
それ以外の場合 (python -c code と python)、現在の作業ディレクトリを意味する空文字列を先頭に追加します。

-P コマンドラインオプションと PYTHONSAFEPATH 環境変数によって 1 に設定されます。

デフォルト: Python 設定では 0、隔離設定では 1。

Added in version 3.11.

wchar_t *base_exec_prefix¶

sys.base_exec_prefix.

デフォルト: NULL。

Python のパス設定の出力の一部です。

PyConfig.exec_prefix も参照してください。

wchar_t *base_executable¶

Python の基となる実行ファイル: sys._base_executable。

__PYVENV_LAUNCHER__ 環境変数によって設定されます。

NULL の場合は PyConfig.executable から設定されます。

デフォルト: NULL。

Python のパス設定の出力の一部です。

PyConfig.executable も参照してください。

wchar_t *base_prefix¶

sys.base_prefix.

デフォルト: NULL。

Python のパス設定の出力の一部です。

PyConfig.prefix も参照してください。

int buffered_stdio¶

0 で、configure_c_stdio がゼロ以外の場合、C のストリーム stdout と stderr のバッファリングを無効にします。

-u コマンドラインオプションと PYTHONUNBUFFERED 環境変数によって 0 に設定されます。

stdin は常にバッファリングモードで開かれます。

デフォルト: 1。

int bytes_warning¶

1 の場合、bytes または bytearray と str の比較、および bytes と int の比較で警告を出します。

2 以上の場合、これらの場合に BytesWarning 例外を送出します。

-b コマンドラインオプションで値が増加します。

デフォルト: 0。

バージョン 3.15 で非推奨、バージョン 3.17 で削除予定: -b と -bb オプションは、3.17 で何も行わなくなります。 bytes_warning メンバーは、3.17 で削除されます。

int warn_default_encoding¶

ゼロ以外の場合、io.TextIOWrapper がデフォルトのエンコーディングを使うときに EncodingWarning を出します。詳しくは EncodingWarning の有効化を参照してください。

デフォルト: 0。

Added in version 3.10.

int code_debug_ranges¶

0 の場合、コードオブジェクトに終了行と列の対応情報を含めません。トレースバックで、エラーの詳しい位置をキャレットで示す表示も無効にします。

PYTHONNODEBUGRANGES 環境変数と -X no_debug_ranges コマンドラインオプションによって 0 に設定されます。

デフォルト: 1。

Added in version 3.11.

wchar_t *check_hash_pycs_mode¶

ハッシュベースの .pyc ファイルの検証方法を制御します。 --check-hash-based-pycs コマンドラインオプションの値です。

有効な値:

L"always": check_source フラグの値にかかわらず、ソースファイルのハッシュを計算してキャッシュの有効性を確認します。
L"never": ハッシュベースの pyc は常に有効と見なします。
L"default": ハッシュベースの pyc の check_source フラグに従って、キャッシュの有効性を確認します。

デフォルト: L"default"。

PEP 552 「Deterministic pycs」も参照してください。

int configure_c_stdio¶

ゼロ以外の場合、C の標準ストリームを設定します。

Windows では、stdin、stdout、stderr をバイナリモード (O_BINARY) に設定します。
buffered_stdio がゼロの場合、stdin、stdout、stderr のバッファリングを無効にします。
interactive がゼロ以外の場合、stdin と stdout (Windows では stdout のみ) のバッファリングを有効にします。

デフォルト: Python 設定では 1、隔離設定では 0。

int dev_mode¶

ゼロ以外の場合、Python 開発モードを有効にします。

-X dev オプションと PYTHONDEVMODE 環境変数によって 1 に設定されます。

デフォルト: Python モードでは -1、隔離モードでは 0。

int dump_refs¶

Python の参照をダンプするかどうか。

ゼロ以外の場合、終了時にまだ生存しているすべてのオブジェクトをダンプします。

PYTHONDUMPREFS 環境変数によって 1 に設定されます。

Py_TRACE_REFS マクロを定義した特別な Python ビルドが必要です。 configure の --with-trace-refs オプション を参照してください。

デフォルト: 0。

wchar_t *dump_refs_file¶

Python の参照をダンプする先のファイル名。

PYTHONDUMPREFSFILE 環境変数によって設定されます。

デフォルト: NULL。

Added in version 3.11.

wchar_t *exec_prefix¶

プラットフォームに依存する Python のファイルをインストールする、サイト固有のディレクトリのプレフィックス。 sys.exec_prefix に対応します。

デフォルト: NULL。

Python のパス設定の出力の一部です。

PyConfig.base_exec_prefix も参照してください。

wchar_t *executable¶

Python インタープリタの実行ファイルの絶対パス。 sys.executable に対応します。

デフォルト: NULL。

Python のパス設定の出力の一部です。

PyConfig.base_executable も参照してください。

int faulthandler¶

faulthandler を有効にするかどうか。

ゼロ以外の場合、起動時に faulthandler.enable() を呼び出します。

-X faulthandler と PYTHONFAULTHANDLER 環境変数によって 1 に設定されます。

デフォルト: Python モードでは -1、隔離モードでは 0。

wchar_t *filesystem_encoding¶

ファイルシステムエンコーディング。 sys.getfilesystemencoding() に対応します。

macOS、Android、VxWorks: デフォルトで "utf-8" を使います。

Windows: デフォルトで "utf-8" を使います。 PyPreConfig の legacy_windows_fs_encoding がゼロ以外の場合は、"mbcs" を使います。

ほかのプラットフォームでのデフォルトのエンコーディング:

PyPreConfig.utf8_mode がゼロ以外の場合は "utf-8"。
nl_langinfo(CODESET) が ASCII エンコーディングを返すのに、mbstowcs() が別のエンコーディング (通常は Latin1) からデコードすると Python が検出した場合は "ascii"。
nl_langinfo(CODESET) が空文字列を返す場合は "utf-8"。
それ以外の場合は、nl_langinfo(CODESET) の結果であるロケールエンコーディングを使います。

Python の起動時に、エンコーディング名は Python のコーデック名に正規化されます。例えば、"ANSI_X3.4-1968" は "ascii" に置き換えられます。

filesystem_errors メンバーも参照してください。

実行時にパスをエンコードする方法については、PyUnicode_EncodeFSDefault() と関連する関数も参照してください。

wchar_t *filesystem_errors¶

ファイルシステムのエラーハンドラー。 sys.getfilesystemencodeerrors() に対応します。

Windows: デフォルトで "surrogatepass" を使います。 PyPreConfig の legacy_windows_fs_encoding がゼロ以外の場合は、"replace" を使います。

ほかのプラットフォーム: デフォルトで "surrogateescape" を使います。

サポートするエラーハンドラー:

"strict"
"surrogateescape"
"surrogatepass" (UTF-8 エンコーディングでのみサポート)

filesystem_encoding メンバーも参照してください。

int use_frozen_modules¶

ゼロ以外の場合、凍結モジュールを使います。

PYTHON_FROZEN_MODULES 環境変数によって設定されます。

デフォルト: リリースビルドでは 1、デバッグビルドでは 0。

unsigned long hash_seed¶

int use_hash_seed¶

ハッシュ関数のランダム化に使うシード。

use_hash_seed がゼロの場合、Python の起動時にシードをランダムに選び、hash_seed は無視します。

PYTHONHASHSEED 環境変数によって設定されます。

use_hash_seed のデフォルト値: Python モードでは -1、隔離モードでは 0。

wchar_t *home¶

Python の標準ライブラリの場所である、デフォルトの Python「home」ディレクトリを設定します (PYTHONHOME を参照)。

PYTHONHOME 環境変数によって設定されます。

デフォルト: NULL。

Python のパス設定の入力の一部です。

int import_time¶: 1 の場合、インポート時間を計測します。 2 の場合、インポートするモジュールがすでにロードされていることを示す出力も含めます。

-X importtime オプションと PYTHONPROFILEIMPORTTIME 環境変数によって設定されます。

デフォルト: 0。

バージョン 3.14 で変更: import_time = 2 をサポートするようになりました。

int inspect¶

スクリプトまたはコマンドの実行後に、対話モードに入ります。

0 より大きい場合、実行後の対話モードを有効にします。最初の引数にスクリプトを指定した場合や -c オプションを使った場合、sys.stdin が端末でなくても、スクリプトやコマンドの実行後に対話モードに入ります。

-i コマンドラインオプションで値が増加します。 PYTHONINSPECT 環境変数が空でなければ 1 に設定されます。

デフォルト: 0。

int install_signal_handlers¶

Python のシグナルハンドラーを登録するかどうか。

デフォルト: Python モードでは 1、隔離モードでは 0。

int interactive¶

0 より大きい場合、対話モード (REPL) を有効にします。

-i コマンドラインオプションで値が増加します。

デフォルト: 0。

int int_max_str_digits¶

整数と文字列の変換の長さ制限を設定します。初期値が -1 の場合、コマンドラインや環境変数の値を使い、それらの指定がなければデフォルトの 4300 (sys.int_info.default_max_str_digits) を使います。 0 は制限を無効にします。ゼロより大きく 640 (sys.int_info.str_digits_check_threshold) 未満の値はサポートされず、エラーになります。

-X int_max_str_digits コマンドラインフラグまたは PYTHONINTMAXSTRDIGITS 環境変数によって設定されます。

デフォルト: Python モードでは -1。隔離モードでは 4300 (sys.int_info.default_max_str_digits)。

Added in version 3.12.

int cpu_count¶

cpu_count が -1 でなければ、os.cpu_count()、os.process_cpu_count()、multiprocessing.cpu_count() の戻り値を上書きします。

-X cpu_count=n|default コマンドラインフラグまたは PYTHON_CPU_COUNT 環境変数によって設定されます。

デフォルト: -1。

Added in version 3.13.

int isolated¶

0 より大きい場合、隔離モードを有効にします。

safe_path を 1 に設定します。これにより、Python の起動時に、現在のディレクトリ、スクリプトのディレクトリ、空文字列など、安全でない可能性のあるパスを sys.path の先頭に追加しません。
use_environment を 0 に設定し、PYTHON 環境変数を無視します。
user_site_directory を 0 に設定し、ユーザーのサイトディレクトリを sys.path に追加しません。
Python の REPL は readline をインポートせず、対話プロンプトのデフォルトの readline 設定も有効にしません。

-I コマンドラインオプションによって 1 に設定されます。

デフォルト: Python モードでは 0、隔離モードでは 1。

隔離設定と PyPreConfig.isolated も参照してください。

int legacy_windows_stdio¶

ゼロ以外の場合、sys.stdin、sys.stdout、sys.stderr に io._WindowsConsoleIO の代わりに io.FileIO を使います。

PYTHONLEGACYWINDOWSSTDIO 環境変数が空でない文字列に設定された場合に、 1 に設定されます。

Windows でのみ利用できます。 Windows 固有のコードには、#ifdef MS_WINDOWS マクロを使えます。

デフォルト: 0。

PEP 528 (Change Windows console encoding to UTF-8) も参照してください。

int malloc_stats¶

ゼロ以外の場合、終了時に Python の pymalloc メモリアロケーターの統計をダンプします。

PYTHONMALLOCSTATS 環境変数によって 1 に設定されます。

Python を --without-pymalloc オプションで構成した 場合、このオプションは無視されます。

デフォルト: 0。

wchar_t *platlibdir¶

プラットフォーム固有のライブラリディレクトリの名前。 sys.platlibdir に対応します。

PYTHONPLATLIBDIR 環境変数によって設定されます。

デフォルト: configure の --with-platlibdir オプション で設定される PLATLIBDIR マクロの値 (デフォルトは "lib"、Windows では "DLLs")。

Python のパス設定の入力の一部です。

Added in version 3.9.

バージョン 3.11 で変更: このマクロは、Windows で標準ライブラリの拡張モジュールを探すために使われるようになりました。通常、拡張モジュールは DLLs にあります。ただし、互換性のため、ソースツリー内のビルドや仮想環境など、標準以外のディレクトリ配置ではこの値を無視します。

wchar_t *pythonpath_env¶

モジュール検索パス (sys.path) を、DELIM (os.pathsep) で区切った文字列。

PYTHONPATH 環境変数によって設定されます。

デフォルト: NULL。

Python のパス設定の入力の一部です。

PyWideStringList module_search_paths¶

int module_search_paths_set¶

モジュール検索パス。 sys.path に対応します。

module_search_paths_set が 0 の場合、Py_InitializeFromConfig() は module_search_paths を置き換え、module_search_paths_set を 1 に設定します。

デフォルト: module_search_paths は空のリスト、module_search_paths_set は 0。

Python のパス設定の出力の一部です。

int optimization_level¶

コンパイルの最適化レベル:

0: のぞき穴最適化を行い、__debug__ を True に設定します。
1: レベル 0 に加えて、アサーションを削除し、__debug__ を False に設定します。
2: レベル 1 に加えて、docstring を削除します。

-O コマンドラインオプションで値が増加します。 PYTHONOPTIMIZE 環境変数の値から設定されます。

デフォルト: 0。

PyWideStringList orig_argv¶

Python 実行ファイルに渡された、元のコマンドライン引数のリスト。 sys.orig_argv に対応します。

orig_argv のリストが空で、argv が空文字列だけを含むリストでない場合、PyConfig_Read() は argv を orig_argv にコピーします。これは、parse_argv がゼロ以外の場合に argv を変更する前に行われます。

argv メンバーと Py_GetArgcArgv() 関数も参照してください。

デフォルト: 空のリスト。

Added in version 3.10.

int parse_argv¶

コマンドライン引数を解析するかどうか。

1 の場合、通常の Python がコマンドライン引数を解析するのと同じように argv を解析し、Python 自体への引数を argv から取り除きます。

PyConfig_Read() は PyConfig.argv の引数を一度しか解析しません。解析後には PyConfig.parse_argv を 2 に設定します。 Python 自体への引数は PyConfig.argv から取り除かれるため、二度解析するとアプリケーションのオプションを Python のオプションとして解析してしまいます。

デフォルト: Python モードでは 1、隔離モードでは 0。

バージョン 3.10 で変更: PyConfig.argv の引数は、PyConfig.parse_argv が 1 の場合にのみ解析されるようになりました。

int parser_debug¶

パーサーのデバッグモード。 0 より大きい場合、パーサーのデバッグ出力を有効にします (専門家向けで、コンパイルオプションに依存します)。

-d コマンドラインオプションで値が増加します。 PYTHONDEBUG 環境変数の値から設定されます。

Python のデバッグビルドが必要です (Py_DEBUG マクロを定義する必要があります)。

デフォルト: 0。

int pathconfig_warnings¶

ゼロ以外の場合、パス設定の計算中に stderr に警告を出せます。 0 の場合は、これらの警告を抑制します。

デフォルト: Python モードでは 1、隔離モードでは 0。

Python のパス設定の入力の一部です。

バージョン 3.11 で変更: Windows にも適用されるようになりました。

wchar_t *prefix¶

プラットフォームに依存しない Python のファイルをインストールする、サイト固有のディレクトリのプレフィックス。 sys.prefix に対応します。

デフォルト: NULL。

Python のパス設定の出力の一部です。

PyConfig.base_prefix も参照してください。

wchar_t *program_name¶

executable の初期化と、Python の初期化の初期段階でのエラーメッセージに使うプログラム名。

macOS では、設定されていれば PYTHONEXECUTABLE 環境変数を使います。
WITH_NEXT_FRAMEWORK マクロが定義されている場合は、設定されていれば __PYVENV_LAUNCHER__ 環境変数を使います。
argv の argv[0] が存在し空でなければ、それを使います。
それ以外の場合、Windows では L"python"、ほかのプラットフォームでは L"python3" を使います。

デフォルト: NULL。

Python のパス設定の入力の一部です。

wchar_t *pycache_prefix¶

キャッシュされた .pyc ファイルを書き込むディレクトリ。 sys.pycache_prefix に対応します。

-X pycache_prefix=PATH コマンドラインオプションと PYTHONPYCACHEPREFIX 環境変数によって設定されます。コマンドラインオプションが優先されます。

NULL の場合、sys.pycache_prefix は None に設定されます。

デフォルト: NULL。

int quiet¶

静粛モード。 0 より大きい場合、対話モードでの Python の起動時に著作権とバージョンを表示しません。

-q コマンドラインオプションで値が増加します。

デフォルト: 0。

wchar_t *run_command¶

-c コマンドラインオプションの値。

Py_RunMain() が使います。

デフォルト: NULL。

wchar_t *run_filename¶

コマンドラインで渡されたファイル名。 -c や -m がない場合の、オプションの後のコマンドライン引数です。 Py_RunMain() が使います。

例えば、python3 script.py arg というコマンドラインでは script.py に設定されます。

PyConfig.skip_source_first_line オプションも参照してください。

デフォルト: NULL。

wchar_t *run_module¶

-m コマンドラインオプションの値。

Py_RunMain() が使います。

デフォルト: NULL。

wchar_t *run_presite¶

site モジュールのインポート前に実行する、module または module:func 形式のエントリーポイント。

-X presite=module:func コマンドラインオプションと PYTHON_PRESITE 環境変数によって設定されます。コマンドラインオプションが優先されます。

Python のデバッグビルドが必要です (Py_DEBUG マクロを定義する必要があります)。

デフォルト: NULL。

int show_ref_count¶

終了時に参照カウントの合計を表示するかどうか (不死オブジェクトを除く)。

-X showrefcount コマンドラインオプションによって 1 に設定されます。

Python のデバッグビルドが必要です (Py_REF_DEBUG マクロを定義する必要があります)。

デフォルト: 0。

int site_import¶

起動時に site モジュールをインポートするかどうか。

ゼロの場合、site モジュールのインポートと、それに伴うサイト固有の sys.path の操作を無効にします。

後で site モジュールを明示的にインポートしても、これらの操作は行われません。行いたい場合は site.main() を呼び出してください。

-S コマンドラインオプションによって 0 に設定されます。

sys.flags.no_site は、site_import の値を反転した値に設定されます。

デフォルト: 1。

int skip_source_first_line¶

ゼロ以外の場合、PyConfig.run_filename のソースの先頭行を読み飛ばします。

Unix 以外の形式の #!cmd を使えるようにします。 DOS 固有の回避策だけを想定したものです。

-x コマンドラインオプションによって 1 に設定されます。

デフォルト: 0。

wchar_t *stdio_encoding¶

wchar_t *stdio_errors¶

sys.stdin、sys.stdout、sys.stderr のエンコーディングとエラーハンドラー。ただし、sys.stderr は常に "backslashreplace" エラーハンドラーを使います。

PYTHONIOENCODING 環境変数が空でなければ、その値を使います。

デフォルトのエンコーディング:

PyPreConfig.utf8_mode がゼロ以外の場合は "UTF-8"。
それ以外の場合はロケールエンコーディングを使います。

デフォルトのエラーハンドラー:

Windows: "surrogateescape" を使います。
PyPreConfig.utf8_mode がゼロ以外の場合、または LC_CTYPE ロケールが "C" か "POSIX" の場合は "surrogateescape"。
それ以外の場合は "strict"。

PyConfig.legacy_windows_stdio も参照してください。

int tracemalloc¶

tracemalloc を有効にするかどうか。

ゼロ以外の場合、起動時に tracemalloc.start() を呼び出します。

-X tracemalloc=N コマンドラインオプションと PYTHONTRACEMALLOC 環境変数によって設定されます。

デフォルト: Python モードでは -1、隔離モードでは 0。

int perf_profiling¶

Linux の perf プロファイラーへの対応を有効にするかどうか。

1 の場合、Linux の perf プロファイラーへの対応を有効にします。

2 の場合、DWARF JIT に対応する方式で Linux の perf プロファイラーへの対応を有効にします。

-X perf コマンドラインオプションと PYTHONPERFSUPPORT 環境変数によって 1 に設定されます。

-X perf_jit コマンドラインオプションと PYTHON_PERF_JIT_SUPPORT 環境変数によって 2 に設定されます。

デフォルト: -1。

参考

詳しくは perf map 対応プロファイラのための Python のサポートを参照してください。

Added in version 3.12.

wchar_t *stdlib_dir¶

Python の標準ライブラリのディレクトリ。

デフォルト: NULL。

Added in version 3.11.

int use_environment¶

環境変数を使うかどうか。

ゼロの場合、環境変数を無視します。

-E コマンドラインオプションによって 0 に設定されます。

デフォルト: Python 設定では 1、隔離設定では 0。

int use_system_logger¶

ゼロ以外の場合、stdout と stderr をシステムログにリダイレクトします。

macOS 10.12 以降と iOS でのみ利用できます。

デフォルト: macOS では 0 (システムログを使わない)、iOS では 1 (システムログを使う)。

Added in version 3.14.

int user_site_directory¶

ゼロ以外の場合、ユーザーのサイトディレクトリを sys.path に追加します。

-s と -I コマンドラインオプションによって 0 に設定されます。

PYTHONNOUSERSITE 環境変数によって 0 に設定されます。

デフォルト: Python モードでは 1、隔離モードでは 0。

int verbose¶

詳細表示モード。 0 より大きい場合、モジュールをインポートするたびに、ロード元の場所 (ファイル名または組み込みモジュール) を示すメッセージを表示します。

2 以上の場合、モジュールを探す際に確認するファイルごとにメッセージを表示します。終了時のモジュールの後始末に関する情報も表示します。

-v コマンドラインオプションで値が増加します。

PYTHONVERBOSE 環境変数の値から設定されます。

デフォルト: 0。

PyWideStringList warnoptions¶

warnings モジュールが警告フィルターを作成するためのオプションで、優先度の低いものから高いものの順に並びます。 sys.warnoptions に対応します。

warnings モジュールは sys.warnoptions を逆順に追加します。そのため、PyConfig.warnoptions の最後の要素が warnings.filters の先頭になり、最初に確認されます (最も高い優先度)。

-W コマンドラインオプションは、その値を warnoptions に追加します。複数回指定できます。

PYTHONWARNINGS 環境変数でも警告オプションを追加できます。カンマ (,) で区切ることで、複数のオプションを指定できます。

デフォルト: 空のリスト。

int write_bytecode¶

0 の場合、Python はソースモジュールのインポート時に .pyc ファイルを書き込もうとしません。

-B コマンドラインオプションと PYTHONDONTWRITEBYTECODE 環境変数によって 0 に設定されます。

sys.dont_write_bytecode は、write_bytecode の値を反転した値で初期化されます。

デフォルト: 1。

PyWideStringList xoptions¶

-X コマンドラインオプションの値。 sys._xoptions に対応します。

デフォルト: 空のリスト。

int _pystats¶

ゼロ以外の場合、Python の終了時に性能統計を書き出します。

Py_STATS マクロを定義した特別なビルドが必要です。 --enable-pystats を参照してください。

デフォルト: 0。

parse_argv がゼロ以外の場合、通常の Python がコマンドライン引数を解析するのと同じように argv の引数を解析し、Python 自体への引数を argv から取り除きます。

xoptions のオプションを解析して、ほかのオプションを設定します。 -X コマンドラインオプションを参照してください。

バージョン 3.9 で変更: show_alloc_count フィールドが削除されました。

PyConfig による初期化¶

値を設定した構造体からインタープリタを初期化するには、Py_InitializeFromConfig() を呼び出します。

呼び出し元は、PyStatus_Exception() と Py_ExitStatusException() を使って、エラーまたは終了の状態を処理する責任があります。

PyImport_FrozenModules()、PyImport_AppendInittab()、PyImport_ExtendInittab() を使う場合は、Python の事前初期化の後、本初期化の前に設定または呼び出す必要があります。 Python を複数回初期化する場合は、初期化のたびに、その前に PyImport_AppendInittab() または PyImport_ExtendInittab() を呼び出さなければなりません。

現在の設定 (PyConfig 型) は、PyInterpreterState.config に保存されます。

プログラム名を設定する例です。

void init_python(void)
{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* プログラム名を設定する。
       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);
}

デフォルトの設定を変更してから設定を読み込み、さらに一部のパラメーターを上書きする、より完全な例です。 3.11 以降、多くのパラメーターは初期化するまで計算されないため、設定構造体から値を読み取れないことに注意してください。初期化関数の呼び出し前に設定された値は、初期化によって変更されません。

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_GetAttrString("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 は解析しません)。 stdout などの C の標準ストリームと LC_CTYPE ロケールは変更しません。シグナルハンドラーも登録しません。

この設定でも、指定されていないパスを決めるために設定ファイルを使います。デフォルトのパス設定の計算を避けるには、PyConfig.home を必ず指定してください。

Python 設定¶

PyPreConfig_InitPythonConfig() と PyConfig_InitPythonConfig() は、通常の Python と同じように動作する、カスタマイズされた Python を作るための設定を作成します。

Python の設定には環境変数とコマンドライン引数を使いますが、グローバルな設定変数は無視します。

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 のパス設定¶

PyConfig には、パス設定のための複数のフィールドがあります。

パス設定の入力:
- PyConfig.home
- PyConfig.platlibdir
- PyConfig.pathconfig_warnings
- PyConfig.program_name
- PyConfig.pythonpath_env
- 現在の作業ディレクトリ: 絶対パスの取得に使います。
- PATH 環境変数: PyConfig.program_name からプログラムの完全なパスを取得するために使います。
- __PYVENV_LAUNCHER__ 環境変数
- Windows のみ: レジストリの HKEY_CURRENT_USER と HKEY_LOCAL_MACHINE の "SoftwarePythonPythonCoreX.YPythonPath" にあるアプリケーションのパス (X.Y は Python のバージョン)。
パス設定の出力フィールド:

「出力フィールド」が 1 つでも未設定なら、Python はパス設定を計算して未設定のフィールドを埋めます。 module_search_paths_set が 0 の場合は、module_search_paths を上書きし、module_search_paths_set を 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 の先頭に追加します。
If isolated is zero:
- run_module が設定されている場合は、現在のディレクトリを sys.path の先頭に追加します。現在のディレクトリを取得できなければ何もしません。
- run_filename が設定されている場合は、そのファイル名のディレクトリを sys.path の先頭に追加します。
- それ以外の場合は、空文字列を sys.path の先頭に追加します。

site_import がゼロ以外の場合、site モジュールが sys.path を変更することがあります。 user_site_directory がゼロ以外で、ユーザーの site-packages ディレクトリが存在する場合は、site モジュールがそのディレクトリを sys.path の末尾に追加します。

パス設定では、以下の設定ファイルを使います。

pyvenv.cfg
._pth ファイル (例: python._pth)
pybuilddir.txt (Unix のみ)

._pth ファイルが存在する場合:

isolated を 1 に設定します。
use_environment を 0 に設定します。
site_import を 0 に設定します。
user_site_directory を 0 に設定します (3.15 以降)。
safe_path を 1 に設定します。

home が未設定で、executable と同じディレクトリか、その親ディレクトリに pyvenv.cfg ファイルがある場合、prefix と exec_prefix はその場所に設定されます。この場合も、base_prefix と base_exec_prefix は元の値を保ち、基となるインストール先を指します。詳しくは仮想環境を参照してください。

__PYVENV_LAUNCHER__ 環境変数は、PyConfig.base_executable の設定に使います。

バージョン 3.14 で変更: prefix と exec_prefix が、pyvenv.cfg のディレクトリに設定されるようになりました。以前は site が設定していたため、-S の影響を受けていました。

バージョン 3.15 で変更: ._pth ファイルが存在する場合、user_site_directory が 0 に設定されるようになりました。

Py_GetArgcArgv()¶

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

Python が変更する前の、元のコマンドライン引数を取得します。

PyConfig.orig_argv メンバーも参照してください。

多相初期化の非公開の暫定 API¶

この節では、PEP 432 の中心的な機能である多相初期化を導入する、非公開の暫定 API を説明します。

「コア」初期化フェーズ。必要最小限の Python:
- 組み込み型。
- 組み込み例外。
- 組み込みモジュールと凍結モジュール。
- sys モジュールは一部だけ初期化されます (例えば、sys.path はまだ存在しません)。
「メイン」初期化フェーズ。 Python が完全に初期化されます:
- importlib の組み込みと設定。
- パス設定の適用。
- シグナルハンドラーの登録。
- sys モジュールの初期化の完了 (例: sys.stdout と sys.path の作成)。
- faulthandler と tracemalloc などのオプション機能の有効化。
- site モジュールのインポート。
- その他。

非公開の暫定 API:

int PyConfig._init_main¶: 0 に設定すると、Py_InitializeFromConfig() は「コア」初期化フェーズで停止します。

PyStatus _Py_InitializeMain(void)¶: 「メイン」初期化フェーズに進み、Python の初期化を完了します。

「コア」フェーズでは、モジュールをインポートせず、importlib モジュールも設定しません。パス設定は「メイン」フェーズでのみ適用されます。これにより、Python コードで Python 自体をカスタマイズし、パス設定の上書きや調整、独自の sys.meta_path インポーターやインポートフックの設定などができる可能性があります。

「コア」フェーズの後、「メイン」フェーズの前に、Python でパス設定を計算できるようになる可能性があります。これは PEP 432 の動機の 1 つです。

「コア」フェーズはまだ明確に定義されておらず、この段階で何が利用でき、何が利用できないべきかは未指定です。 API は非公開かつ暫定とされているため、正式な公開 API が設計されるまでは、いつでも変更または削除される可能性があります。

「コア」と「メイン」の初期化フェーズの間で Python コードを実行する例です。

void init_python(void)
{
    PyStatus status;

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

    /* ... 'config' の設定をカスタマイズする ... */

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

    /* sys.stdout は _Py_InitializeMain() で初めて作成されるので、
       sys.stderr を使う */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) {
        exit(1);
    }

    /* ... ここに追加の設定コードを書く ... */

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

Python 初期化設定¶

PyInitConfig C API¶

使用例¶

設定の作成¶

エラー処理¶

オプションの取得¶

オプションの設定¶

モジュール¶

Python の初期化¶

設定オプション¶

実行時の Python 設定 API¶

PyConfig C API¶

使用例¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

PyPreConfig による Python の事前初期化¶

PyConfig¶

PyConfig による初期化¶

隔離設定¶

Python 設定¶

Python のパス設定¶

Py_GetArgcArgv()¶

多相初期化の非公開の暫定 API¶

目次

前のトピックへ

次のトピックへ

このページ