1. Extending Python with C or C++
*********************************

It is quite easy to add new built-in modules to Python, if you know
how to program in C.  Such *extension modules* can do two things that
can't be done directly in Python: they can implement new built-in
object types, and they can call C library functions and system calls.

To support extensions, the Python API (Application Programmers
Interface) defines a set of functions, macros and variables that
provide access to most aspects of the Python run-time system.  The
Python API is incorporated in a C source file by including the header
""Python.h"".

The compilation of an extension module depends on its intended use as
well as on your system setup; details are given in later chapters.

注釈:

  The C extension interface is specific to CPython, and extension
  modules do not work on other Python implementations.  In many cases,
  it is possible to avoid writing C extensions and preserve
  portability to other implementations. For example, if your use case
  is calling C library functions or system calls, you should consider
  using the "ctypes" module or the cffi library rather than writing
  custom C code. These modules let you write Python code to interface
  with C code and are more portable between implementations of Python
  than writing and compiling a C extension module.


1.1. A Simple Example
=====================

Let's create an extension module called "spam" (the favorite food of
Monty Python fans...) and let's say we want to create a Python
interface to the C library function "system()" [1]. This function
takes a null-terminated character string as argument and returns an
integer.  We want this function to be callable from Python as follows:

   >>> import spam
   >>> status = spam.system("ls -l")

Begin by creating a file "spammodule.c".  (Historically, if a module
is called "spam", the C file containing its implementation is called
"spammodule.c"; if the module name is very long, like "spammify", the
module name can be just "spammify.c".)

The first two lines of our file can be:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

which pulls in the Python API (you can add a comment describing the
purpose of the module and a copyright notice if you like).

注釈:

  Since Python may define some pre-processor definitions which affect
  the standard headers on some systems, you *must* include "Python.h"
  before any standard headers are included."#define PY_SSIZE_T_CLEAN"
  was used to indicate that "Py_ssize_t" should be used in some APIs
  instead of "int". It is not necessary since Python 3.13, but we keep
  it here for backward compatibility. See 文字列とバッファ for a
  description of this macro.

All user-visible symbols defined by "Python.h" have a prefix of "Py"
or "PY", except those defined in standard header files.

Tip:

  For backward compatibility, "Python.h" includes several standard
  header files. C extensions should include the standard headers that
  they use, and should not rely on these implicit includes. If using
  the limited C API version 3.13 or newer, the implicit includes are:

  * "<assert.h>"

  * "<intrin.h>" (on Windows)

  * "<inttypes.h>"

  * "<limits.h>"

  * "<math.h>"

  * "<stdarg.h>"

  * "<wchar.h>"

  * "<sys/types.h>" (if present)

  If "Py_LIMITED_API" is not defined, or is set to version 3.12 or
  older, the headers below are also included:

  * "<ctype.h>"

  * "<unistd.h>" (on POSIX)

  If "Py_LIMITED_API" is not defined, or is set to version 3.10 or
  older, the headers below are also included:

  * "<errno.h>"

  * "<stdio.h>"

  * "<stdlib.h>"

  * "<string.h>"

The next thing we add to our module file is the C function that will
be called when the Python expression "spam.system(string)" is
evaluated (we'll see shortly how it ends up being called):

   static PyObject *
   spam_system(PyObject *self, PyObject *args)
   {
       const char *command;
       int sts;

       if (!PyArg_ParseTuple(args, "s", &command))
           return NULL;
       sts = system(command);
       return PyLong_FromLong(sts);
   }

There is a straightforward translation from the argument list in
Python (for example, the single expression ""ls -l"") to the arguments
passed to the C function.  The C function always has two arguments,
conventionally named *self* and *args*.

The *self* argument points to the module object for module-level
functions; for a method it would point to the object instance.

The *args* argument will be a pointer to a Python tuple object
containing the arguments.  Each item of the tuple corresponds to an
argument in the call's argument list.  The arguments are Python
objects --- in order to do anything with them in our C function we
have to convert them to C values.  The function "PyArg_ParseTuple()"
in the Python API checks the argument types and converts them to C
values.  It uses a template string to determine the required types of
the arguments as well as the types of the C variables into which to
store the converted values.  More about this later.

"PyArg_ParseTuple()" returns true (nonzero) if all arguments have the
right type and its components have been stored in the variables whose
addresses are passed.  It returns false (zero) if an invalid argument
list was passed.  In the latter case it also raises an appropriate
exception so the calling function can return "NULL" immediately (as we
saw in the example).


1.2. Intermezzo: Errors and Exceptions
======================================

An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition
and return an error value (usually "-1" or a "NULL" pointer).
Exception information is stored in three members of the interpreter's
thread state.  These are "NULL" if there is no exception.  Otherwise
they are the C equivalents of the members of the Python tuple returned
by "sys.exc_info()".  These are the exception type, exception
instance, and a traceback object.  It is important to know about them
to understand how errors are passed around.

Python API では、様々な型の例外をセットするための関数をいくつか定義し
ています。

もっともよく用いられるのは "PyErr_SetString()" です。引数は例外オブジ
ェクトと C 文字列です。例外オブジェクトは通常、
"PyExc_ZeroDivisionError" のような定義済みのオブジェクトです。 C 文字
列はエラーの原因を示し、Python 文字列オブジェクトに変換されて例外の "
付属値" に保存されます。

もう一つ有用な関数として "PyErr_SetFromErrno()" があります。この関数は
引数に例外だけをとり、付属値はグローバル変数 "errno" から構築します。
もっとも汎用的な関数は "PyErr_SetObject()" で、二つのオブジェクト、例
外と付属値を引数にとります。これら関数に渡すオブジェクトには
"Py_INCREF()" を使う必要はありません。

例外がセットされているかどうかは、 "PyErr_Occurred()" を使って非破壊的
に調べられます。この関数は現在の例外オブジェクトを返します。例外が発生
していない場合には "NULL" を返します。通常は、関数の戻り値からエラーが
発生したかを判別できるはずなので、 "PyErr_Occurred()" を呼び出す必要は
ありません。

関数 *g* を呼び出す *f* が、前者の関数の呼び出しに失敗したことを検出す
ると、 *f* 自体はエラー値 (大抵は "NULL" や "-1") を返さねばなりません
。しかし、 "PyErr_*" 関数群のいずれかを呼び出す必要は *ありません* ---
なぜなら、 *g* がすでに呼び出しているからです。次いで *f* を呼び出した
コードもエラーを示す値を *自らを呼び出したコード* に返すことになります
が、同様に "PyErr_*" は *呼び出しません* 。以下同様に続きます --- エラ
ーの最も詳しい原因は、最初にエラーを検出した関数がすでに報告しているか
らです。エラーが Python インタプリタのメインループに到達すると、現在実
行中の Python コードは一時停止し、 Python プログラマが指定した例外ハン
ドラを探し出そうとします。

(モジュールが "PyErr_*" 関数をもう一度呼び出して、より詳細なエラーメッ
セージを提供するような状況があります。このような状況ではそうすべきです
。とはいえ、一般的な規則としては、この関数を何度も呼び出す必要はなく、
ともすればエラーの原因に関する情報を失う結果になりがちです: これにより
、ほとんどの操作が様々な理由から失敗するかもしれません)

ある関数呼び出しでの処理の失敗によってセットされた例外を無視するには、
"PyErr_Clear()" を呼び出して例外状態を明示的に消去しなくてはなりません
。エラーをインタプリタには渡したくなく、自前で (何か他の作業を行ったり
、何も起こらなかったかのように見せかけるような) エラー処理を完全に行う
場合にのみ、 "PyErr_Clear()" を呼び出すようにすべきです。

"malloc()" の呼び出し失敗は、常に例外にしなくてはなりません ---
"malloc()" (または "realloc()") を直接呼び出しているコードは、
"PyErr_NoMemory()" を呼び出して、失敗を示す値を返さねばなりません。オ
ブジェクトを生成する全ての関数 (例えば "PyLong_FromLong()") は
"PyErr_NoMemory()" の呼び出しを済ませてしまうので、この規則が関係する
のは直接 "malloc()" を呼び出すコードだけです。

また、 "PyArg_ParseTuple()" という重要な例外を除いて、整数の状態コード
を返す関数はたいてい、Unix のシステムコールと同じく、処理が成功した際
にはゼロまたは正の値を返し、失敗した場合には "-1" を返します。

最後に、エラー標示値を返す際に、(エラーが発生するまでに既に生成してし
まったオブジェクトに対して "Py_XDECREF()" や "Py_DECREF()" を呼び出し
て) ごみ処理を注意深く行ってください!

The choice of which exception to raise is entirely yours.  There are
predeclared C objects corresponding to all built-in Python exceptions,
such as "PyExc_ZeroDivisionError", which you can use directly. Of
course, you should choose exceptions wisely --- don't use
"PyExc_TypeError" to mean that a file couldn't be opened (that should
probably be "PyExc_OSError"). If something's wrong with the argument
list, the "PyArg_ParseTuple()" function usually raises
"PyExc_TypeError".  If you have an argument whose value must be in a
particular range or must satisfy other conditions, "PyExc_ValueError"
is appropriate.

