将扩展模块移植到 Python 3

作者

Benjamin Peterson

摘要

尽管更改 C-API 并不是 Python 3 的目标之一，但许多 Python 级别的更改使得 Python 2 的 API 无法完整实现。实际上，一些变化如 int() 和 long() 的统一在 C 级别更明显。本文档致力于记录不兼容性以及如何解决这些问题。

条件编译

仅编译 Python 3 的一些代码的最简单方法是检查 PY_MAJOR_VERSION 是否大于或等于3。

  1. #if PY_MAJOR_VERSION >= 3
  2. #define IS_PY3K
  3. #endif

不存在的 API 函数可以在条件块中别名为它们的等价物。

对象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 用于二进制数据。同样重要的是要记住 pyBytes 和 Python 3中的 PyUnicode 不可互换，如 PyString 和 PyUnicode 在 Python 2 以下中示例显示了以下方面的最佳实践 PyUnicode 、 PyString 和 PyBytes 。:

  1. #include "stdlib.h"
  2. #include "Python.h"
  3. #include "bytesobject.h"
  5. /* text example */
  6. static PyObject *
  7. say_hello(PyObject *self, PyObject *args) {
  8.     PyObject *name, *result;
  10.     if (!PyArg_ParseTuple(args, "U:say_hello", &name))
  11.         return NULL;
  13.     result = PyUnicode_FromFormat("Hello, %S!", name);
  14.     return result;
  15. }
  17. /* just a forward */
  18. static char * do_encode(PyObject *);
  20. /* bytes example */
  21. static PyObject *
  22. encode_object(PyObject *self, PyObject *args) {
  23.     char *encoded;
  24.     PyObject *result, *myobj;
  26.     if (!PyArg_ParseTuple(args, "O:encode_object", &myobj))
  27.         return NULL;
  29.     encoded = do_encode(myobj);
  30.     if (encoded == NULL)
  31.         return NULL;
  32.     result = PyBytes_FromString(encoded);
  33.     free(encoded);
  34.     return result;
  35. }

long/int 统一

Python 3 只有一个整数类型， int() 。但它实际上对应于Python 2 long() 类型 —— 删除了 Python 2 中使用的 int() 类型。在 C-API 中， PyInt_* 函数被它们等价的 PyLong_* 替换。

模块初始化和状态

Python 3 有一个改进的扩展模块初始化系统。（参见 PEP 3121 。）而不是将模块状态存储在全局变量中，它们应该存储在特定于解释器的结构中。创建在 Python 2 和 Python 3 中正确运行的模块非常棘手。以下简单示例演示了如何操作。:

  1. #include "Python.h"
  3. struct module_state {
  4.     PyObject *error;
  5. };
  7. #if PY_MAJOR_VERSION >= 3
  8. #define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
  9. #else
  10. #define GETSTATE(m) (&_state)
  11. static struct module_state _state;
  12. #endif
  14. static PyObject *
  15. error_out(PyObject *m) {
  16.     struct module_state *st = GETSTATE(m);
  17.     PyErr_SetString(st->error, "something bad happened");
  18.     return NULL;
  19. }
  21. static PyMethodDef myextension_methods[] = {
  22.     {"error_out", (PyCFunction)error_out, METH_NOARGS, NULL},
  23.     {NULL, NULL}
  24. };
  26. #if PY_MAJOR_VERSION >= 3
  28. static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
  29.     Py_VISIT(GETSTATE(m)->error);
  30.     return 0;
  31. }
  33. static int myextension_clear(PyObject *m) {
  34.     Py_CLEAR(GETSTATE(m)->error);
  35.     return 0;
  36. }
  39. static struct PyModuleDef moduledef = {
  40.         PyModuleDef_HEAD_INIT,
  41.         "myextension",
  42.         NULL,
  43.         sizeof(struct module_state),
  44.         myextension_methods,
  45.         NULL,
  46.         myextension_traverse,
  47.         myextension_clear,
  48.         NULL
  49. };
  51. #define INITERROR return NULL
  53. PyMODINIT_FUNC
  54. PyInit_myextension(void)
  56. #else
  57. #define INITERROR return
  59. void
  60. initmyextension(void)
  61. #endif
  62. {
  63. #if PY_MAJOR_VERSION >= 3
  64.     PyObject *module = PyModule_Create(&moduledef);
  65. #else
  66.     PyObject *module = Py_InitModule("myextension", myextension_methods);
  67. #endif
  69.     if (module == NULL)
  70.         INITERROR;
  71.     struct module_state *st = GETSTATE(module);
  73.     st->error = PyErr_NewException("myextension.Error", NULL, NULL);
  74.     if (st->error == NULL) {
  75.         Py_DECREF(module);
  76.         INITERROR;
  77.     }
  79. #if PY_MAJOR_VERSION >= 3
  80.     return module;
  81. #endif
  82. }

CObject 替换为 Capsule

Capsule 对象是在 Python 3.1 和 2.7 中引入的，用于替换 CObject 。 CObject 是有用的，但是 CObject API 是有问题的：它不允许区分有效的 CObject ，这导致不匹配的 CObject 使解释器崩溃，并且它的一些 API 依赖于 C 中的未定义行为。有关 Capsule 背后的基本原理的进一步阅读，请参阅 bpo-5630 。）

如果你当前正在使用 CObject ，并且想要迁移到 3.1 或更高版本，则需要切换到 Capsules 。 CObject 在 3.1 和 2.7 中已弃用，在 Python 3.2 中已完全删除。如果你只支持 2.7 或 3.1 及以上，你可以简单地切换到 Capsule 。如果你需要支持 Python 3.0 或早于 2.7 的 Python 版本，则必须同时支持 CObject 和 Capsule 。（请注意，不再支持 Python 3.0 ，不建议将其用于生产用途。）

