Python 初期化設定¶

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_Free(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 (6): use mimalloc, a fast malloc replacement.
PYMEM_ALLOCATOR_MIMALLOC_DEBUG (7): 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 に設定されます。

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

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

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)¶: 設定のメモリを解放します。

Most PyConfig methods preinitialize Python if needed. In that case, the Python preinitialization configuration (PyPreConfig) is 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

さらに、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 base executable: sys._base_executable.

Set by the __PYVENV_LAUNCHER__ environment variable.

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。

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 *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 メンバーも参照してください。

wchar_t *filesystem_errors¶

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

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

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

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

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

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

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¶

If non-zero, profile import time.

Set the 1 by the -X importtime option and the PYTHONPROFILEIMPORTTIME environment variable.

デフォルト: 0。

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 環境変数を使います。
If the WITH_NEXT_FRAMEWORK macro is defined, use __PYVENV_LAUNCHER__ environment variable if set.
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¶

package.module path to module that should be imported before site.py is run.

Set by the -X presite=package.module command-line option and the PYTHON_PRESITE environment variable. The command-line option takes precedence.

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¶

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 PYTHON_PERF_JIT_SUPPORT environment variable for perf support with stack pointers and -X perf_jit command-line option and by the PYTHON_PERF_JIT_SUPPORT environment variable for perf support with DWARF JIT information.

デフォルト: -1。

Added in version 3.12.

int use_environment¶

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

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

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

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

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 に対応します。

The warnings module adds sys.warnoptions in the reverse order: the last PyConfig.warnoptions item becomes the first item of warnings.filters which is checked first (highest priority).

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

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

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

int write_bytecode¶

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

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

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

デフォルト: 1。

PyWideStringList xoptions¶

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

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

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_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 は解析しません)。 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 に設定します。
safe_path を 1 に設定します。

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

Py_GetArgcArgv()¶

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

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

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

Multi-Phase Initialization Private Provisional API¶

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

"Core" initialization phase, "bare minimum Python":
- Builtin types;
- Builtin exceptions;
- Builtin and frozen modules;
- The sys module is only partially initialized (ex: sys.path doesn't exist yet).
"Main" initialization phase, Python is fully initialized:
- Install and configure importlib;
- Apply the Path Configuration;
- Install signal handlers;
- Finish sys module initialization (ex: create sys.stdout and sys.path);
- Enable optional features like faulthandler and tracemalloc;
- Import the site module;
- etc.

Private provisional API:

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

PyStatus _Py_InitializeMain(void)¶: Move to the "Main" initialization phase, finish the Python initialization.

No module is imported during the "Core" phase and the importlib module is not configured: the Path Configuration is only applied during the "Main" phase. It may allow to customize Python in Python to override or tune the Path Configuration, maybe install a custom sys.meta_path importer or an import hook, etc.

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.

The "Core" phase is not properly defined: what should be and what should not be available at this phase is not specified yet. The API is marked as private and provisional: the API can be modified or even be removed anytime until a proper public API is designed.

Example running Python code between "Core" and "Main" initialization phases:

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

Python 初期化設定¶

使用例¶

PyWideStringList¶

PyStatus¶

PyPreConfig¶

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

PyConfig¶

PyConfig による初期化¶

隔離設定¶

Python 設定¶

Python のパス設定¶

Py_GetArgcArgv()¶

Multi-Phase Initialization Private Provisional API¶

目次

前のトピックへ

次のトピックへ

このページ