You can also define a new exception that is unique to your module. The
simplest way to do this is to declare a static global object variable
at the beginning of the file:

   static PyObject *SpamError = NULL;

and initialize it by calling "PyErr_NewException()" in the module's
"Py_mod_exec" function ("spam_module_exec()"):

   SpamError = PyErr_NewException("spam.error", NULL, NULL);

Since "SpamError" is a global variable, it will be overwritten every
time the module is reinitialized, when the "Py_mod_exec" function is
called.

For now, let's avoid the issue: we will block repeated initialization
by raising an "ImportError":

   static PyObject *SpamError = NULL;

   static int
   spam_module_exec(PyObject *m)
   {
       if (SpamError != NULL) {
           PyErr_SetString(PyExc_ImportError,
                           "cannot initialize spam module more than once");
           return -1;
       }
       SpamError = PyErr_NewException("spam.error", NULL, NULL);
       if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {
           return -1;
       }

       return 0;
   }

   static PyModuleDef_Slot spam_module_slots[] = {
       {Py_mod_exec, spam_module_exec},
       {0, NULL}
   };

   static struct PyModuleDef spam_module = {
       .m_base = PyModuleDef_HEAD_INIT,
       .m_name = "spam",
       .m_size = 0,  // non-negative
       .m_slots = spam_module_slots,
   };

   PyMODINIT_FUNC
   PyInit_spam(void)
   {
       return PyModuleDef_Init(&spam_module);
   }

Note that the Python name for the exception object is "spam.error".
The "PyErr_NewException()" function may create a class with the base
class being "Exception" (unless another class is passed in instead of
"NULL"), described in 組み込み例外.

Note also that the "SpamError" variable retains a reference to the
newly created exception class; this is intentional!  Since the
exception could be removed from the module by external code, an owned
reference to the class is needed to ensure that it will not be
discarded, causing "SpamError" to become a dangling pointer. Should it
become a dangling pointer, C code which raises the exception could
cause a core dump or other unintended side effects.

For now, the "Py_DECREF()" call to remove this reference is missing.
Even when the Python interpreter shuts down, the global "SpamError"
variable will not be garbage-collected. It will "leak". We did,
however, ensure that this will happen at most once per process.

We discuss the use of "PyMODINIT_FUNC" as a function return type later
in this sample.

The "spam.error" exception can be raised in your extension module
using a call to "PyErr_SetString()" as shown below:

   static PyObject *
   spam_system(PyObject *self, PyObject *args)
   {
       const char *command;
       int sts;

       if (!PyArg_ParseTuple(args, "s", &command))
           return NULL;
       sts = system(command);
       if (sts < 0) {
           PyErr_SetString(SpamError, "System command failed");
           return NULL;
       }
       return PyLong_FromLong(sts);
   }


1.3. Back to the Example
========================

Going back to our example function, you should now be able to
understand this statement:

   if (!PyArg_ParseTuple(args, "s", &command))
       return NULL;

It returns "NULL" (the error indicator for functions returning object
pointers) if an error is detected in the argument list, relying on the
exception set by "PyArg_ParseTuple()".  Otherwise the string value of
the argument has been copied to the local variable "command".  This is
a pointer assignment and you are not supposed to modify the string to
which it points (so in Standard C, the variable "command" should
properly be declared as "const char *command").

The next statement is a call to the Unix function "system()", passing
it the string we just got from "PyArg_ParseTuple()":

   sts = system(command);

Our "spam.system()" function must return the value of "sts" as a
Python object.  This is done using the function "PyLong_FromLong()".

   return PyLong_FromLong(sts);

In this case, it will return an integer object.  (Yes, even integers
are objects on the heap in Python!)

If you have a C function that returns no useful argument (a function
returning void), the corresponding Python function must return "None".
You need this idiom to do so (which is implemented by the
"Py_RETURN_NONE" macro):

   Py_INCREF(Py_None);
   return Py_None;

"Py_None" is the C name for the special Python object "None".  It is a
genuine Python object rather than a "NULL" pointer, which means
"error" in most contexts, as we have seen.


1.4. The Module's Method Table and Initialization Function
==========================================================

I promised to show how "spam_system()" is called from Python programs.
First, we need to list its name and address in a "method table":

   static PyMethodDef spam_methods[] = {
       ...
       {"system",  spam_system, METH_VARARGS,
        "Execute a shell command."},
       ...
       {NULL, NULL, 0, NULL}        /* Sentinel */
   };

Note the third entry ("METH_VARARGS").  This is a flag telling the
interpreter the calling convention to be used for the C function.  It
should normally always be "METH_VARARGS" or "METH_VARARGS |
METH_KEYWORDS"; a value of "0" means that an obsolete variant of
"PyArg_ParseTuple()" is used.

