\chapter{ユーティリティ関数 \label{utilities}}

この章の関数は、 C で書かれたコードをプラットフォーム間で可搬性の
あるものにする上で役立つものから、C から Python モジュールを使う
もの、そして関数の引数を解釈したり、 C の値から Python の値を
構築するものまで、様々なユーティリティ的タスクを行います。


\section{オペレーティングシステム関連のユーティリティ\label{os}}

\begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, const char *filename}
\var{filename} という名前の標準 I/O ファイル \var{fp} が対話的
(interactive) であると考えられる場合に真 (非ゼロ) を返します。
これは\samp{isatty(fileno(\var{fp}))} が真になるファイルの場合です。
グローバルなフラグ \cdata{Py_InteractiveFlag} が真の場合には、
\var{filename} ポインタが \NULL{} か、名前が \code{'<stdin>'}
または \code{'???'} のいずれかに等しい場合にも真を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
ファイル \var{filename} の最終更新時刻を返します。
結果は標準 C ライブラリ関数 \cfunction{time()} が返すタイムスタンプと
同じ様式で符号化されています。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyOS_AfterFork}{}
プロセスが fork した後の内部状態を更新するための関数です;
fork 後 Python インタプリタを使い続ける場合、新たなプロセス内で
この関数を呼び出さねばなりません。新たなプロセスに新たな実行
可能物をロードする場合、この関数を呼び出す必要はありません。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyOS_CheckStack}{}
インタプリタがスタック空間を使い尽くしたときに真を返します。
このチェック関数には信頼性がありますが、\constant{USE_STACKCHECK}
が定義されている場合 (現状では Microsoft Visual \Cpp{} コンパイラ
でビルドした Windows 版) にしか利用できません . 
\constant{USE_CHECKSTACK} は自動的に定義されます; 自前のコードで
この定義を変更してはなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
シグナル \var{i} に対する現在のシグナルハンドラを返します。
この関数は \cfunction{sigaction()} または \cfunction{signal()}
のいずれかに対する薄いラッパです。
\cfunction{sigaction()} や \cfunction{signal()} を直接呼び出しては
なりません! 
\ctype{PyOS_sighandler_t} は \ctype{void (*)(int)} の typedef 
による別名です。
\end{cfuncdesc}

\begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
シグナル \var{i} に対する現在のシグナルハンドラを \var{h} に設定
します; 以前のシグナルハンドラを返します。
この関数は \cfunction{sigaction()} または \cfunction{signal()}
のいずれかに対する薄いラッパです。
\cfunction{sigaction()} や \cfunction{signal()} を直接呼び出しては
なりません! 
\ctype{PyOS_sighandler_t} は \ctype{void (*)(int)} の typedef 
による別名です。
\end{cfuncdesc}


\section{プロセス制御 \label{processControl}}

\begin{cfuncdesc}{void}{Py_FatalError}{const char *message}
致命的エラーメッセージ (fatal error message) を出力してプロセスを
強制終了 (kill) します。後始末処理は行われません。この関数は、Python 
インタプリタを使い続けるのが危険であるような状況が検出されたとき; 
例えば、オブジェクト管理が崩壊していると思われるときにのみ、呼び出され
るようにしなければなりません。\UNIX では、標準 C ライブラリ関数
\cfunction{abort()}\ttindex{abort()} を呼び出して \file{core}
を生成しようと試みます。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{Py_Exit}{int status}
現在のプロセスを終了 (exit) します。この関数は
\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} を呼び出し、
次いで標準 C ライブラリ関数
\code{exit(\var{status})}\ttindex{exit()} を呼び出します。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} から呼び出される
後始末処理を行う関数 (cleanup function) を登録します。
後始末関数は引数無しで呼び出され、値を返しません。
最大で 32 の\index{cleanup functions} 後始末処理関数を登録できます。
登録に成功すると、\cfunction{Py_AtExit()} は \code{0} を返します; 
失敗すると \code{-1} を返します。最後に登録した後始末処理関数から
先に呼び出されます。各関数は高々一度しか呼び出されません。
Python の内部的な終了処理は後始末処理関数より以前に完了している
ので、\var{func} からはいかなる Python API も呼び出してはなりません。
\end{cfuncdesc}


\section{モジュールの import \label{importing}}

\begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{const char *name}
この関数は下で述べる \cfunction{PyImport_ImportModuleEx()} 
を単純化したインタフェースで、 \var{globals} および \var{locals} 
引数を \NULL のままにしたものです。
\var{name} 引数にドットが含まれる場合 (あるパッケージの
サブモジュールを指定している場合)、\var{fromlist} 引数が
リスト \code{['*']} に追加され、戻り値がモジュールを含む
トップレベルパッケージではなく名前つきモジュール (named module) に
なるようにします。
(残念ながらこのやり方には、\var{name} が実際にはサブモジュールでなく
サブパッケージを指定している場合、パッケージの 
\code{__all__} \withsubitem{(package variable)}{\ttindex{__all__}}
\index{package variable!\code{__all__}} 変数に指定されている
サブモジュールがロードされてしまうという副作用があります。)
import されたモジュールへの新たな参照を返します。失敗した
場合には例外をセットし、\NULL{} を返します。 Python 2.4 以前では、
失敗した場合でもモジュールは生成されていることがあります --- 
\code{sys.modules} 
を使って調べてください。 Python 2.4 以降では、 import に失敗した
モジュールは \code{sys.modules} に残りません。

\versionchanged[import に失敗した場合、不完全なモジュールを除去するように
なりました]{2.4}
\withsubitem{(in module sys)}{\ttindex{modules}}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name,
                       PyObject *globals, PyObject *locals, PyObject *fromlist}
モジュールを import します。モジュールの import については
組み込みの Python 関数\function{__import__()}\bifuncindex{__import__}
を読むとよく分かります。というのも、標準の \function{__import__()} 
はこの関数を直接呼び出しているからです。

