cpython/Doc/howto/cporting.rst

219 lines
5.7 KiB
ReStructuredText
Raw Normal View History

.. highlightlang:: c
.. _cporting-howto:
********************************
Porting Extension Modules to 3.0
********************************
:author: Benjamin Peterson
.. topic:: Abstract
Although changing the C-API was not one of Python 3.0's objectives, the many
Python level changes made leaving 2.x's API intact impossible. In fact, some
changes such as :func:`int` and :func:`long` unification are more obvious on
the C level. This document endeavors to document incompatibilities and how
they can be worked around.
Conditional compilation
=======================
The easiest way to compile only some code for 3.0 is to check if
:cmacro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::
#if PY_MAJOR_VERSION >= 3
#define IS_PY3K
#endif
API functions that are not present can be aliased to their equivalents within
2008-09-26 18:15:21 -03:00
conditional blocks.
Changes to Object APIs
======================
2008-09-26 18:15:21 -03:00
Python 3.0 merged together some types with similar functions while cleanly
separating others.
str/unicode Unification
-----------------------
Python 3.0's :func:`str` (``PyString_*`` functions in C) type is equivalent to
2.x's :func:`unicode` (``PyUnicode_*``). The old 8-bit string type has become
:func:`bytes`. Python 2.6 and later provide a compatibility header,
:file:`bytesobject.h`, mapping ``PyBytes`` names to ``PyString`` ones. For best
2008-09-27 20:28:43 -03:00
compatibility with 3.0, :ctype:`PyUnicode` should be used for textual data and
:ctype:`PyBytes` for binary data. It's also important to remember that
:ctype:`PyBytes` and :ctype:`PyUnicode` in 3.0 are not interchangeable like
Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line #10072: assume a bit less knowledge of the FTP protocol in the ftplib docs. ........ r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line #10122: typo fix. ........ r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line #10124: typo fix. ........ r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line #10058: tweak wording about exception returns. ........ r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line #8556: use less confusing mapping key in example. ........ r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line #8686: remove potentially confusing wording that does not add any value. ........ r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line #8811: small fixes to sqlite3 docs. ........ r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line #8855: add shelve security warning. ........ r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line #8968: add actual name of token constants. ........ r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line #459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows. ........ r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line Fix copy-paste error in example. ........
2010-11-26 03:42:15 -04:00
:ctype:`PyString` and :ctype:`PyUnicode` are in 2.x. The following example
shows best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`,
and :ctype:`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;
}
2008-09-27 20:28:43 -03:00
/* 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;
}
long/int Unification
--------------------
In Python 3.0, there is only one integer type. It is called :func:`int` on the
Python level, but actually corresponds to 2.x's :func:`long` type. In the
C-API, ``PyInt_*`` functions are replaced by their ``PyLong_*`` neighbors. The
2008-09-27 20:28:43 -03:00
best course of action here is using the ``PyInt_*`` functions aliased to
2009-04-03 18:45:29 -03:00
``PyLong_*`` found in :file:`intobject.h`. The abstract ``PyNumber_*`` APIs
2008-09-27 20:28:43 -03:00
can also be used in some cases. ::
#include "Python.h"
2008-09-27 20:28:43 -03:00
#include "intobject.h"
static PyObject *
add_ints(PyObject *self, PyObject *args) {
int one, two;
PyObject *result;
if (!PyArg_ParseTuple(args, "ii:add_ints", &one, &two))
return NULL;
return PyInt_FromLong(one + two);
}
Module initialization and state
===============================
Python 3.0 has a revamped extension module initialization system. (See
:pep:`3121`.) Instead of storing module state in globals, they should be stored
2008-09-26 18:15:21 -03:00
in an interpreter specific structure. Creating modules that act correctly in
both 2.x and 3.0 is tricky. The following simple example demonstrates how. ::
#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
PyObject *
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
}
2008-09-26 17:52:06 -03:00
Other options
=============
If you are writing a new extension module, you might consider `Cython
<http://www.cython.org>`_. It translates a Python-like language to C. The
extension modules it creates are compatible with Python 3.x and 2.x.