When using only "METH_VARARGS", the function should expect the Python-
level parameters to be passed in as a tuple acceptable for parsing via
"PyArg_ParseTuple()"; more information on this function is provided
below.

The "METH_KEYWORDS" bit may be set in the third field if keyword
arguments should be passed to the function.  In this case, the C
function should accept a third "PyObject *" parameter which will be a
dictionary of keywords. Use "PyArg_ParseTupleAndKeywords()" to parse
the arguments to such a function.

The method table must be referenced in the module definition
structure:

   static struct PyModuleDef spam_module = {
       ...
       .m_methods = spam_methods,
       ...
   };

This structure, in turn, must be passed to the interpreter in the
module's initialization function.  The initialization function must be
named "PyInit_name()", where *name* is the name of the module, and
should be the only non-"static" item defined in the module file:

   PyMODINIT_FUNC
   PyInit_spam(void)
   {
       return PyModuleDef_Init(&spam_module);
   }

Note that "PyMODINIT_FUNC" declares the function as "PyObject *"
return type, declares any special linkage declarations required by the
platform, and for C++ declares the function as "extern "C"".

"PyInit_spam()" is called when each interpreter imports its module
"spam" for the first time.  (See below for comments about embedding
Python.) A pointer to the module definition must be returned via
"PyModuleDef_Init()", so that the import machinery can create the
module and store it in "sys.modules".

When embedding Python, the "PyInit_spam()" function is not called
automatically unless there's an entry in the "PyImport_Inittab" table.
To add the module to the initialization table, use
"PyImport_AppendInittab()", optionally followed by an import of the
module:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

   int
   main(int argc, char *argv[])
   {
       PyStatus status;
       PyConfig config;
       PyConfig_InitPythonConfig(&config);

       /* Add a built-in module, before Py_Initialize */
       if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
           fprintf(stderr, "Error: could not extend in-built modules table\n");
           exit(1);
       }

       /* Pass argv[0] to the Python interpreter */
       status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
       if (PyStatus_Exception(status)) {
           goto exception;
       }

       /* Initialize the Python interpreter.  Required.
          If this step fails, it will be a fatal error. */
       status = Py_InitializeFromConfig(&config);
       if (PyStatus_Exception(status)) {
           goto exception;
       }
       PyConfig_Clear(&config);

       /* Optionally import the module; alternatively,
          import can be deferred until the embedded script
          imports it. */
       PyObject *pmodule = PyImport_ImportModule("spam");
       if (!pmodule) {
           PyErr_Print();
           fprintf(stderr, "Error: could not import module 'spam'\n");
       }

       // ... use Python C API here ...

       return 0;

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

注釈:

  If you declare a global variable or a local static one, the module
  may experience unintended side-effects on re-initialisation, for
  example when removing entries from "sys.modules" or importing
  compiled modules into multiple interpreters within a process (or
  following a "fork()" without an intervening "exec()"). If module
  state is not yet fully isolated, authors should consider marking the
  module as having no support for subinterpreters (via
  "Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED").

A more substantial example module is included in the Python source
distribution as "Modules/xxlimited.c".  This file may be used as a
template or simply read as an example.


1.5. Compilation and Linkage
============================

There are two more things to do before you can use your new extension:
compiling and linking it with the Python system.  If you use dynamic
loading, the details may depend on the style of dynamic loading your
system uses; see the chapters about building extension modules
(chapter C および C++ 拡張のビルド) and additional information that
pertains only to building on Windows (chapter Windows 上での C および
C++ 拡張モジュールのビルド) for more information about this.

If you can't use dynamic loading, or if you want to make your module a
permanent part of the Python interpreter, you will have to change the
configuration setup and rebuild the interpreter.  Luckily, this is
very simple on Unix: just place your file ("spammodule.c" for example)
in the "Modules/" directory of an unpacked source distribution, add a
line to the file "Modules/Setup.local" describing your file:

   spam spammodule.o

を追加して、トップレベルのディレクトリで **make** を実行して、インタプ
リタを再ビルドするだけです。 "Modules/" サブディレクトリでも **make**
を実行できますが、前もって '**make** Makefile' を実行して "Makefile"
を再ビルドしておかなければならりません。(この作業は "Setup" ファイルを
変更するたびに必要です。)

モジュールが別のライブラリとリンクされている必要がある場合、ライブラリ
も設定ファイルに列挙できます。例えば以下のようにします。

   spam spammodule.o -lX11


1.6. C から Python 関数を呼び出す
=================================

So far we have concentrated on making C functions callable from
Python.  The reverse is also useful: calling Python functions from C.
This is especially the case for libraries that support so-called
"callback" functions.  If a C interface makes use of callbacks, the
equivalent Python often needs to provide a callback mechanism to the
Python programmer; the implementation will require calling the Python
callback functions from a C callback.  Other uses are also imaginable.

Fortunately, the Python interpreter is easily called recursively, and
there is a standard interface to call a Python function.  (If you're
interested in how to call the Python parser with a particular string
as input, see 超高水準レイヤ.)

Python 関数の呼び出しは簡単です。まず、C のコードに対してコールバック
を登録しようとする Python プログラムは、何らかの方法で Python の関数オ
ブジェクトを渡さねばなりません。このために、コールバック登録関数 (また
はその他のインターフェース) を提供せねばなりません。このコールバック登
録関数が呼び出された際に、引き渡された Python 関数オブジェクトへのポイ
ンタをグローバル変数に --- あるいは、どこか適切な場所に --- 保存します
(関数オブジェクトを "Py_INCREF()" するようよく注意してください!)。例え
ば、以下のような関数がモジュールの一部になっていることでしょう:

   static PyObject *my_callback = NULL;

   static PyObject *
   my_set_callback(PyObject *dummy, PyObject *args)
   {
       PyObject *result = NULL;
       PyObject *temp;

       if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
           if (!PyCallable_Check(temp)) {
               PyErr_SetString(PyExc_TypeError, "parameter must be callable");
               return NULL;
           }
           Py_XINCREF(temp);         /* Add a reference to new callback */
           Py_XDECREF(my_callback);  /* Dispose of previous callback */
           my_callback = temp;       /* Remember new callback */
           /* Boilerplate to return "None" */
           Py_INCREF(Py_None);
           result = Py_None;
       }
       return result;
   }

This function must be registered with the interpreter using the
"METH_VARARGS" flag; this is described in section The Module's Method
Table and Initialization Function.  The "PyArg_ParseTuple()" function
and its arguments are documented in section 拡張モジュール関数でのパラ
メタ展開.

"Py_XINCREF()" および "Py_XDECREF()" は、オブジェクトに対する参照カウ
ントをインクリメント/デクリメントするためのマクロで、 "NULL" ポインタ
が渡されても安全に操作できる形式です (とはいえ、上の流れでは *temp* が
"NULL" になることはありません)。これらのマクロと参照カウントについては
、 参照カウント法 で説明しています。