戻り値は import されたモジュールかトップレベルパッケージへの新たな参照
になります。失敗した場合には例外をセットし、\NULL{} を返します
(Python 2.4 よりも前のバージョンでは、モジュールは生成されている場合が
あります)
\function{__import__()} と同じく、パッケージに対してサブモジュール
を要求した場合の戻り値は通常、空でない \var{fromlist} を指定しない
限りトップレベルパッケージになります。
\versionchanged[import に失敗した場合、不完全なモジュールを除去するように
なりました]{2.4}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyImport_Import}{PyObject *name}
現在の ``import フック関数'' を呼び出すための高水準のインタフェース
です。この関数は現在のグローバル変数辞書内の \code{__builtins__}
から \function{__import__()} 関数を呼び出します。
すなわち、現在の環境にインストールされている import フック、
例えば \module{rexec}\refstmodindex{rexec} や
\module{ihooks}\refstmodindex{ihooks} を使って
import を行います。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyImport_ReloadModule}{PyObject *m}
モジュールを再ロード (reload) します。モジュールの再ロードについては
組み込みの Python 関数\function{reload()}\bifuncindex{reload}
を読むとよく分かります。というのも、標準の \function{reload} 
はこの関数を直接呼び出しているからです。
戻り値は再ロードしたモジュールかトップレベルパッケージへの新たな参照
になります。失敗した場合には例外をセットし、\NULL{} を返します
(その場合でも、モジュールは生成されている場合があります)
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyImport_AddModule}{const char *name}
モジュール名に対応するモジュールオブジェクトを返します。
\var{name} 引数は \code{package.module} の形式でもかまいません。
まずモジュール辞書に該当するモジュールがあるかどうか調べ、
なければ新たなモジュールを生成してモジュール辞書に挿入します。
失敗した場合には例外をセットして \NULL{} を返します。
\note{この関数はモジュールの import やロードを行いません;
モジュールがまだロードされていなければ、空のモジュール
オブジェクトを得ることになります。
\cfunction{PyImport_ImportModule()} やその別形式を使って
モジュールを import してください。ドット名表記で
指定した\var{name} が存在しない場合、パッケージ構造は
作成されません。}

\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyImport_ExecCodeModule}{char *name, PyObject *co}
モジュール名 (\code{package.module} 形式でもかまいません) および
Python のバイトコードファイルや組み込み関数 \function{compile()}
\bifuncindex{compile} で得られたコードオブジェクトを元にモジュールを
ロードします。
モジュールオブジェクトへの新たな参照を返します。失敗した
場合には例外をセットし、\NULL{} を返します。Python 2.4 以前では、
失敗した場合でもモジュールは生成されていることがありました。
Python 2.4 以降では、たとえ\cfunction{PyImport_ExecCodeModule()} の処理に
入った時に\var{name} が \code{sys.modules} に入っていたとしても、
import に失敗したモジュールは \code{sys.modules} に残りません。
初期化の不完全なモジュールを \code{sys.modules} に残すのは危険
であり、そのようなモジュールを import するコードにとっては、モジュール
の状態がわからない (モジュール作者の意図から外れた壊れた状態かもしれない)
からです。

この関数は、すでに import されているモジュールの場合には再ロードを
行います。意図的にモジュールの再ロードを行う方法は
\cfunction{PyImport_ReloadModule()} を参照してください。

\var{name} が\code{package.module} 形式のドット名表記で
あった場合、まだ作成されていないパッケージ構造はその作成されない
ままになります。

\versionchanged[エラーが発生した場合に\var{name} を\code{sys.modules} から除去するようになりました]{2.4}
\end{cfuncdesc}

\begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
Python バイトコードファイル (いわゆる \file{.pyc} および \file{.pyo}
ファイル) のマジックナンバを返します。マジックナンバは
バイトコードファイルの先頭 4 バイトにリトルエンディアン整列で
配置されています。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
モジュール管理のための辞書 (いわゆる \code{sys.modules} )を返します。
この辞書はインタプリタごとに一つだけある変数なので注意してください。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{_PyImport_Init}{}
import 機構を初期化します。
内部使用だけのための関数です。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyImport_Cleanup}{}
モジュールテーブルを空にします。
内部使用だけのための関数です。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{_PyImport_Fini}{}
import 機構を終了処理します。
内部使用だけのための関数です。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{_PyImport_FindExtension}{char *, char *}
内部使用だけのための関数です。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{_PyImport_FixupExtension}{char *, char *}
内部使用だけのための関数です。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
\var{name} という名前のフリーズ (freeze) されたモジュールをロード
します。成功すると \code{1} を、モジュールが見つからなかった場合には
\code{0} を、初期化が失敗した場合には例外をセットして\code{-1} を
返します。ロードに成功したモジュールにアクセスするには
\cfunction{PyImport_ImportModule()} を使ってください。
(Note この関数名はいささか誤称めいています --- この関数は
すでに import 済みのモジュールをリロードしてしまいます。)
\end{cfuncdesc}

\begin{ctypedesc}[_frozen]{struct _frozen}
\program{freeze}\index{freeze utility} ユーティリティが生成するような
フリーズ化モジュールデスクリプタの構造体型定義です。
(Python ソース配布物の \file{Tools/freeze/} を参照してください)
この構造体の定義は \file{Include/import.h} にあり、以下のように
なっています:

\begin{verbatim}
struct _frozen {
    char *name;
    unsigned char *code;
    int size;
};
\end{verbatim}
\end{ctypedesc}

\begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
このポインタは \ctype{struct _frozen} のレコードからなり、
終端の要素のメンバが \NULL{} かゼロになっているような配列
を指すよう初期化されます。フリーズされたモジュールを import する
とき、このテーブルを検索します。サードパーティ製のコードから
このポインタに仕掛けを講じて、動的に生成されたフリーズ化モジュールの
集合を提供するようにできます。
\end{cvardesc}

\begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
                                               void (*initfunc)(void)}
既存の組み込みモジュールテーブルに単一のモジュールを追加します。
この関数は利便性を目的とした \cfunction{PyImport_ExtendInittab()} 
のラッパ関数で、テーブルが拡張できないときには \code{-1} を返します。
新たなモジュールは \var{name} で import でき、最初に import を
試みた際に呼び出される関数として \var{initfunc} を使います。
\cfunction{Py_Initialize()} よりも前に呼び出さねばなりません。
\end{cfuncdesc}

\begin{ctypedesc}[_inittab]{struct _inittab}
組み込みモジュールリスト内の一つのエントリを記述している構造体です。
リスト内の各構造体には、インタプリタ内に組み込まれているモジュールの
名前と初期化関数が指定されています。
Python を埋め込むようなプログラムは、この構造体の配列と
\cfunction{PyImport_ExtendInittab()} を組み合わせて、追加の
組み込みモジュールを提供できます。構造体は\file{Include/import.h} 
で以下のように定義されています:

\begin{verbatim}
struct _inittab {
    char *name;
    void (*initfunc)(void);
};
\end{verbatim}
\end{ctypedesc}

\begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
組み込みモジュールのテーブルに一群のモジュールを追加します。
配列 \var{newtab} は \member{name} フィールドが \NULL{} になっている
センチネル (sentinel) エントリで終端されていなければなりません;
センチネル値を与えられなかった場合にはメモリ違反になるかもしれません。
成功すると \code{0} を、内部テーブルを拡張するのに十分なメモリを
確保できなかった場合には \code{-1} を返します。操作が失敗した場合、
モジュールは一切内部テーブルに追加されません。
  \cfunction{Py_Initialize()} よりも前に呼び出さねばなりません。
\end{cfuncdesc}


\section{データ整列化 (data marshalling) のサポート \label{marshalling-utils}}

以下のルーチン群は、\module{marshal} モジュールと同じ形式を使った
整列化オブジェクトを C コードから使えるようにします。
整列化形式でデータを書き出す関数に加えて、データを読み戻す関数
もあります。整列化されたデータを記録するファイルはバイナリモードで
開かれていなければなりません。

数値は最小桁が先にくるように記録されます。

このモジュールでは、二つのバージョンのデータ形式をサポートしています。
バージョン 0 は従来のもので、(Python 2.4 で新たに追加された) バージョン 1 
は intern 化された文字列をファイル内で共有し、逆マーシャル化の時にも
共有されるようにします。\var{PY_MARSHAL_VERSION} は現在のバージョン
(バージョン 1) を示します。 

\begin{cfuncdesc}{void}{PyMarshal_WriteLongToFile}{long value, FILE *file, int version}
\ctype{long} 型の整数値 \var{value} を \var{file} へ整列化します。
この関数は \var{value} の下桁 32 ビットを書き込むだけです;
ネイティブの \ctype{long} 型サイズには関知しません。

\versionchanged[ファイル形式を示す\var{version} が追加されました]{2.4}
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyMarshal_WriteObjectToFile}{PyObject *value,
                                                     FILE *file, int version}
Python オブジェクト\var{value} を \var{file} へ整列化します。

\versionchanged[ファイル形式を示す\var{version} が追加されました]{2.4}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyMarshal_WriteObjectToString}{PyObject *value, int version}
\var{value} の整列化表現が入った文字列オブジェクトを返します。

\versionchanged[ファイル形式を示す\var{version} が追加されました]{2.4}
\end{cfuncdesc}

以下の関数を使うと、整列化された値を読み戻せます。

% XXX What about error detection?  It appears that reading past the end
% of the file will always result in a negative numeric value (where
% that's relevant), but it's not clear that negative values won't be
% handled properly when there's no error.  What's the right way to tell?
% Should only non-negative values be written using these routines?

\begin{cfuncdesc}{long}{PyMarshal_ReadLongFromFile}{FILE *file}
読み出し用に開かれた \ctype{FILE*} 内のデータストリームから、
C の \ctype{long} 型データを読み出して返します。
この関数は、ネイティブの \ctype{long} のサイズに関係なく、
32 ビットの値だけを読み出せます。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyMarshal_ReadShortFromFile}{FILE *file}
読み出し用に開かれた \ctype{FILE*} 内のデータストリームから、
C の \ctype{short} 型データを読み出して返します。
この関数は、ネイティブの \ctype{short} のサイズに関係なく、
16 ビットの値だけを読み出せます。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromFile}{FILE *file}
読み出し用に開かれた \ctype{FILE*} 内のデータストリームから、
Python オブジェクトを読み出して返します。
エラーが生じた場合、適切な例外 (\exception{EOFError} または
\exception{TypeError}) を送出して \NULL を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadLastObjectFromFile}{FILE *file}
読み出し用に開かれた \ctype{FILE*} 内のデータストリームから、
Python オブジェクトを読み出して返します。
\cfunction{PyMarshal_ReadObjectFromFile()} と違い、この関数は
ファイル中に後続のオブジェクトが存在しないと仮定し、ファイルから
メモリ上にファイルデータを一気にメモリにロードして、逆整列化機構が
ファイルから一バイトづつ読み出す代わりにメモリ上のデータを操作
できるようにします。対象のファイルから他に何も読み出さないと
分かっている場合にのみ、この関数を使ってください。
エラーが生じた場合、適切な例外 (\exception{EOFError} または
\exception{TypeError}) を送出して \NULL を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyMarshal_ReadObjectFromString}{char *string,
                                                             Py_ssize_t len}
