Edit File - File Manager

Edit File: cporting.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
 <title>Porting Extension Modules to 3.0 &mdash; Python v2.6.6 documentation</title>
 <link rel="stylesheet" href="../_static/default.css" type="text/css" />
 <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
 <script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '../',
 VERSION: '2.6.6',
 COLLAPSE_MODINDEX: false,
 FILE_SUFFIX: '.html',
 HAS_SOURCE: true
 };
 </script>
 <script type="text/javascript" src="../_static/jquery.js"></script>
 <script type="text/javascript" src="../_static/doctools.js"></script>
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python v2.6.6 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="top" title="Python v2.6.6 documentation" href="../index.html" />
 <link rel="up" title="Python HOWTOs" href="index.html" />
 <link rel="next" title="Curses Programming with Python" href="curses.html" />
 <link rel="prev" title="Python Advocacy HOWTO" href="advocacy.html" />
 <link rel="shortcut icon" type="image/png" href="../_static/py.png" />

</head>
 <body>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../modindex.html" title="Global Module Index"
 accesskey="M">modules</a> |</li>
 <li class="right" >
 <a href="curses.html" title="Curses Programming with Python"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="advocacy.html" title="Python Advocacy HOWTO"
 accesskey="P">previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="../index.html">Python v2.6.6 documentation</a> &raquo;</li>

<li><a href="index.html" accesskey="U">Python HOWTOs</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body">
 
 <div class="section" id="porting-extension-modules-to-3-0">
<h1>Porting Extension Modules to 3.0<a class="headerlink" href="#porting-extension-modules-to-3-0" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">author:</th><td class="field-body">Benjamin Peterson</td>
</tr>
</tbody>
</table>
<div class="topic">
Abstract
Although changing the C-API was not one of Python 3.0&#8217;s objectives, the many
Python level changes made leaving 2.x&#8217;s API intact impossible. In fact, some
changes such as <a title="int" class="reference external" href="../library/functions.html#int"><tt class="xref docutils literal">int()</tt></a> and <a title="long" class="reference external" href="../library/functions.html#long"><tt class="xref docutils literal">long()</tt></a> unification are more obvious on
the C level. This document endeavors to document incompatibilities and how
they can be worked around.
</div>
<div class="section" id="conditional-compilation">
<h2>Conditional compilation<a class="headerlink" href="#conditional-compilation" title="Permalink to this headline">¶</a></h2>
The easiest way to compile only some code for 3.0 is to check if
<tt class="xref docutils literal">PY_MAJOR_VERSION</tt> is greater than or equal to 3.
<div class="highlight-c"><div class="highlight"><pre>#if PY_MAJOR_VERSION &gt;= 3
#define IS_PY3K
#endif
</pre></div>
</div>
API functions that are not present can be aliased to their equivalents within
conditional blocks.
</div>
<div class="section" id="changes-to-object-apis">
<h2>Changes to Object APIs<a class="headerlink" href="#changes-to-object-apis" title="Permalink to this headline">¶</a></h2>
Python 3.0 merged together some types with similar functions while cleanly
separating others.
<div class="section" id="str-unicode-unification">
<h3>str/unicode Unification<a class="headerlink" href="#str-unicode-unification" title="Permalink to this headline">¶</a></h3>
Python 3.0&#8217;s <a title="str" class="reference external" href="../library/functions.html#str"><tt class="xref docutils literal">str()</tt></a> (<tt class="docutils literal">PyString_*</tt> functions in C) type is equivalent to
2.x&#8217;s <a title="unicode" class="reference external" href="../library/functions.html#unicode"><tt class="xref docutils literal">unicode()</tt></a> (<tt class="docutils literal">PyUnicode_*</tt>). The old 8-bit string type has become
<tt class="xref docutils literal">bytes()</tt>. Python 2.6 and later provide a compatibility header,
<tt class="docutils literal">bytesobject.h</tt>, mapping <tt class="docutils literal">PyBytes</tt> names to <tt class="docutils literal">PyString</tt> ones. For best
compatibility with 3.0, <tt class="xref docutils literal">PyUnicode</tt> should be used for textual data and
<tt class="xref docutils literal">PyBytes</tt> for binary data. It&#8217;s also important to remember that
<tt class="xref docutils literal">PyBytes</tt> and <tt class="xref docutils literal">PyUnicode</tt> in 3.0 are not interchangeable like
<tt class="xref docutils literal">PyString</tt> and <tt class="xref docutils literal">PyString</tt> are in 2.x. The following example shows
best practices with regards to <tt class="xref docutils literal">PyUnicode</tt>, <tt class="xref docutils literal">PyString</tt>, and
<tt class="xref docutils literal">PyBytes</tt>.
<div class="highlight-c"><div class="highlight"><pre>#include &quot;stdlib.h&quot;
#include &quot;Python.h&quot;
#include &quot;bytesobject.h&quot;