その後、コールバック関数を呼び出す時が来たら、C 関数
"PyObject_CallObject()" を呼び出します。この関数には二つの引数: Python
関数と Python 関数の引数リストがあり、いずれも任意の Python オブジェク
トを表すポインタ型です。引数リストは常にタプルオブジェクトでなければな
らず、その長さは引数の数になります。Python 関数を引数なしで呼び出すの
なら、 "NULL" か空のタプルを渡します; 単一の引数で関数を呼び出すのなら
、単要素 (singleton) のタプルを渡します。 "Py_BuildValue()" の書式文字
列中に、ゼロ個または一個以上の書式化コードが入った丸括弧がある場合、こ
の関数はタプルを返します。以下に例を示します:

   int arg;
   PyObject *arglist;
   PyObject *result;
   ...
   arg = 123;
   ...
   /* Time to call the callback */
   arglist = Py_BuildValue("(i)", arg);
   result = PyObject_CallObject(my_callback, arglist);
   Py_DECREF(arglist);

"PyObject_CallObject()" は Python オブジェクトへのポインタを返します:
これは Python 関数からの戻り値になります。 "PyObject_CallObject()" は
、引数に対して "参照カウント中立 (reference-count- neutral)" です。上
の例ではタプルを生成して引数リストとして提供しており、このタプルは
"PyObject_CallObject()" の呼び出し直後に "Py_DECREF()" されています。

"PyObject_CallObject()" は戻り値として "新しい" オブジェクト: 新規に作
成されたオブジェクトか、既存のオブジェクトの参照カウントをインクリメン
トしたものを返します。従って、このオブジェクトをグローバル変数に保存し
たいのでないかぎり、たとえこの戻り値に興味がなくても (むしろ、そうであ
ればなおさら!) 何がしかの方法で戻り値オブジェクトを "Py_DECREF()" しな
ければなりません。

とはいえ、戻り値を "Py_DECREF()" する前には、値が "NULL" でないかチェ
ックしておくことが重要です。もし "NULL" なら、呼び出した Python 関数は
例外を送出して終了させられています。 "PyObject_CallObject()" を呼び出
しているコード自体もまた Python から呼び出されているのであれば、今度は
C コードが自分を呼び出している Python コードにエラー標示値を返さねばな
りません。それにより、インタプリタはスタックトレースを出力したり、例外
を処理するための Python コードを呼び出したりできます。例外の送出が不可
能だったり、したくないのなら、 "PyErr_Clear()" を呼んで例外を消去して
おかねばなりません。例えば以下のようにします:

   if (result == NULL)
       return NULL; /* Pass error back */
   ...use result...
   Py_DECREF(result);

Python コールバック関数をどんなインターフェースにしたいかによっては、
引数リストを "PyObject_CallObject()" に与えなければならない場合もあり
ます。あるケースでは、コールバック関数を指定したのと同じインターフェー
スを介して、引数リストも渡されているかもしれません。また別のケースでは
、新しいタプルを構築して引数リストを渡さねばならないかもしれません。こ
の場合最も簡単なのは "Py_BuildValue()" を呼ぶやり方です。例えば、整数
のイベントコードを渡したければ、以下のようなコードを使うことになるでし
ょう:

   PyObject *arglist;
   ...
   arglist = Py_BuildValue("(l)", eventcode);
   result = PyObject_CallObject(my_callback, arglist);
   Py_DECREF(arglist);
   if (result == NULL)
       return NULL; /* Pass error back */
   /* Here maybe use the result */
   Py_DECREF(result);

"Py_DECREF(arglist)" が呼び出しの直後、エラーチェックよりも前に置かれ
ていることに注意してください! また、厳密に言えば、このコードは完全では
ありません: "Py_BuildValue()" はメモリ不足におちいるかもしれず、チェッ
クしておくべきです。

通常の引数とキーワード引数をサポートする "PyObject_Call()" を使って、
キーワード引数を伴う関数呼び出しをすることができます。上の例と同じよう
に、 "Py_BuildValue()" を作って辞書を作ります。

   PyObject *dict;
   ...
   dict = Py_BuildValue("{s:i}", "name", val);
   result = PyObject_Call(my_callback, NULL, dict);
   Py_DECREF(dict);
   if (result == NULL)
       return NULL; /* Pass error back */
   /* Here maybe use the result */
   Py_DECREF(result);


1.7. 拡張モジュール関数でのパラメタ展開
=======================================

The "PyArg_ParseTuple()" function is declared as follows:

   int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

引数 *arg* は C 関数から Python に渡される引数リストが入ったタプルオブ
ジェクトでなければなりません。 *format* 引数は書式文字列で、 Python/C
API リファレンスマニュアルの 引数の解釈と値の構築 で解説されている書法
に従わねばなりません。残りの引数は、それぞれの変数のアドレスで、書式化
文字列から決まる型になっていなければなりません。

"PyArg_ParseTuple()" は Python 側から与えられた引数が必要な型になって
いるか調べるのに対し、 "PyArg_ParseTuple()" は呼び出しの際に渡された C
変数のアドレスが有効な値を持つか調べられないことに注意してください: こ
こで間違いを犯すと、コードがクラッシュするかもしれませんし、少なくとも
でたらめなビットをメモリに上書きしてしまいます。慎重に!

呼び出し側に提供されるオブジェクトへの参照はすべて *借用* 参照
(borrowed reference) になります; これらのオブジェクトの参照カウントを
デクリメントしてはなりません!

以下にいくつかの呼び出し例を示します:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

   int ok;
   int i, j;
   long k, l;
   const char *s;
   Py_ssize_t size;

   ok = PyArg_ParseTuple(args, ""); /* No arguments */
       /* Python call: f() */

   ok = PyArg_ParseTuple(args, "s", &s); /* A string */
       /* Possible Python call: f('whoops!') */

   ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
       /* Possible Python call: f(1, 2, 'three') */

   ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
       /* A pair of ints and a string, whose size is also returned */
       /* Possible Python call: f((1, 2), 'three') */

   {
       const char *file;
       const char *mode = "r";
       int bufsize = 0;
       ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
       /* A string, and optionally another string and an integer */
       /* Possible Python calls:
          f('spam')
          f('spam', 'w')
          f('spam', 'wb', 100000) */
   }

   {
       int left, top, right, bottom, h, v;
       ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
                &left, &top, &right, &bottom, &h, &v);
       /* A rectangle and a point */
       /* Possible Python call:
          f(((0, 0), (400, 300)), (10, 10)) */
   }

   {
       Py_complex c;
       ok = PyArg_ParseTuple(args, "D:myfunction", &c);
       /* a complex, also providing a function name for errors */
       /* Possible Python call: myfunction(1+2j) */
   }


1.8. 拡張モジュール関数のキーワードパラメタ
===========================================

"PyArg_ParseTupleAndKeywords()" は、以下のように宣言されています:

   int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                   const char *format, char * const *kwlist, ...);