\var{string} が指している\var{len} バイトの文字列バッファに納められた
データストリームから Python オブジェクトを読み出して返します。
エラーが生じた場合、適切な例外 (\exception{EOFError} または
\exception{TypeError}) を送出して \NULL を返します。
\end{cfuncdesc}


\section{引数の解釈と値の構築
         \label{arg-parsing}}

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に
便利です。詳しい情報や用例は
\citetitle[../ext/ext.html]{Python インタプリタの拡張と埋め込み} に
あります。

最初に説明する 3 つの関数、
\cfunction{PyArg_ParseTuple()}、
\cfunction{PyArg_ParseTupleAndKeywords()}、および
\cfunction{PyArg_Parse()} はいずれも
\emph{書式化文字列 (format string)} を使います。
書式化文字列は、関数が受け取るはずの引数に関する情報を伝えるのに
用いられます。いずれの関数における書式化文字列も、同じ書式を
使っています。

書式化文字列は、ゼロ個またはそれ以上の ``書式化単位 (format unit)''
から成り立ちます。一つの書式化単位は一つの Python オブジェクトを
表します; 通常は単一の文字か、書式化単位からなる文字列を括弧で
囲ったものになります。例外として、括弧で囲われていない
書式化単位文字列が単一のアドレス引数に対応する場合がいくつかあります。
以下の説明では、引用符のついた形式は書式化単位です;
(丸)括弧で囲った部分は書式化単位に対応する Python のオブジェクト型
です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。

\begin{description}
  \item[\samp{s} (文字列型または Unicode オブジェクト型) {[const char *]}]