/* text example */
static PyObject *
say_hello(PyObject *self, PyObject *args) {
 PyObject *name, *result;

if (!PyArg_ParseTuple(args, &quot;U:say_hello&quot;, &amp;name))
 return NULL;

result = PyUnicode_FromFormat(&quot;Hello, %S!&quot;, 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, &quot;O:encode_object&quot;, &amp;myobj))
 return NULL;

encoded = do_encode(myobj);
 if (encoded == NULL)
 return NULL;
 result = PyBytes_FromString(encoded);
 free(encoded);
 return result;
}
</pre></div>
</div>
</div>
<div class="section" id="long-int-unification">
<h3>long/int Unification<a class="headerlink" href="#long-int-unification" title="Permalink to this headline">¶</a></h3>
In Python 3.0, there is only one integer type. It is called <a title="int" class="reference external" href="../library/functions.html#int"><tt class="xref docutils literal">int()</tt></a> on the
Python level, but actually corresponds to 2.x&#8217;s <a title="long" class="reference external" href="../library/functions.html#long"><tt class="xref docutils literal">long()</tt></a> type. In the
C-API, <tt class="docutils literal">PyInt_*</tt> functions are replaced by their <tt class="docutils literal">PyLong_*</tt> neighbors. The
best course of action here is using the <tt class="docutils literal">PyInt_*</tt> functions aliased to
<tt class="docutils literal">PyLong_*</tt> found in <tt class="docutils literal">intobject.h</tt>. The abstract <tt class="docutils literal">PyNumber_*</tt> APIs
can also be used in some cases.
<div class="highlight-c"><div class="highlight"><pre>#include &quot;Python.h&quot;
#include &quot;intobject.h&quot;

static PyObject *
add_ints(PyObject *self, PyObject *args) {
 int one, two;
 PyObject *result;

if (!PyArg_ParseTuple(args, &quot;ii:add_ints&quot;, &amp;one, &amp;two))
 return NULL;

return PyInt_FromLong(one + two);
}
</pre></div>
</div>
</div>
</div>
<div class="section" id="module-initialization-and-state">
<h2>Module initialization and state<a class="headerlink" href="#module-initialization-and-state" title="Permalink to this headline">¶</a></h2>
Python 3.0 has a revamped extension module initialization system. (See
<a class="reference external" href="http://www.python.org/dev/peps/pep-3121">PEP 3121</a>.) Instead of storing module state in globals, they should be stored
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.
<div class="highlight-c"><div class="highlight"><pre>#include &quot;Python.h&quot;

struct module_state {
 PyObject *error;
};

#if PY_MAJOR_VERSION &gt;= 3
#define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
#else
#define GETSTATE(m) (&amp;_state)
static struct module_state _state;
#endif

static PyObject *
error_out(PyObject *m) {
 struct module_state *st = GETSTATE(m);
 PyErr_SetString(st-&gt;error, &quot;something bad happened&quot;);
 return NULL;
}

