3 ********************************
4 Porting Extension Modules to 3.0
5 ********************************
7 :author: Benjamin Peterson
12 Although changing the C-API was not one of Python 3.0's objectives, the many
13 Python level changes made leaving 2.x's API intact impossible. In fact, some
14 changes such as :func:`int` and :func:`long` unification are more obvious on
15 the C level. This document endeavors to document incompatibilities and how
16 they can be worked around.
19 Conditional compilation
20 =======================
22 The easiest way to compile only some code for 3.0 is to check if
23 :cmacro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::
25 #if PY_MAJOR_VERSION >= 3
29 API functions that are not present can be aliased to their equivalents within
33 Changes to Object APIs
34 ======================
36 Python 3.0 merged together some types with similar functions while cleanly
40 str/unicode Unification
41 -----------------------
44 Python 3.0's :func:`str` (``PyString_*`` functions in C) type is equivalent to
45 2.x's :func:`unicode` (``PyUnicode_*``). The old 8-bit string type has become
46 :func:`bytes`. Python 2.6 and later provide a compatibility header,
47 :file:`bytesobject.h`, mapping ``PyBytes`` names to ``PyString`` ones. For best
48 compatibility with 3.0, :ctype:`PyUnicode` should be used for textual data and
49 :ctype:`PyBytes` for binary data. It's also important to remember that
50 :ctype:`PyBytes` and :ctype:`PyUnicode` in 3.0 are not interchangeable like
51 :ctype:`PyString` and :ctype:`PyString` are in 2.x. The following example shows
52 best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`, and
57 #include "bytesobject.h"
61 say_hello(PyObject *self, PyObject *args) {
62 PyObject *name, *result;
64 if (!PyArg_ParseTuple(args, "U:say_hello", &name))
67 result = PyUnicode_FromFormat("Hello, %S!", name);
72 static char * do_encode(PyObject *);
76 encode_object(PyObject *self, PyObject *args) {
78 PyObject *result, *myobj;
80 if (!PyArg_ParseTuple(args, "O:encode_object", &myobj))
83 encoded = do_encode(myobj);
86 result = PyBytes_FromString(encoded);
95 In Python 3.0, there is only one integer type. It is called :func:`int` on the
96 Python level, but actually corresponds to 2.x's :func:`long` type. In the
97 C-API, ``PyInt_*`` functions are replaced by their ``PyLong_*`` neighbors. The
98 best course of action here is using the ``PyInt_*`` functions aliased to
99 ``PyLong_*`` found in :file:`intobject.h`. The abstract ``PyNumber_*`` APIs
100 can also be used in some cases. ::
103 #include "intobject.h"
106 add_ints(PyObject *self, PyObject *args) {
110 if (!PyArg_ParseTuple(args, "ii:add_ints", &one, &two))
113 return PyInt_FromLong(one + two);
118 Module initialization and state
119 ===============================
121 Python 3.0 has a revamped extension module initialization system. (See PEP
122 :pep:`3121`.) Instead of storing module state in globals, they should be stored
123 in an interpreter specific structure. Creating modules that act correctly in
124 both 2.x and 3.0 is tricky. The following simple example demonstrates how. ::
128 struct module_state {
132 #if PY_MAJOR_VERSION >= 3
133 #define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
135 #define GETSTATE(m) (&_state)
136 static struct module_state _state;
140 error_out(PyObject *m) {
141 struct module_state *st = GETSTATE(m);
142 PyErr_SetString(st->error, "something bad happened");
146 static PyMethodDef myextension_methods[] = {
147 {"error_out", (PyCFunction)error_out, METH_NOARGS, NULL},
151 #if PY_MAJOR_VERSION >= 3
153 static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
154 Py_VISIT(GETSTATE(m)->error);
158 static int myextension_clear(PyObject *m) {
159 Py_CLEAR(GETSTATE(m)->error);
164 static struct PyModuleDef moduledef = {
165 PyModuleDef_HEAD_INIT,
168 sizeof(struct module_state),
171 myextension_traverse,
176 #define INITERROR return NULL
179 PyInit_myextension(void)
182 #define INITERROR return
185 initmyextension(void)
188 #if PY_MAJOR_VERSION >= 3
189 PyObject *module = PyModule_Create(&moduledef);
191 PyObject *module = Py_InitModule("myextension", myextension_methods);
196 struct module_state *st = GETSTATE(module);
198 st->error = PyErr_NewException("myextension.Error", NULL, NULL);
199 if (st->error == NULL) {
204 #if PY_MAJOR_VERSION >= 3
213 If you are writing a new extension module, you might consider `Cython
214 <http://www.cython.org>`_. It translates a Python-like language to C. The
215 extension modules it creates are compatible with Python 3.x and 2.x.