*arg* と *format* パラメタは "PyArg_ParseTuple()" のものと同じです。
*kwdict* パラメタはキーワード引数の入った辞書で、 Python ランタイムシ
ステムから第三パラメタとして受け取ります。 *kwlist* パラメタは各パラメ
タを識別するための文字列からなる、 "NULL" 終端されたリストです; 各パラ
メタ名は *format* 中の型情報に対して左から右の順に照合されます。成功す
ると "PyArg_ParseTupleAndKeywords()" は真を返し、それ以外の場合には適
切な例外を送出して偽を返します。

注釈:

  キーワード引数を使っている場合、タプルは入れ子にして使えません!
  *kwlist* 内に存在しないキーワードパラメタが渡された場合、
  "TypeError" の送出を引き起こします。

以下にキーワードを使ったモジュール例を示します。これは Geoff Philbrick
(philbrick@hks.com) によるプログラム例をもとにしています:

   #define PY_SSIZE_T_CLEAN
   #include <Python.h>

   static PyObject *
   keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
   {
       int voltage;
       const char *state = "a stiff";
       const char *action = "voom";
       const char *type = "Norwegian Blue";

       static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

       if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                        &voltage, &state, &action, &type))
           return NULL;

       printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
              action, voltage);
       printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

       Py_RETURN_NONE;
   }

   static PyMethodDef keywdarg_methods[] = {
       /* The cast of the function is necessary since PyCFunction values
        * only take two PyObject* parameters, and keywdarg_parrot() takes
        * three.
        */
       {"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
        "Print a lovely skit to standard output."},
       {NULL, NULL, 0, NULL}   /* sentinel */
   };

   static struct PyModuleDef keywdarg_module = {
       .m_base = PyModuleDef_HEAD_INIT,
       .m_name = "keywdarg",
       .m_size = 0,
       .m_methods = keywdarg_methods,
   };

   PyMODINIT_FUNC
   PyInit_keywdarg(void)
   {
       return PyModuleDef_Init(&keywdarg_module);
   }


1.9. 任意の値を構築する
=======================

"Py_BuildValue()" は "PyArg_ParseTuple()" の対極に位置するものです。こ
の関数は以下のように定義されています:

   PyObject *Py_BuildValue(const char *format, ...);

"Py_BuildValue()" は、 "PyArg_ParseTuple()" の認識する一連の書式単位に
似た書式単位を認識します。ただし (関数への出力ではなく、入力に使われる
) 引数はポインタではなく、ただの値でなければなりません。 Python から呼
び出された C 関数が返す値として適切な、新たな Python オブジェクトを返
します。

"PyArg_ParseTuple()" とは一つ違う点があります: "PyArg_ParseTuple()" は
第一引数をタプルにする必要があります (Python の引数リストは内部的には
常にタプルとして表現されるからです) が、 "Py_BuildValue()" はタプルを
生成するとは限りません。 "Py_BuildValue()" は書式文字列中に書式単位が
二つかそれ以上入っている場合にのみタプルを構築します。書式文字列が空な
ら、 "None" を返します。きっかり一つの書式単位なら、その書式単位が記述
している何らかのオブジェクトになります。サイズが 0 や 1 のタプル返させ
たいのなら、書式文字列を丸括弧で囲います。

以下に例を示します (左に呼び出し例を、右に構築される Python 値を示しま
す):

   Py_BuildValue("")                        None
   Py_BuildValue("i", 123)                  123
   Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
   Py_BuildValue("s", "hello")              'hello'
   Py_BuildValue("y", "hello")              b'hello'
   Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
   Py_BuildValue("s#", "hello", 4)          'hell'
   Py_BuildValue("y#", "hello", 4)          b'hell'
   Py_BuildValue("()")                      ()
   Py_BuildValue("(i)", 123)                (123,)
   Py_BuildValue("(ii)", 123, 456)          (123, 456)
   Py_BuildValue("(i,i)", 123, 456)         (123, 456)
   Py_BuildValue("[i,i]", 123, 456)         [123, 456]
   Py_BuildValue("{s:i,s:i}",
                 "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
   Py_BuildValue("((ii)(ii)) (ii)",
                 1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))


1.10. 参照カウント法
====================

C や C++のような言語では、プログラマはヒープ上のメモリを動的に確保した
り解放したりする責任があります。こうした作業は C では関数 "malloc()"
や "free()" で行います。C++では本質的に同じ意味で演算子 "new" や
"delete" が使われます。そこで、以下の議論は C の場合に限定して行います
。

Every block of memory allocated with "malloc()" should eventually be
returned to the pool of available memory by exactly one call to
"free()". It is important to call "free()" at the right time.  If a
block's address is forgotten but "free()" is not called for it, the
memory it occupies cannot be reused until the program terminates.
This is called a *memory leak*.  On the other hand, if a program calls
"free()" for a block and then continues to use the block, it creates a
conflict with reuse of the block through another "malloc()" call.
This is called *using freed memory*. It has the same bad consequences
as referencing uninitialized data --- core dumps, wrong results,
mysterious crashes.

よくあるメモリリークの原因はコード中の普通でない処理経路です。例えば、
ある関数があるメモリブロックを確保し、何らかの計算を行って、再度ブロッ
クを解放するとします。さて、関数の要求仕様を変更して、計算に対するテス
トを追加すると、エラー条件を検出し、関数の途中で処理を戻すようになるか
もしれません。この途中での終了が起きるとき、確保されたメモリブロックは
解放し忘れやすいのです。コードが後で追加された場合には特にそうです。こ
のようなメモリリークが一旦紛れ込んでしまうと、長い間検出されないままに
なることがよくあります: エラーによる関数の終了は、全ての関数呼び出しの
に対してほんのわずかな割合しか起きず、その一方でほとんどの近代的な計算
機は相当量の仮想記憶を持っているため、メモリリークが明らかになるのは、
長い間動作していたプロセスがリークを起こす関数を何度も使った場合に限ら
れるからです。従って、この種のエラーを最小限にとどめるようなコーディン
グ規約や戦略を設けて、不慮のメモリリークを避けることが重要なのです。

Python は "malloc()" や "free()" を非常によく利用するため、メモリリー
クの防止に加え、解放されたメモリの使用を防止する戦略が必要です。このた
めに選ばれたのが参照カウント法 (*reference counting*) と呼ばれる手法で
す。参照カウント法の原理は簡単です: 全てのオブジェクトにはカウンタがあ
り、オブジェクトに対する参照がどこかに保存されたらカウンタをインクリメ
ントし、オブジェクトに対する参照が削除されたらデクリメントします。カウ
ンタがゼロになったら、オブジェクトへの最後の参照が削除されたことになり
、オブジェクトは解放されます。

An alternative strategy is called *automatic garbage collection*.
(Sometimes, reference counting is also referred to as a garbage
collection strategy, hence the use of "automatic" to distinguish the
two.)  The big advantage of automatic garbage collection is that the
user doesn't need to call "free()" explicitly.  (Another claimed
advantage is an improvement in speed or memory usage --- this is no
hard fact however.)  The disadvantage is that for C, there is no truly
portable automatic garbage collector, while reference counting can be
implemented portably (as long as the functions "malloc()" and "free()"
are available --- which the C Standard guarantees). Maybe some day a
sufficiently portable automatic garbage collector will be available
for C. Until then, we'll have to live with reference counts.

