Python 3 への拡張モジュール移植¶
author: | Benjamin Peterson |
---|
Abstract
C-API の変更は Python 3 の目標には入っていませんでしたが、Python レベルでの変更がたくさんあったので、Python 2 の API を無傷で済ませることはできませんでした。実際、 int()
と long()
の統合などは C レベルのほうが目立ちます。この文書では、なくなった互換性と、その対処方法について記述しようと思います。
条件コンパイル¶
一部のコードを Python 3 にだけコンパイルするための一番簡単な方法は、 PY_MAJOR_VERSION
が 3 以上かどうかチェックすることです。
#if PY_MAJOR_VERSION >= 3
#define IS_PY3K
#endif
存在しなくなった関数については、条件ブロックの中で同等品にエイリアスすれば良いでしょう。
オブジェクト API の変更¶
Python 3 では、似た機能を持つタイプのいくつかを、統合したり、きっちり分けたりしました。
str/unicode の統合¶
Python 3 の str()
タイプは Python 2 の unicode()
と同じもので、どちらも C 関数は PyUnicode_*
と呼ばれます。昔の 8 ビット文字列タイプは bytes()
になり、C 関数は PyBytes_*
と呼ばれます。Python 2.6 以降には互換性ヘッダ bytesobject.h
が用意されており、 PyBytes
系の名前を PyString
系にマップしています。Python 3 との互換性を最大限確保するには、 PyUnicode
は文字データに、 PyBytes
はバイナリデータにだけ使うべきです。ほかにも、Python 3 の PyBytes
と PyUnicode
は Python 2 の PyString
と PyUnicode
とは違って交換不可能だということも重要です。以下の例では PyUnicode
, PyString
, PyBytes
に関するベストプラクティスを見ることができます。
#include "stdlib.h"
#include "Python.h"
#include "bytesobject.h"
/* text example */
static PyObject *
say_hello(PyObject *self, PyObject *args) {
PyObject *name, *result;
if (!PyArg_ParseTuple(args, "U:say_hello", &name))
return NULL;
result = PyUnicode_FromFormat("Hello, %S!", name);
return result;
}
/* just a forward */
static char * do_encode(PyObject *);
/* bytes example */
static PyObject *
encode_object(PyObject *self, PyObject *args) {
char *encoded;
PyObject *result, *myobj;
if (!PyArg_ParseTuple(args, "O:encode_object", &myobj))
return NULL;
encoded = do_encode(myobj);
if (encoded == NULL)
return NULL;
result = PyBytes_FromString(encoded);
free(encoded);
return result;
}
モジュールの初期化と状態情報¶
Python 3 には、改良された拡張モジュール初期化システムがあります (PEP 3121 参照)。モジュールの状態はグローバル変数に持つのではなく、インタプリタ固有の構造体に持つべきだということになったのです。Pythonk 2 と Python 3 のどちらでも動くモジュールを作るのにはコツが要ります。次の簡単な例で、その方法を実演してみます。
#include "Python.h"
struct module_state {
PyObject *error;
};
#if PY_MAJOR_VERSION >= 3
#define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
#else
#define GETSTATE(m) (&_state)
static struct module_state _state;
#endif
static PyObject *
error_out(PyObject *m) {
struct module_state *st = GETSTATE(m);
PyErr_SetString(st->error, "something bad happened");
return NULL;
}
static PyMethodDef myextension_methods[] = {
{"error_out", (PyCFunction)error_out, METH_NOARGS, NULL},
{NULL, NULL}
};
#if PY_MAJOR_VERSION >= 3
static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
Py_VISIT(GETSTATE(m)->error);
return 0;
}
static int myextension_clear(PyObject *m) {
Py_CLEAR(GETSTATE(m)->error);
return 0;
}
static struct PyModuleDef moduledef = {
PyModuleDef_HEAD_INIT,
"myextension",
NULL,
sizeof(struct module_state),
myextension_methods,
NULL,
myextension_traverse,
myextension_clear,
NULL
};
#define INITERROR return NULL
PyMODINIT_FUNC
PyInit_myextension(void)
#else
#define INITERROR return
void
initmyextension(void)
#endif
{
#if PY_MAJOR_VERSION >= 3
PyObject *module = PyModule_Create(&moduledef);
#else
PyObject *module = Py_InitModule("myextension", myextension_methods);
#endif
if (module == NULL)
INITERROR;
struct module_state *st = GETSTATE(module);
st->error = PyErr_NewException("myextension.Error", NULL, NULL);
if (st->error == NULL) {
Py_DECREF(module);
INITERROR;
}
#if PY_MAJOR_VERSION >= 3
return module;
#endif
}
CObject の Capsule への変更¶
Python 3.1 と 2.7 に Capsule
オブジェクトが導入されました。これは CObject
のかわりになるものです。 CObject は便利でしたが、 CObject
API には問題がありました: 有効な CObject であればそれ以上の識別が不可能なので、合わない CObject を混ぜて使うとインタープリタをクラッシュさせかねなかったこと、そして API の一部が C の未定義な挙動に依存していたことです。 (Capsule の背景について詳しくは bpo-5630 をご覧ください。)
現時点で CObject を使っているのであれば、3.1 以降へ移行するには Capsule へ切り換える必要があります。 CObject
は 3.1 および 2.7 で非推奨となり、Python 3.2 では完全に削除されたからです。 2.7 と 3.1 以上だけの対応でいいなら、単に Capsule
へ切り換えるだけです。 しかし Python 3.0 や、あるいは 2.7 未満のバージョンに対応しなければならない場合は、CObject と Capsule の両方に対応する必要が出てきます。(ただし Python 3.0 はサポートが終了しているため現場利用には推奨されません。)
そうした問題は、下に例示する capsulethunk.h
ヘッダファイルで解決できるかもしれません。 必要な作業は、 Capsule
API でコードを書き、このヘッダファイルを Python.h
の後でインクルードするだけです。 すると自動的に、Capsule のあるバージョンの Python では Capsule を使い、なければ CObject を使うようになります。
その場合 capsulethunk.h
は CObject を使って Capsule をシミュレートします。 しかし CObject
には capsule の "name" を保持する余地がありません。 よって、 capsulethunk.h
でシミュレートされた Capsule
オブジェクトの動作は、本物の Capsule とは少し異なります。 具体的には:
PyCapsule_New()
に渡された name 引数は無視されます。PyCapsule_IsValid()
およびPyCapsule_GetPointer()
に渡された name 引数は無視され、name のエラーチェックも実行されません。PyCapsule_GetName()
は常に NULL を返します。PyCapsule_SetName()
は常に例外を送出して、失敗を返します。 (CObject に名前を格納する方法がないので、ここではPyCapsule_SetName()
のうるさい失敗は暗黙の失敗より好ましいと考えられました。これが不便な場合は、適切と思うやり方で自由にローカルコピーを修正してください。)
capsulethunk.h
は Python のソースの中に Doc/includes/capsulethunk.h という名前で入っています。 読者の便宜のため、ここにも引用しておきましょう:
#ifndef __CAPSULETHUNK_H
#define __CAPSULETHUNK_H
#if ( (PY_VERSION_HEX < 0x02070000) \
|| ((PY_VERSION_HEX >= 0x03000000) \
&& (PY_VERSION_HEX < 0x03010000)) )
#define __PyCapsule_GetField(capsule, field, default_value) \
( PyCapsule_CheckExact(capsule) \
? (((PyCObject *)capsule)->field) \
: (default_value) \
) \
#define __PyCapsule_SetField(capsule, field, value) \
( PyCapsule_CheckExact(capsule) \
? (((PyCObject *)capsule)->field = value), 1 \
: 0 \
) \
#define PyCapsule_Type PyCObject_Type
#define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))
#define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))
#define PyCapsule_New(pointer, name, destructor) \
(PyCObject_FromVoidPtr(pointer, destructor))
#define PyCapsule_GetPointer(capsule, name) \
(PyCObject_AsVoidPtr(capsule))
/* Don't call PyCObject_SetPointer here, it fails if there's a destructor */
#define PyCapsule_SetPointer(capsule, pointer) \
__PyCapsule_SetField(capsule, cobject, pointer)
#define PyCapsule_GetDestructor(capsule) \
__PyCapsule_GetField(capsule, destructor)
#define PyCapsule_SetDestructor(capsule, dtor) \
__PyCapsule_SetField(capsule, destructor, dtor)
/*
* Sorry, there's simply no place
* to store a Capsule "name" in a CObject.
*/
#define PyCapsule_GetName(capsule) NULL
static int
PyCapsule_SetName(PyObject *capsule, const char *unused)
{
unused = unused;
PyErr_SetString(PyExc_NotImplementedError,
"can't use PyCapsule_SetName with CObjects");
return 1;
}
#define PyCapsule_GetContext(capsule) \
__PyCapsule_GetField(capsule, descr)
#define PyCapsule_SetContext(capsule, context) \
__PyCapsule_SetField(capsule, descr, context)
static void *
PyCapsule_Import(const char *name, int no_block)
{
PyObject *object = NULL;
void *return_value = NULL;
char *trace;
size_t name_length = (strlen(name) + 1) * sizeof(char);
char *name_dup = (char *)PyMem_MALLOC(name_length);
if (!name_dup) {
return NULL;
}
memcpy(name_dup, name, name_length);
trace = name_dup;
while (trace) {
char *dot = strchr(trace, '.');
if (dot) {
*dot++ = '\0';
}
if (object == NULL) {
if (no_block) {
object = PyImport_ImportModuleNoBlock(trace);
} else {
object = PyImport_ImportModule(trace);
if (!object) {
PyErr_Format(PyExc_ImportError,
"PyCapsule_Import could not "
"import module \"%s\"", trace);
}
}
} else {
PyObject *object2 = PyObject_GetAttrString(object, trace);
Py_DECREF(object);
object = object2;
}
if (!object) {
goto EXIT;
}
trace = dot;
}
if (PyCObject_Check(object)) {
PyCObject *cobject = (PyCObject *)object;
return_value = cobject->cobject;
} else {
PyErr_Format(PyExc_AttributeError,
"PyCapsule_Import \"%s\" is not valid",
name);
}
EXIT:
Py_XDECREF(object);
if (name_dup) {
PyMem_FREE(name_dup);
}
return return_value;
}
#endif /* #if PY_VERSION_HEX < 0x02070000 */
#endif /* __CAPSULETHUNK_H */