以下示例头文件 capsulethunk.h 可以为你解决问题。只需针对 Capsule API 编写代码，并在以下文件后包含此头文件 Python.h 。你的代码将自动在带有 Capsule 的 Python 版本中使用 Capsules ，并在 Capsule 不可用时切换到 CObjects 。

capsulethunk.h 使用 CObject 模拟 Capsules 。 但是， CObject 没有提供存储胶囊的“名称”的地方。因此，模拟 Capsule 对象由 capsulethunk.h 创建，其行为与真实 Capsule 略有不同。特别地：

你可以在 Python 源代码分发中的 Doc/includes/capsulethunk.h 找到 capsulethunk.h 。为方便起见，我们还将其包含在此处：

  1. #ifndef __CAPSULETHUNK_H
  2. #define __CAPSULETHUNK_H
  4. #if (    (PY_VERSION_HEX <  0x02070000) \
  5.      || ((PY_VERSION_HEX >= 0x03000000) \
  6.       && (PY_VERSION_HEX <  0x03010000)) )
  8. #define __PyCapsule_GetField(capsule, field, default_value) \
  9.     ( PyCapsule_CheckExact(capsule) \
  10.         ? (((PyCObject *)capsule)->field) \
  11.         : (default_value) \
  12.     ) \
  14. #define __PyCapsule_SetField(capsule, field, value) \
  15.     ( PyCapsule_CheckExact(capsule) \
  16.         ? (((PyCObject *)capsule)->field = value), 1 \
  17.         : 0 \
  18.     ) \
  21. #define PyCapsule_Type PyCObject_Type
  23. #define PyCapsule_CheckExact(capsule) (PyCObject_Check(capsule))
  24. #define PyCapsule_IsValid(capsule, name) (PyCObject_Check(capsule))
  27. #define PyCapsule_New(pointer, name, destructor) \
  28.     (PyCObject_FromVoidPtr(pointer, destructor))
  31. #define PyCapsule_GetPointer(capsule, name) \
  32.     (PyCObject_AsVoidPtr(capsule))
  34. /* Don't call PyCObject_SetPointer here, it fails if there's a destructor */
  35. #define PyCapsule_SetPointer(capsule, pointer) \
  36.     __PyCapsule_SetField(capsule, cobject, pointer)
  39. #define PyCapsule_GetDestructor(capsule) \
  40.     __PyCapsule_GetField(capsule, destructor)
  42. #define PyCapsule_SetDestructor(capsule, dtor) \
  43.     __PyCapsule_SetField(capsule, destructor, dtor)
  46. /*
  47.  * Sorry, there's simply no place
  48.  * to store a Capsule "name" in a CObject.
  49.  */
  50. #define PyCapsule_GetName(capsule) NULL
  52. static int
  53. PyCapsule_SetName(PyObject *capsule, const char *unused)
  54. {
  55.     unused = unused;
  56.     PyErr_SetString(PyExc_NotImplementedError,
  57.         "can't use PyCapsule_SetName with CObjects");
  58.     return 1;
  59. }
  63. #define PyCapsule_GetContext(capsule) \
  64.     __PyCapsule_GetField(capsule, descr)
  66. #define PyCapsule_SetContext(capsule, context) \
  67.     __PyCapsule_SetField(capsule, descr, context)
  70. static void *
  71. PyCapsule_Import(const char *name, int no_block)
  72. {
  73.     PyObject *object = NULL;
  74.     void *return_value = NULL;
  75.     char *trace;
  76.     size_t name_length = (strlen(name) + 1) * sizeof(char);
  77.     char *name_dup = (char *)PyMem_MALLOC(name_length);
  79.     if (!name_dup) {
  80.         return NULL;
  81.     }
  83.     memcpy(name_dup, name, name_length);
  85.     trace = name_dup;
  86.     while (trace) {
  87.         char *dot = strchr(trace, '.');
  88.         if (dot) {
  89.             *dot++ = '\0';
  90.         }
  92.         if (object == NULL) {
  93.             if (no_block) {
  94.                 object = PyImport_ImportModuleNoBlock(trace);
  95.             } else {
  96.                 object = PyImport_ImportModule(trace);
  97.                 if (!object) {
  98.                     PyErr_Format(PyExc_ImportError,
  99.                         "PyCapsule_Import could not "
  100.                         "import module \"%s\"", trace);
  101.                 }
  102.             }
  103.         } else {
  104.             PyObject *object2 = PyObject_GetAttrString(object, trace);
  105.             Py_DECREF(object);
  106.             object = object2;
  107.         }
  108.         if (!object) {
  109.             goto EXIT;
  110.         }
  112.         trace = dot;
  113.     }
  115.     if (PyCObject_Check(object)) {
  116.         PyCObject *cobject = (PyCObject *)object;
  117.         return_value = cobject->cobject;
  118.     } else {
  119.         PyErr_Format(PyExc_AttributeError,
  120.             "PyCapsule_Import \"%s\" is not valid",
  121.             name);
  122.     }
  124. EXIT:
  125.     Py_XDECREF(object);
  126.     if (name_dup) {
  127.         PyMem_FREE(name_dup);
  128.     }
  129.     return return_value;
  130. }
  132. #endif /* #if PY_VERSION_HEX < 0x02070000 */
  134. #endif /* __CAPSULETHUNK_H */

其他选项

如果你正在编写新的扩展模块，你可能会考虑 Cython 。 它将类似 Python 的语言转换为 C 。它创建的扩展模块与 Python 3 和 Python 2 兼容。