Python では、伝統的な参照カウント法の実装を行っている一方で、参照の循
環を検出するために働く循環参照検出機構 (cycle detector) も提供していま
す。循環参照検出機構のおかげで、直接、間接にかかわらず循環参照の生成を
気にせずにアプリケーションを構築できます; というのも、参照カウント法だ
けを使ったガベージコレクション実装にとって循環参照は弱点だからです。循
環参照は、(間接参照の場合も含めて) 相互への参照が入ったオブジェクトか
ら形成されるため、循環内のオブジェクトは各々非ゼロの参照カウントを持ち
ます。典型的な参照カウント法の実装では、たとえ循環参照を形成するオブジ
ェクトに対して他に全く参照がないとしても、循環参照内のどのオブジェクト
に属するメモリも再利用できません。

循環参照検出機構はそのようなガベージサイクル (前述したような循環参照オ
ブジェクト) を検出して回収することができます。 "gc" モジュールそのよう
な検出機構の実行 ("collect()" 関数) を提供するとともに、設定のためのイ
ンタフェースおよび検出機構を実行時に無効にする方法も提供しています。


1.10.1. Python における参照カウント法
-------------------------------------

Python には、参照カウントのインクリメントやデクリメントを処理する二つ
のマクロ、 "Py_INCREF(x)" と "Py_DECREF(x)" があります。 "Py_DECREF()"
は、参照カウントがゼロに到達した際に、オブジェクトのメモリ解放も行いま
す。柔軟性を持たせるために、 "free()" を直接呼び出しません --- その代
わりにオブジェクトの型オブジェクト (*type object*) を介します。このた
めに (他の目的もありますが)、全てのオブジェクトには自身の型オブジェク
トに対するポインタが入っています。

さて、まだ重大な疑問が残っています: いつ "Py_INCREF(x)" や
"Py_DECREF(x)" を使えばよいのでしょうか? まず、いくつかの用語説明から
始めさせてください。まず、オブジェクトは "占有 (own)" されることはあり
ません; しかし、あるオブジェクトに対する参照の所有 *own a reference*
はできます。オブジェクトの参照カウントは、そのオブジェクトが参照の所有
を受けている回数と定義されています。参照の所有者は、参照が必要なくなっ
た際に "Py_DECREF()" を呼び出す役割を担います。参照の所有権は委譲
(transfer) できます。所有参照 (owned reference) の放棄には、渡す、保存
する、 "Py_DECREF()" を呼び出す、という三つの方法があります。所有参照
を処理し忘れると、メモリリークを引き起こします。

It is also possible to *borrow* [2] a reference to an object.  The
borrower of a reference should not call "Py_DECREF()".  The borrower
must not hold on to the object longer than the owner from which it was
borrowed. Using a borrowed reference after the owner has disposed of
it risks using freed memory and should be avoided completely [3].

参照の借用が参照の所有よりも優れている点は、コードがとりうるあらゆる処
理経路で参照を廃棄しておくよう注意しなくて済むことです --- 別の言い方
をすれば、借用参照の場合には、処理の途中で関数を終了してもメモリリーク
の危険を冒すことがない、ということです。逆に、所有よりも不利な点は、ご
くまともに見えるコードが、実際には参照の借用元で放棄されてしまった後に
その参照を使うかもしれないような微妙な状況があるということです。

"Py_INCREF()" を呼び出すと、借用参照を所有参照に変更できます。この操作
は参照の借用元の状態には影響しません --- "Py_INCREF()" は新たな所有参
照を生成し、参照の所有者が担うべき全ての責任を課します (つまり、新たな
参照の所有者は、以前の所有者と同様、参照の放棄を適切に行わねばなりませ
ん)。


1.10.2. 所有権にまつわる規則
----------------------------

オブジェクトへの参照を関数の内外に渡す場合には、オブジェクトの所有権が
参照と共に渡されるか否かが常に関数インターフェース仕様の一部となります
。

オブジェクトへの参照を返すほとんどの関数は、参照とともに所有権も渡しま
す。特に、 "PyLong_FromLong()" や "Py_BuildValue()" のように、新しいオ
ブジェクトを生成する関数は全て所有権を相手に渡します。オブジェクトが実
際には新たなオブジェクトでなくても、そのオブジェクトに対する新たな参照
の所有権を得ます。例えば、 "PyLong_FromLong()" はよく使う値をキャッシ
ュしており、キャッシュされた値への参照を返すことがあります。

"PyObject_GetAttrString()" のように、あるオブジェクトから別のオブジェ
クトを抽出するような関数もまた、参照とともに所有権を委譲します。こちら
の方はやや理解しにくいかもしれません。というのはよく使われるルーチンの
いくつかが例外となっているからです: "PyTuple_GetItem()" 、
"PyList_GetItem()" 、 "PyDict_GetItem()" 、および
"PyDict_GetItemString()" は全て、タプル、リスト、または辞書から借用参
照を返します。

"PyImport_AddModule()" は、実際にはオブジェクトを生成して返すことがあ
るにもかかわらず、借用参照を返します: これが可能なのは、生成されたオブ
ジェクトに対する所有参照は "sys.modules" に保持されるからです。

オブジェクトへの参照を別の関数に渡す場合、一般的には、関数側は呼び出し
手から参照を借用します --- 参照を保存する必要があるなら、関数側は
"Py_INCREF()" を呼び出して独立した所有者になります。とはいえ、この規則
には二つの重要な例外: "PyTuple_SetItem()" と "PyList_SetItem()" があり
ます。これらの関数は、渡された引数要素に対して所有権を乗っ取り (take
over) ます --- たとえ失敗してもです! ("PyDict_SetItem()" とその仲間は
所有権を乗っ取りません --- これらはいわば "普通の" 関数です。)

Python から C 関数が呼び出される際には、C 関数は呼び出し側から引数への
参照を借用します。C 関数の呼び出し側はオブジェクトへの参照を所有してい
るので、借用参照の生存期間が保証されるのは関数が処理を返すまでです。こ
のようにして借用参照を保存したり他に渡したりしたい場合にのみ、
"Py_INCREF()" を使って所有参照にする必要があります。

Python から呼び出された C 関数が返す参照は所有参照でなければなりません
--- 所有権は関数から呼び出し側へと委譲されます。


1.10.3. 薄氷
------------

数少ない状況において、一見無害に見える借用参照の利用が問題をひきおこす
ことがあります。この問題はすべて、インタプリタが非明示的に呼び出され、
インタプリタが参照の所有者に参照を放棄させてしまう状況と関係しています
。

知っておくべきケースのうち最初の、そして最も重要なものは、リスト要素に
対する参照を借りている際に起きる、関係ないオブジェクトに対する
"Py_DECREF()" の使用です。例えば:

   void
   bug(PyObject *list)
   {
       PyObject *item = PyList_GetItem(list, 0);

       PyList_SetItem(list, 1, PyLong_FromLong(0L));
       PyObject_Print(item, stdout, 0); /* BUG! */
   }