static PyMethodDef myextension_methods[] = {
 {&quot;error_out&quot;, (PyCFunction)error_out, METH_NOARGS, NULL},
 {NULL, NULL}
};

#if PY_MAJOR_VERSION &gt;= 3

static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
 Py_VISIT(GETSTATE(m)-&gt;error);
 return 0;
}

static int myextension_clear(PyObject *m) {
 Py_CLEAR(GETSTATE(m)-&gt;error);
 return 0;
}

static struct PyModuleDef moduledef = {
 PyModuleDef_HEAD_INIT,
 &quot;myextension&quot;,
 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 &gt;= 3
 PyObject *module = PyModule_Create(&amp;moduledef);
#else
 PyObject *module = Py_InitModule(&quot;myextension&quot;, myextension_methods);
#endif

if (module == NULL)
 INITERROR;
 struct module_state *st = GETSTATE(module);

st-&gt;error = PyErr_NewException(&quot;myextension.Error&quot;, NULL, NULL);
 if (st-&gt;error == NULL) {
 Py_DECREF(module);
 INITERROR;
 }

#if PY_MAJOR_VERSION &gt;= 3
 return module;
#endif
}
</pre></div>
</div>
</div>
<div class="section" id="other-options">
<h2>Other options<a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h2>
If you are writing a new extension module, you might consider <a class="reference external" href="http://www.cython.org">Cython</a>. It translates a Python-like language to C. The
extension modules it creates are compatible with Python 3.x and 2.x.
</div>
</div>

</div>
 </div>
 </div>
 <div class="sphinxsidebar">
 <div class="sphinxsidebarwrapper">
 <h3><a href="../contents.html">Table Of Contents</a></h3>
 <ul>
<li><a class="reference external" href="#">Porting Extension Modules to 3.0</a><ul>
<li><a class="reference external" href="#conditional-compilation">Conditional compilation</a></li>
<li><a class="reference external" href="#changes-to-object-apis">Changes to Object APIs</a><ul>
<li><a class="reference external" href="#str-unicode-unification">str/unicode Unification</a></li>
<li><a class="reference external" href="#long-int-unification">long/int Unification</a></li>
</ul>
</li>
<li><a class="reference external" href="#module-initialization-and-state">Module initialization and state</a></li>
<li><a class="reference external" href="#other-options">Other options</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="advocacy.html"
 title="previous chapter">Python Advocacy HOWTO</a>
 <h4>Next topic</h4>
 <a href="curses.html"
 title="next chapter">Curses Programming with Python</a>
<h3>This Page</h3>
<ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li><a href="../_sources/howto/cporting.txt"
 rel="nofollow">Show Source</a></li>
</ul>

<div id="searchbox" style="display: none">
 <h3>Quick search</h3>
 <form class="search" action="../search.html" method="get">
 <input type="text" name="q" size="18" />
 <input type="submit" value="Go" />
 <input type="hidden" name="check_keywords" value="yes" />
 <input type="hidden" name="area" value="default" />
 </form>
 
 Enter search terms or a module, class or function name.
 
 </div>
 <script type="text/javascript">$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../modindex.html" title="Global Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="curses.html" title="Curses Programming with Python"
 >next</a> |</li>
 <li class="right" >
 <a href="advocacy.html" title="Python Advocacy HOWTO"
 >previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="../index.html">Python v2.6.6 documentation</a> &raquo;</li>

<li><a href="index.html" >Python HOWTOs</a> &raquo;</li> 
 </ul>
 </div>
 <div class="footer">
 &copy; <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation.
 
 The Python Software Foundation is a non-profit corporation. 
 <a href="http://www.python.org/psf/donations/">Please donate.</a>
 
 Last updated on Jul 20, 2011.
 <a href="../bugs.html">Found a bug</a>?
 
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.6.
 </div>

</body>
</html>

Back to File Manager