Porting Extension Modules to Python 3¶
| 作者： | 本杰明·彼得森 |
|---|
抽象
虽然更改C-API不是Python 3的目标之一，但是许多Python级别的更改使得Python 2的API完全不可能。事实上，在C级别上，诸如int()和long()之类的一些更改更为明显。本文档努力记录不兼容性以及如何处理它们。
Conditional compilation¶
编译Python 3的最简单的方法是检查PY_MAJOR_VERSION是否大于或等于3。
#if PY_MAJOR_VERSION >= 3
#define IS_PY3K
#endif
不存在的API函数可以在条件块内被别名为其等价物。
Changes to Object APIs¶
Python 3将一些具有类似功能的类型合并在一起，同时干净地分离了其他类型。
str/unicode Unification¶
Python 3的str()类型等同于Python 2的unicode()；两个C函数都被称为PyUnicode_*。旧的8位字符串类型变为bytes()，具有称为PyBytes_*的C函数。Python 2.6和更高版本提供了兼容性标头bytesobject.h，将PyBytes名称映射到PyString为了与Python 3最佳兼容，PyUnicode应用于文本数据，PyBytes用于二进制数据。还有一点要记住，Python 3中的PyBytes和PyUnicode不能互换，如PyString和PyUnicode 2。以下示例显示了有关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;
}
Module initialization and state¶
Python 3有一个改进的扩展模块初始化系统。（请参阅 PEP 3121。）不是将模块状态存储在全局变量中，而应将其存储在解释器特定结构中。创建在Python 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 replaced with Capsule¶
在Python 3.1和2.7中引入了Capsule对象来替换CObject。CObjects是有用的，但CObject API有问题：它不允许区分有效的CObjects，允许不匹配的CObject崩溃解释器，并且它的一些API依赖于未定义的行为在C中。 （有关胶囊背后的理由的进一步阅读，请参阅问题5630。）
如果您目前正在使用CObjects，并且要迁移到3.1或更高版本，则需要切换到“胶囊”。CObject在3.1和2.7版本中已弃用，并在Python 3.2中完全移除。如果您只支持2.7或3.1及以上版本，则只需切换到Capsule即可。如果你需要支持Python 3.0或早于2.7的Python版本，你必须同时支持CObjects和Capsules。（请注意，不再支持Python 3.0，不推荐在生产环境中使用。）
以下示例头文件capsulethunk.h可能为您解决问题。只需根据Capsule API编写代码，并在Python.h之后包含此头文件即可。您的代码将自动在使用Capsules的Python版本中使用Capsules，并在Capsules不可用时切换到CObjects。
capsulethunk.h使用CObjects模拟Capsules。然而，CObject没有提供存储胶囊的“名称”的地方。因此，由capsulethunk.h创建的模拟Capsule对象的行为与真实胶囊稍有不同。特别：
- The name parameter passed in to
PyCapsule_New()is ignored.- The name parameter passed in to
PyCapsule_IsValid()andPyCapsule_GetPointer()is ignored, and no error checking of the name is performed.PyCapsule_GetName()always returns NULL.PyCapsule_SetName()always raises an exception and returns failure. (Since there’s no way to store a name in a CObject, noisy failure ofPyCapsule_SetName()was deemed preferable to silent failure here. If this is inconvenient, feel free to modify your local copy as you see fit.)
您可以在Python源代码分发中找到capsulethunk.h为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 */