上の関数はまず、 "list[0]" への参照を借用し、次に "list[1]" を値 "0"
で置き換え、最後にさきほど借用した参照を出力しています。何も問題ないよ
うに見えますね? でもそうではないのです!

Let's follow the control flow into "PyList_SetItem()".  The list owns
references to all its items, so when item 1 is replaced, it has to
dispose of the original item 1.  Now let's suppose the original item 1
was an instance of a user-defined class, and let's further suppose
that the class defined a "__del__()" method.  If this class instance
has a reference count of 1, disposing of it will call its "__del__()"
method. Internally, "PyList_SetItem()" calls "Py_DECREF()" on the
replaced item, which invokes replaced item's corresponding
"tp_dealloc" function. During deallocation, "tp_dealloc" calls
"tp_finalize", which is mapped to the "__del__()" method for class
instances (see **PEP 442**). This entire sequence happens
synchronously within the "PyList_SetItem()" call.

Since it is written in Python, the "__del__()" method can execute
arbitrary Python code.  Could it perhaps do something to invalidate
the reference to "item" in "bug()"?  You bet!  Assuming that the list
passed into "bug()" is accessible to the "__del__()" method, it could
execute a statement to the effect of "del list[0]", and assuming this
was the last reference to that object, it would free the memory
associated with it, thereby invalidating "item".

問題の原因が分かれば、解決は簡単です。一時的に参照回数を増やせばよいの
です。正しく動作するバージョンは以下のようになります:

   void
   no_bug(PyObject *list)
   {
       PyObject *item = PyList_GetItem(list, 0);

       Py_INCREF(item);
       PyList_SetItem(list, 1, PyLong_FromLong(0L));
       PyObject_Print(item, stdout, 0);
       Py_DECREF(item);
   }

This is a true story.  An older version of Python contained variants
of this bug and someone spent a considerable amount of time in a C
debugger to figure out why his "__del__()" methods would fail...

The second case of problems with a borrowed reference is a variant
involving threads.  Normally, multiple threads in the Python
interpreter can't get in each other's way, because there is a *global
lock* protecting Python's entire object space. However, it is possible
to temporarily release this lock using the macro
"Py_BEGIN_ALLOW_THREADS", and to re-acquire it using
"Py_END_ALLOW_THREADS".  This is common around blocking I/O calls, to
let other threads use the processor while waiting for the I/O to
complete. Obviously, the following function has the same problem as
the previous one:

   void
   bug(PyObject *list)
   {
       PyObject *item = PyList_GetItem(list, 0);
       Py_BEGIN_ALLOW_THREADS
       ...some blocking I/O call...
       Py_END_ALLOW_THREADS
       PyObject_Print(item, stdout, 0); /* BUG! */
   }


1.10.4. NULL ポインタ
---------------------

一般論として、オブジェクトへの参照を引数にとる関数はユーザが "NULL" ポ
インタを渡すとは予想しておらず、渡そうとするとコアダンプになる (か、あ
とでコアダンプを引き起こす) ことでしょう。一方、オブジェクトへの参照を
返すような関数は一般に、例外の発生を示す場合にのみ "NULL" を返します。
引数に対して "NULL" テストを行わない理由は、関数はしばしば受け取ったオ
ブジェクトを他の関数へと引き渡すからです --- 各々の関数が "NULL" テス
トを行えば、冗長なテストが大量に行われ、コードはより低速に動くことにな
ります。

従って、 "NULL" のテストはオブジェクトの "発生源"、すなわち値が "NULL"
になるかもしれないポインタを受け取ったときだけにしましょう。
"malloc()" や、例外を送出する可能性のある関数がその例です。

マクロ "Py_INCREF()" および "Py_DECREF()" は "NULL" ポインタのチェック
を行いません --- しかし、これらのマクロの変化形である "Py_XINCREF()"
および "Py_XDECREF()" はチェックを行います。

特定のオブジェクト型について調べるマクロ ("Pytype_Check()") は *NULL*
ポインタのチェックを行いません --- 繰り返しますが、様々な異なる型を想
定してオブジェクトの型を調べる際には、こうしたマクロを続けて呼び出す必
要があるので、個別に "NULL" ポインタのチェックをすると冗長なテストにな
ってしまうのです。型を調べるマクロには、 "NULL" チェックを行う変化形は
ありません。

The C function calling mechanism guarantees that the argument list
passed to C functions ("args" in the examples) is never "NULL" --- in
fact it guarantees that it is always a tuple [4].

"NULL" ポインタを Python ユーザレベルに "逃がし" てしまうと、深刻なエ
ラーを引き起こします。


1.11. C++での拡張モジュール作成
===============================

C++でも拡張モジュールは作成できます。ただしいくつか制限があります。メ
インプログラム (Python インタプリタ) は C コンパイラでコンパイルされリ
ンクされているので、グローバル変数や静的オブジェクトをコンストラクタで
作成できません。メインプログラムが C++ コンパイラでリンクされているな
らこれは問題ではありません。 Python インタプリタから呼び出される関数 (
特にモジュール初期化関数) は、 "extern "C"" を使って宣言しなければなり
ません。また、Python ヘッダファイルを "extern "C" {...}" に入れる必要
はありません--- シンボル "__cplusplus" (最近の C++ コンパイラは全てこ
のシンボルを定義しています) が定義されているときに "extern "C" {...}"
が行われるように、ヘッダファイル内にすでに書かれているからです。


1.12. 拡張モジュールに C API を提供する
=======================================

多くの拡張モジュールは単に Python から使える新たな関数や型を提供するだ
けですが、時に拡張モジュール内のコードが他の拡張モジュールでも便利なこ
とがあります。例えば、あるモジュールでは順序概念のないリストのように動
作する "コレクション (collection)" クラスを実装しているかもしれません
。ちょうどリストを生成したり操作したりできる C API を備えた標準の
Python リスト型のように、この新たなコレクション型も他の拡張モジュール
から直接操作できるようにするには一連の C 関数を持っていなければなりま
せん。

一見するとこれは簡単なこと: 単に関数を (もちろん "static" などとは宣言
せずに) 書いて、適切なヘッダファイルを提供し、C API を書けばよいだけ、
に思えます。そして実際のところ、全ての拡張モジュールが Python インタプ
リタに常に静的にリンクされている場合にはうまく動作します。ところがモジ
ュールが共有ライブラリの場合には、一つのモジュールで定義されているシン
ボルが他のモジュールから不可視なことがあります。可視性の詳細はオペレー
ティングシステムによります; あるシステムは Python インタプリタと全ての
拡張モジュール用に単一のグローバルな名前空間を用意しています (例えば
Windows)。別のシステムはモジュールのリンク時に取り込まれるシンボルを明
示的に指定する必要があります (AIX がその一例です)、また別のシステム (
ほとんどの Unix) では、違った戦略を選択肢として提供しています。そして
、たとえシンボルがグローバル変数として可視であっても、呼び出したい関数
の入ったモジュールがまだロードされていないことだってあります!