Python の文字列または Unicode オブジェクトを、キャラクタ文字列を
指す C のポインタに変換します。
変換先の文字列自体の記憶領域を提供する必要はありません;
キャラクタ型ポインタ変数のアドレスを渡すと、すでに存在している
文字列へのポインタをその変数に記録します。C 文字列は NUL で
終端されています。Python の文字列型は、NUL バイトが途中に埋め込まれて
いてはなりません; もし埋め込まれていれば\exception{TypeError} 例外を
送出します。Unicode オブジェクトはデフォルトエンコーディングを使って
C 文字列に変換されます。変換に失敗すると \exception{UnicodeError} を
送出します。

  \item[\samp{s\#} (文字列型、Unicode オブジェクト型または任意の読み出しバッファ互換型)
  {[const char *, int]}]
これは \samp{s} の変化形で、値を二つの変数に記録します。一つ目の変数は
キャラクタ文字列へのポインタで、二つ目はその長さです。
この書式化単位の場合には、Python 文字列に null バイトが埋め込まれて
いてもかまいません。 Unicode オブジェクトの場合、デフォルト
エンコーディングでの変換が可能ならば、変換したオブジェクトから文字列
へのポインタを返します。その他の読み出しバッファ互換オブジェクトは
生の内部データ表現への参照を返します。

  \item[\samp{z} (文字列型または \code{None}) {[const char *]}]
\samp{s} に似ていますが、Python オブジェクトは \code{None} でも
よく、その場合には C のポインタは \NULL にセットされます。

  \item[\samp{z\#} (文字列型、\code{None}、または任意の読み出しバッファ互換型) {[const char *, int]}]
\samp{s\#} の \samp{s} を \samp{z} にしたような意味です。

  \item[\samp{u} (Unicode オブジェクト型) {[Py_UNICODE *]}]
Python の Unicode オブジェクトを、NUL で終端された 16 ビットの
Unicode (UTF-16) データに変換します。\samp{s} と同様に、
Unicode データバッファ用に記憶領域を提供する必要はありません;
\ctype{Py_UNICODE} 型ポインタ変数のアドレスを渡すと、すでに存在している
Unicode データへのポインタをその変数に記録します。

  \item[\samp{u\#} (Unicode オブジェクト型) {[Py_UNICODE *, int]}]
これは \samp{u} の変化形で、値を二つの変数に記録します。一つ目の変数は
Unicode データバッファへのポインタで、二つ目はその長さです。
非 Unicode のオブジェクトの場合、読み出しバッファのポインタを
\ctype{Py_UNICODE} 型シーケンスへのポインタと解釈して扱います。

  \item[\samp{es} (文字列型、Unicode オブジェクト型または任意の読み出しバッファ互換型){[const char *encoding, char **buffer]}]
これは \samp{s} の変化形で、Unicode オブジェクトや Unicode に
変換可能なオブジェクトをキャラクタ型バッファにエンコードするために
用いられます。NUL バイトが埋め込まれていない文字列でのみ動作します。

この書式化単位には二つの引数が必要です。一つ目は入力にのみ用いられ、
NUL で終端されたエンコード名文字列を指す \ctype{const char*} 型で
なければなりません。指定したエンコード名を Python が理解できない
場合には例外を送出します。第二の引数は \ctype{char**} でなければ
なりません; この引数が参照しているポインタの値は、引数に指定した
テキストの内容が入ったバッファへのポインタになります。
テキストは最初の引数に指定したエンコード方式でエンコードされます。

\cfunction{PyArg_ParseTuple()} を使うと、必要なサイズのバッファを
確保し、そのバッファにエンコード後のデータをコピーして、
\var{*buffer} がこの新たに確保された記憶領域を指すように変更します。
呼び出し側には、確保されたバッファを使い終わった後に
\cfunction{PyMem_Free()} で解放する責任があります。

  \item[\samp{et} (文字列型、Unicode オブジェクト型または文字列バッファ互換型) {[const char *encoding, char **buffer]}]
\samp{es} と同じです。ただし、8 ビット幅の文字列オブジェクトを
エンコードし直さずに渡します。その代わり、実装では文字列オブジェクトが
パラメタに渡したエンコードを使っているものと仮定します。

  \item[\samp{es\#} (文字列型、Unicode オブジェクト型または文字列バッファ互換型) {[const char *encoding, char **buffer, int *buffer_length]}]
\samp{s\#} の変化形で、Unicode オブジェクトや Unicode に
変換可能なオブジェクトをキャラクタ型バッファにエンコードするために
用いられます。\samp{es} 書式化単位と違って、この変化形はバイトが埋め込まれて
いてもかまいません。 

この書式化単位には三つの引数が必要です。一つ目は入力にのみ用いられ、
NUL で終端されたエンコード名文字列を指す \ctype{const char*} 型か
\NULL でなければなりません。\NULL の場合にはデフォルトエンコーディング
を使います。指定したエンコード名を Python が理解できない
場合には例外を送出します。第二の引数は \ctype{char**} でなければ
なりません; この引数が参照しているポインタの値は、引数に指定した
テキストの内容が入ったバッファへのポインタになります。
テキストは最初の引数に指定したエンコード方式でエンコードされます。
第三の引数は整数へのポインタでなければなりません; ポインタが参照
している整数の値は出力バッファ内のバイト数にセットされます。

この書式化単位の処理には二つのモードがあります:

\var{*buffer} が\NULL{} ポインタを指している場合、関数は
必要なサイズのバッファを確保し、そのバッファにエンコード後の
データをコピーして、\var{*buffer} がこの新たに確保された
記憶領域を指すように変更します。
呼び出し側には、確保されたバッファを使い終わった後に
\cfunction{PyMem_Free()} で解放する責任があります。

\var{*buffer} が非 \NULL{} のポインタ (すでにメモリ確保済みの
バッファ) を指している場合、\cfunction{PyArg_ParseTuple()} 
はこのメモリ位置をバッファとして用い、\var{*buffer_length} 
の初期値をバッファサイズとして用います。\cfunction{PyArg_ParseTuple()} 
は次にエンコード済みのデータをバッファにコピーして、NUL で終端
します。バッファの大きさが足りなければ \exception{ValueError} 
がセットされます。

どちらの場合も、 \var{*buffer_length} は終端の NUL バイトを
含まないエンコード済みデータの長さにセットされます。

  \item[\samp{et\#} (文字列型、Unicode オブジェクト型または文字列バッファ互換型) {[const char *encoding, char **buffer]}]
\samp{es\#} と同じです。ただし、文字列オブジェクトを
エンコードし直さずに渡します。その代わり、実装では文字列オブジェクトが
パラメタに渡したエンコードを使っているものと仮定します。

  \item[\samp{b} (整数型) {[char]}]
Python の整数型を、 C の \ctype{char} 型の小さな整数に変換します。

  \item[\samp{B} (整数型) {[unsigned char]}]
Python の整数型を、オーバフローチェックを行わずに、 C の 
\ctype{unsigned char} 型の小さな整数に変換します。\versionadded{2.3}

  \item[\samp{h} (整数型) {[short int]}]
Python の整数型を、 C の \ctype{short int} 型に変換します。

  \item[\samp{H} (整数型) {[unsigned short int]}]
Python の整数型を、オーバフローチェックを行わずに、 C の 
\ctype{unsigned short int} 型に変換します。\versionadded{2.3}

  \item[\samp{i} (整数型) {[int]}]
Python の整数型を、 C の \ctype{int} 型に変換します。

  \item[\samp{I} (整数型) {[unsigned int]}]
Python の整数型を、オーバフローチェックを行わずに、 C の 
\ctype{unsigned int} 型に変換します。\versionadded{2.3}

  \item[\samp{l} (整数型) {[long int]}]
Python の整数型を、 C の \ctype{long int} 型に変換します。

  \item[\samp{k} (整数型) {[unsigned long]}]
Python の整数型もしくは長整数型を、オーバフローチェックを行わずに、 C の 
\ctype{unsigned long int} 型に変換します。\versionadded{2.3}

  \item[\samp{L} (整数型) {[PY_LONG_LONG]}]
Python の整数型を、 C の \ctype{long long} 型に変換します。
この書式化単位は、\ctype{long long} 型 (または Windows の 
\ctype{_int64} 型) がサポートされているプラットフォームでのみ
利用できます。
  Convert a Python integer to a C \ctype{long long}.  This format is
  only available on platforms that support \ctype{long long} (or
  \ctype{_int64} on Windows).

  \item[\samp{K} (整数型) {[unsigned PY_LONG_LONG]}]
Python の整数型もしくは長整数型を、オーバフローチェックを行わずに、 C の 
\ctype{unsigned long long} 型に変換します。
この書式化単位は、\ctype{unsigned long long} 型 (または Windows の 
\ctype{unsigned _int64} 型) がサポートされているプラットフォームでのみ
利用できます。\versionadded{2.3}

  \item[\samp{n} (integer) {[Py_ssize_t]}]
Python の整数型もしくは長整数型をCの \ctype{Py_ssize_t} 型に変換します。
  \versionadded{2.5}

  \item[\samp{c} (長さ 1 の文字列型) {[char]}]
長さ 1 の文字列として表現されている Python キャラクタを
C の \ctype{char} 型に変換します。

  \item[\samp{f} (浮動小数点型) {[float]}]
Python の浮動小数点型を、 C の \ctype{float} 型に変換します。

  \item[\samp{d} (浮動小数点型) {[double]}]
Python の浮動小数点型を、 C の \ctype{double} 型に変換します。

  \item[\samp{D} (複素数型) {[Py_complex]}]
Python の複素数型を、 C の \ctype{Py_complex} 構造体に変換します。

  \item[\samp{O} (オブジェクト) {[PyObject *]}]
Python オブジェクトを (一切変換を行わずに) C の Python オブジェクト型
ポインタに保存します。これにより、C プログラムは実際のオブジェクトを
受け渡しされます。オブジェクトの参照カウントは増加しません。
保存されるポインタが \NULL になることはありません。

  \item[\samp{O!} (オブジェクト) {[\var{typeobject}, PyObject *]}]
Python オブジェクトを C の Python オブジェクト型ポインタに保存します。
\samp{O} に似ていますが、二つの C の引数をとります: 一つ目の引数は
Python の型オブジェクトへのアドレスで、二つ目の引数は
オブジェクトへのポインタが保存されている (\ctype{PyObject*} の) C の
変数へのアドレスです。Python オブジェクトが指定した型ではない場合、
\exception{TypeError} を送出します。

\item[\samp{O\&} (オブジェクト) {[\var{converter}, \var{anything}]}]
Python オブジェクトを \var{converter} 関数を介して C の変数に変換します。
二つの引数をとります: 一つ目は関数で、二つ目は (任意の型の) C 変数
へのアドレスを\ctype{void *} 型に変換したものです。
\var{converter} は以下のようにして呼び出されます:

  \var{status}\code{ = }\var{converter}\code{(}\var{object},
  \var{address}\code{);}

ここで \var{object} は変換対象の Python オブジェクトで、
\var{address} は \cfunction{PyArg_Parse*()} に渡した \ctype{void*} 
型の引数です。戻り値 \var{status} は変換に成功した際に \code{1}、
失敗した場合には \code{0} になります。変換に失敗した場合、
\var{converter} 関数は例外を送出しなくてはなりません。

  \item[\samp{S} (文字列型) {[PyStringObject *]}]
\samp{O} に似ていますが、Python オブジェクトは文字列オブジェクトで
なければなりません。
オブジェクトが文字列オブジェクトでない場合には\exception{TypeError}
を送出します。
C 変数は \ctype{PyObject*} で宣言しておいてもかまいません。

  \item[\samp{U} (Unicode 文字列型) {[PyUnicodeObject *]}]
\samp{O} に似ていますが、Python オブジェクトは Unicode オブジェクトで
なければなりません。
オブジェクトが Unicode オブジェクトでない場合には\exception{TypeError}
を送出します。
C 変数は \ctype{PyObject*} で宣言しておいてもかまいません。

  \item[\samp{t\#} (読み出し専用キャラクタバッファ) {[char *, int]}]
\samp{s\#} に似ていますが、読み出し専用バッファインタフェースを
実装している任意のオブジェクトを受理します。
\ctype{char*} 変数はバッファの最初のバイトを指すようにセットされ、
\ctype{int} はバッファの長さにセットされます。
単一セグメントからなるバッファオブジェクトだけを受理します;
それ以外の場合には \exception{TypeError} を送出します。

  \item[\samp{w} (読み書き可能なキャラクタバッファ) {[char *]}]
\samp{s} と同様ですが、読み書き可能なバッファインタフェースを
実装している任意のオブジェクトを受理します。
呼び出し側は何らかの別の手段でバッファの長さを決定するか、
あるいは\samp{w\#} を使わねばなりません。
単一セグメントからなるバッファオブジェクトだけを受理します;
それ以外の場合には \exception{TypeError} を送出します。

  \item[\samp{w\#} (読み書き可能なキャラクタバッファ) {[char *, int]}]
\samp{s\#} に似ていますが、読み書き可能なバッファインタフェースを
実装している任意のオブジェクトを受理します。
\ctype{char*} 変数はバッファの最初のバイトを指すようにセットされ、
\ctype{int} はバッファの長さにセットされます。
単一セグメントからなるバッファオブジェクトだけを受理します;
それ以外の場合には \exception{TypeError} を送出します。

  \item[\samp{(\var{items})} (タプル) {[\var{matching-items}]}]
オブジェクトは\var{items} に入っている書式化単位の数だけの長さを持つ
Python のシーケンス型でなくてはなりません。各 C 引数は \var{items} 内の
個々の書式化単位に対応づけできねばなりません。
シーケンスの書式化単位は入れ子構造にできます。

  \note{Python のバージョン 1.5.2 より以前は、この書式化指定文字列は
パラメタ列ではなく、個別のパラメタが入ったタプルでなければなりません
でした。このため、以前は \exception{TypeError} を引き起こしていたよう
なコードが現在は例外を出さずに処理されるかもしれません。
とはいえ、既存のコードにとってこれは問題ないと思われます。}
\end{description}

Python 整数型を要求している場所に Python 長整数型を渡すのは
可能です; しかしながら、適切な値域チェックはまったく行われません ---
値を受け取るためのフィールドが、値全てを受け取るには小さすぎる
場合、上桁のビット群は暗黙のうちに切り詰められます (実際のところ、
このセマンティクスは C のダウンキャスト (downcast) から継承して
います --- その恩恵は人それぞれかもしれませんが)。

その他、書式化文字列において意味を持つ文字がいくつかあります。
それらの文字は括弧による入れ子内には使えません。以下に文字を
示します:

\begin{description}
  \item[\samp{|}]
Python 引数リスト中で、この文字以降の引数がオプションであることを
示します。
オプションの引数に対応する C の変数はデフォルトの値で初期化して
おかねばなりません --- オプションの引数が省略された場合、
\cfunction{PyArg_ParseTuple()} は対応する C 変数の内容に
手を加えません。

  \item[\samp{:}]
この文字があると、書式化単位の記述はそこで終わります;
コロン以降の文字列は、エラーメッセージにおける関数名
(\cfunction{PyArg_ParseTuple()} が送出する例外の
``付属値 (associated value)'') として使われます。

  \item[\samp{;}]
この文字があると、書式化単位の記述はそこで終わります;
セミコロン以降の文字列は、デフォルトエラーメッセージを
\emph{置き換える} エラーメッセージとして使われます。
言うまでもなく、\samp{:} と \samp{;} は相互に排他の文字です。
\end{description}

呼び出し側に提供される Python オブジェクトの参照は全て 
\emph{借りた (borrowed)} ものです; オブジェクトの参照カウントを
デクリメントしてはなりません!

以下の関数に渡す補助引数 (additional argument) は、書式化文字列から
決定される型へのアドレスでなければなりません; 補助引数に指定した
アドレスは、タプルから入力された値を保存するために使います。
上の書式化単位のリストで説明したように、補助引数を入力値として
使う場合がいくつかあります; その場合、対応する書式化単位
の指定する形式に従うようにせねばなりません。

変換を正しく行うためには、\var{arg} オブジェクトは
書式化文字に一致しなければならず、かつ書式化文字列内の
書式化単位に全て値が入るようにせねばなりません。
成功すると、\cfunction{PyArg_Parse*()} 関数は真を返します。
それ以外の場合には偽を返し、適切な例外を送出します。

\begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, const char *format,
                                         \moreargs}
固定引数のみを引数にとる関数のパラメタを解釈して、ローカルな
変数に変換します。
成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArg_VaParse}{PyObject *args, const char *format,
                                         va_list vargs}
\cfunction{PyArg_ParseTuple()} と同じですが、可変長の引数では
なく \var{va_list} を引数にとります。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
                       PyObject *kw, const char *format, char *keywords[],
                       \moreargs}
固定引数およびキーワード引数をとる関数のパラメタを解釈して、ローカルな
変数に変換します。
成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArg_VaParseTupleAndKeywords}{PyObject *args,
                       PyObject *kw, const char *format, char *keywords[],
                       va_list vargs}
\cfunction{PyArg_ParseTupleAndKeywords()} と同じですが、可変長の引数では
なく \var{va_list} を引数にとります。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, const char *format,
                                    \moreargs}
``旧スタイル'' の関数における引数リストを分析するために使われる
関数です --- 旧スタイルの関数は、引数解釈手法に
\constant{METH_OLDARGS} を使います。
新たに書かれるコードでのパラメタ解釈にはこの関数の使用は奨められず、
標準のインタプリタにおけるほとんどのコードがもはや引数解釈の
ためにこの関数を使わないように変更済みです。
この関数を残しているのは、この関数が依然として引数以外のタプルを
分析する上で便利だからですが、この目的においては将来も使われ
つづけるかもしれません。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyArg_UnpackTuple}{PyObject *args, const char *name,
                                          Py_ssize_t min, Py_ssize_t max, \moreargs}
パラメータ取得を簡単にした形式で、引数の型を指定する書式化文字列を
使いません。
パラメタの取得にこの手法を使う関数は、関数宣言テーブル、またはメソッド
宣言テーブル内で\constant{METH_VARARGS} として宣言しなくては
なりません。
実引数の入ったタプルは \var{args} に渡します;
このタプルは本当のタプルでなくてはなりません。
タプルの長さは少なくとも \var{min} で、\var{max} を超えてはなりません;
\var{min} と \var{max} が等しくてもかまいません。
補助引数を関数に渡さなくてはならず、各補助引数は\ctype{PyObject*} 
変数へのポインタでなくてはなりません; これらの補助引数には、
\var{args} の値が入ります; 値の参照は借りた参照です。
オプションのパラメタに対応する変数のうち、\var{args} に指定していない
ものには値が入りません; 呼び出し側はそれらの値を初期化しておかねば
なりません。
この関数は成功すると真を返し、\var{args} がタプルでない場合や
間違った数の要素が入っている場合に偽を返します; 何らかの失敗が
起きた場合には例外をセットします。

この関数の使用例を以下に示します。この例は、弱参照のための
\module{_weakref} 補助モジュールのソースコードからとったものです:

\begin{verbatim}
static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}
\end{verbatim}

この例における\cfunction{PyArg_UnpackTuple()} 呼び出しは、
\cfunction{PyArg_ParseTuple()} を使った以下の呼び出し:

\begin{verbatim}
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
\end{verbatim}

と全く等価です。

  \versionadded{2.2}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{Py_BuildValue}{const char *format,
                                            \moreargs}
\cfunction{PyArg_Parse*()} ファミリの関数が受け取るのと似た
形式の書式化文字列および値列に基づいて、新たな値を生成します。
生成した値を返します。エラーの場合には\NULL{} を返します;
\NULL{} を返す場合、例外を送出するでしょう。

\cfunction{Py_BuildValue()} は常にタプルを生成するとは限りません。
この関数がタプルを生成するのは、書式化文字列に二つ以上の書式化単位
が入っているときだけです。書式化文字列が空の場合、\code{None} 
を返します; 書式化単位が厳密に一つだけ入っている場合、
書式化単位で指定されている何らかのオブジェクト単体を返します。
サイズがゼロや 1 のタプルを返すように強制するには、
丸括弧で囲われた書式化文字列を使います。

書式化単位 \samp{s} や \samp{s\#} の場合のように、オブジェクトを
構築する際にデータを供給するためにメモリバッファをパラメタとして渡す
場合には、指定したデータはコピーされます。\cfunction{Py_BuildValue()}
が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照
しません。
別の言い方をすれば、\cfunction{malloc()} を呼び出してメモリを確保し、
それを \cfunction{Py_BuildValue()} に渡した場合、コード内で
\cfunction{Py_BuildValue()} が返った後で\cfunction{free()} を
呼び出す責任があるということです。

以下の説明では、引用符のついた形式は書式化単位です;
(丸)括弧で囲った部分は書式化単位が返す Python のオブジェクト型
です; [角] 括弧は関数に渡す値の C 変数型です。

書式化文字列内では、(\samp{s\#} のような書式化単位を除いて) スペース、
タブ、コロンおよびコンマは無視されます。
これらの文字を使うと、長い書式化文字列をちょっとだけ読みやすく
できます。

  \begin{description}
    \item[\samp{s} (文字列型) {[char *]}]
null 終端された C 文字列から Python オブジェクトに変換します。
C 文字列ポインタが \NULL の場合、 \code{None} になります。

    \item[\samp{s\#} (文字列型) {[char *, int]}]
C 文字列とその長さから Python オブジェクトに変換します。
C 文字列ポインタが \NULL の場合、長さは無視され \code{None} になります。

    \item[\samp{z} (string or \code{None}) {[char *]}]
    \samp{s} と同じです。

    \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
    \samp{s\#} と同じです。

    \item[\samp{u} (Unicode string) {[Py_UNICODE *]}]
null 終端された Unicode (UCS-2 または UCS-4) データのバッファから
Python オブジェクトに変換します。
Unicode バッファポインタが \NULL の場合、 \code{None} になります。

    \item[\samp{u\#} (Unicode string) {[Py_UNICODE *, int]}]
null 終端された Unicode (UCS-2 または UCS-4) データのバッファと
その長さから Python オブジェクトに変換します。
Unicode バッファポインタが \NULL の場合、長さは無視され
\code{None} になります。

    \item[\samp{i} (整数型) {[int]}]
通常の C の \ctype{int} を Python の整数オブジェクトに変換します。

    \item[\samp{b} (整数型) {[char]}]
    \samp{i} と同じです。
通常のC の \ctype{char} を Python の整数オブジェクトに変換します。

    \item[\samp{h} (整数型) {[short int]}]
通常のC の \ctype{short int} を Python の整数オブジェクトに変換します。

    \item[\samp{l} (整数型) {[long int]}]
C の \ctype{long int} を Python の整数オブジェクトに変換します。

    \item[\samp{B} (integer) {[unsigned char]}]
C の \ctype{unsigned char} を Python の整数オブジェクトに変換します。

    \item[\samp{H} (integer) {[unsigned short int]}]
C の \ctype{unsigned short int} を Python の整数オブジェクトに変換します。

    \item[\samp{I} (integer/long) {[unsigned int]}]
C の \ctype{unsigned int} を Python の整数オブジェクト、あるいは、値が \code{sys.maxint} 
より大きければ長整数オブジェクトに変換します。

    \item[\samp{k} (integer/long) {[unsigned long]}]
C の \ctype{unsigned long} を Python の整数オブジェクト、あるいは、値が \code{sys.maxint} 
より大きければ長整数オブジェクトに変換します。

    \item[\samp{L} (long) {[PY_LONG_LONG]}]
C の \ctype{long long} を Python の長整数オブジェクトに変換します。
\ctype{long long} をサポートしているプラットフォームでのみ利用可能です。

    \item[\samp{K} (long) {[unsigned PY_LONG_LONG]}]
C の \ctype{unsigned long long} を Python の長整数オブジェクトに変換します。
\ctype{long long} をサポートしているプラットフォームでのみ利用可能です。

    \item[\samp{n} (int) {[Py_ssize_t]}]
C の \ctype{unsigned long} を Python の整数オブジェクト、あるいは
長整数オブジェクトに変換します。
    \versionadded{2.5}

    \item[\samp{c} (string of length 1) {[char]}]
文字を表す通常の C の \ctype{int} を、長さ 1 の Python の文字列
オブジェクトに変換します。

    \item[\samp{d} (浮動小数点型) {[double]}]
C の \ctype{double} を Python の浮動小数点数に変換します。

    \item[\samp{f} (浮動小数点型) {[float]}]
    \samp{d} と同じです。

    \item[\samp{D} (複素数型) {[Py_complex *]}]
C の \ctype{Py_complex} 構造体を Python の複素数に変換します。

    \item[\samp{O} (オブジェクト) {[PyObject *]}]
Python オブジェクトを手を加えずに渡します (ただし、参照カウントは
1 インクリメントします)。渡したオブジェクトが \NULL{} ポインタ
の場合、この引数を生成するのに使った何らかの呼び出しがエラーに
なったのが原因であると仮定して、例外をセットします。
従ってこのとき \cfunction{Py_BuildValue()} は \NULL{} を返しますが
\cfunction{Py_BuildValue()} 自体は例外を送出しません。
例外をまだ送出していなければ\exception{SystemError} をセットします。

    \item[\samp{S} (オブジェクト) {[PyObject *]}]
    \samp{O} と同じです。

    \item[\samp{N} (オブジェクト) {[PyObject *]}]
    \samp{O} と同じです。ただし、オブジェクトの参照カウントを
インクリメントしません。オブジェクトが引数リスト内のオブジェクト
コンストラクタ呼び出しによって生成されている場合に便利です。

    \item[\samp{O\&} (オブジェクト) {[\var{converter}, \var{anything}]}]
\var{anything} を \var{converter} 関数を介して Python オブジェクトに
変換します。この関数は \var{anything}  (\ctype{void *} と互換の型で
なければなりません) を引数にして呼び出され、``新たな'' オブジェクト
を返すか、失敗した場合には \NULL{} を返すようにしなければなりません。

    \item[\samp{(\var{items})} (タプル型) {[\var{matching-items}]}]
C の値からなる配列を、同じ要素数を持つ Python のタプルに変換します。

    \item[\samp{[\var{items}]} (リスト型) {[\var{matching-items}]}]
C の値からなる配列を、同じ要素数を持つ Python のリストに変換します。

    \item[\samp{\{\var{items}\}} (辞書型) {[\var{matching-items}]}]
C の値からなる配列を Python の辞書に変換します。一連のペアからなる
C の値が、それぞれキーおよび値となって辞書に追加されます。

  \end{description}

書式化文字列に関するエラーが生じると、\exception{SystemError} 例外を
セットして \NULL{} を返します。
\end{cfuncdesc}