Portability therefore requires not to make any assumptions about
symbol visibility. This means that all symbols in extension modules
should be declared "static", except for the module's initialization
function, in order to avoid name clashes with other extension modules
(as discussed in section The Module's Method Table and Initialization
Function). And it means that symbols that *should* be accessible from
other extension modules must be exported in a different way.

Python はある拡張モジュールの C レベルの情報 (ポインタ) を別のモジュー
ルに渡すための特殊な機構: Capsule (カプセル)を提供しています。 Capsule
はポインタ (void*) を記憶する Python のデータ型です。 Capsule は C API
を介してのみ生成したりアクセスしたりできますが、他の Python オブジェク
トと同じように受け渡しできます。とりわけ、Capsule は拡張モジュールの名
前空間内にある名前に代入できます。他の拡張モジュールはこのモジュールを
import でき、次に名前を取得し、最後にCapsule へのポインタを取得します
。

拡張モジュールの C API を公開するために、様々な方法で Capsule が使われ
ます。各関数を1つのオブジェクトに入れたり、全ての C API のポインタ配列
を Capsule に入れることができます。そして、ポインタに対する保存や取得
といった様々な作業は、コードを提供しているモジュールとクライアントモジ
ュールとの間では異なる方法で分散できます。

どの方法を選ぶにしても、 Capsule の name を正しく設定することは重要で
す。 "PyCapsule_New()" は name 引数 (const char*) を取ります。 "NULL"
を name に渡すことも許可されていますが、 name を設定することを強く推奨
します。正しく名前を付けられた Capsule はある程度の実行時型安全性を持
ちます。名前を付けられていない Capsule を他の Capsule と区別する現実的
な方法はありません。

特に、 C API を公開するための Capsule には次のルールに従った名前を付け
るべきです:

   modulename.attributename

"PyCapsule_Import()" という便利関数は、 Capsule の名前がこのルールに一
致しているときにのみ、簡単に Capsule 経由で公開されている C API をロー
ドすることができます。この挙動により、 C API のユーザーが、確実に正し
い C API を格納している Capsule をロードできたことを確かめることができ
ます。

以下の例では、名前を公開するモジュールの作者にほとんどの負荷が掛かりま
すが、よく使われるライブラリを作る際に適切なアプローチを実演します。こ
のアプローチでは、全ての C API ポインタ (例中では一つだけですが!) を、
Capsule の値となる void ポインタの配列に保存します。拡張モジュールに対
応するヘッダファイルは、モジュールの import と C API ポインタを取得す
るよう手配するマクロを提供します; クライアントモジュールは、C API にア
クセスする前にこのマクロを呼ぶだけです。

The exporting module is a modification of the "spam" module from
section A Simple Example. The function "spam.system()" does not call
the C library function "system()" directly, but a function
"PySpam_System()", which would of course do something more complicated
in reality (such as adding "spam" to every command). This function
"PySpam_System()" is also exported to other extension modules.

The function "PySpam_System()" is a plain C function, declared
"static" like everything else:

   static int
   PySpam_System(const char *command)
   {
       return system(command);
   }

The function "spam_system()" is modified in a trivial way:

   static PyObject *
   spam_system(PyObject *self, PyObject *args)
   {
       const char *command;
       int sts;

       if (!PyArg_ParseTuple(args, "s", &command))
           return NULL;
       sts = PySpam_System(command);
       return PyLong_FromLong(sts);
   }

モジュールの先頭にある以下の行

   #include <Python.h>

の直後に、以下の二行を必ず追加してください:

   #define SPAM_MODULE
   #include "spammodule.h"

The "#define" is used to tell the header file that it is being
included in the exporting module, not a client module. Finally, the
module's "mod_exec" function must take care of initializing the C API
pointer array:

   static int
   spam_module_exec(PyObject *m)
   {
       static void *PySpam_API[PySpam_API_pointers];
       PyObject *c_api_object;

       /* Initialize the C API pointer array */
       PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

       /* Create a Capsule containing the API pointer array's address */
       c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);

       if (PyModule_Add(m, "_C_API", c_api_object) < 0) {
           return -1;
       }

       return 0;
   }

Note that "PySpam_API" is declared "static"; otherwise the pointer
array would disappear when "PyInit_spam()" terminates!

からくりの大部分はヘッダファイル "spammodule.h" 内にあり、以下のように
なっています:

   #ifndef Py_SPAMMODULE_H
   #define Py_SPAMMODULE_H
   #ifdef __cplusplus
   extern "C" {
   #endif

   /* Header file for spammodule */

   /* C API functions */
   #define PySpam_System_NUM 0
   #define PySpam_System_RETURN int
   #define PySpam_System_PROTO (const char *command)

   /* Total number of C API pointers */
   #define PySpam_API_pointers 1


   #ifdef SPAM_MODULE
   /* This section is used when compiling spammodule.c */

   static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

   #else
   /* This section is used in modules that use spammodule's API */

   static void **PySpam_API;

   #define PySpam_System \
    (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

   /* Return -1 on error, 0 on success.
    * PyCapsule_Import will set an exception if there's an error.
    */
   static int
   import_spam(void)
   {
       PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
       return (PySpam_API != NULL) ? 0 : -1;
   }

   #endif

   #ifdef __cplusplus
   }
   #endif

   #endif /* !defined(Py_SPAMMODULE_H) */

All that a client module must do in order to have access to the
function "PySpam_System()" is to call the function (or rather macro)
"import_spam()" in its "mod_exec" function:

   static int
   client_module_exec(PyObject *m)
   {
       if (import_spam() < 0) {
           return -1;
       }
       /* additional initialization can happen here */
       return 0;
   }

このアプローチの主要な欠点は、 "spammodule.h" がやや難解になるというこ
とです。とはいえ、各関数の基本的な構成は公開されるものと同じなので、書
き方を一度だけ学べばすみます。

Finally it should be mentioned that Capsules offer additional
functionality, which is especially useful for memory allocation and
deallocation of the pointer stored in a Capsule. The details are
described in the Python/C API Reference Manual in the section カプセル
and in the implementation of Capsules (files "Include/pycapsule.h" and
"Objects/capsule.c" in the Python source code distribution).

-[ 脚注 ]-

[1] An interface for this function already exists in the standard
    module "os" --- it was chosen as a simple and straightforward
    example.

[2] 参照を "借用する" というメタファは厳密には正しくありません: なぜな
    ら、参照の所有者は依然として参照のコピーを持っているからです。

[3] 参照カウントが 1 以上かどうか調べる方法は **うまくいきません** ---
    参照カウント自体も解放されたメモリ上にあるため、その領域が他のオブ
    ジェクトに使われている可能性があります!

[4] "旧式の" 呼び出し規約を使っている場合には、この保証は適用されませ
    ん --- 既存のコードにはいまだに旧式の呼び出し規約が多々あります。
