<!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 — Python v3.2.2 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: '3.2.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v3.2.2 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 v3.2.2 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="Porting Python 2 Code to Python 3" href="pyporting.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="../py-modindex.html" title="Python Module Index"
>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="pyporting.html" title="Porting Python 2 Code to Python 3"
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 v3.2.2 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Python HOWTOs</a> »</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">
<span id="cporting-howto"></span><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">
<p class="topic-title first">Abstract</p>
<p>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 <a class="reference internal" href="../library/functions.html#int" title="int"><tt class="xref py py-func docutils literal"><span class="pre">int()</span></tt></a> and <tt class="xref py py-func docutils literal"><span class="pre">long()</span></tt> unification are more obvious on
the C level. This document endeavors to document incompatibilities and how
they can be worked around.</p>
</div>
<div class="section" id="conditional-compilation">
<h2>Conditional compilation<a class="headerlink" href="#conditional-compilation" title="Permalink to this headline">¶</a></h2>
<p>The easiest way to compile only some code for 3.0 is to check if
<tt class="xref c c-macro docutils literal"><span class="pre">PY_MAJOR_VERSION</span></tt> is greater than or equal to 3.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if PY_MAJOR_VERSION >= 3</span>
<span class="cp">#define IS_PY3K</span>
<span class="cp">#endif</span>
</pre></div>
</div>
<p>API functions that are not present can be aliased to their equivalents within
conditional blocks.</p>
</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>
<p>Python 3.0 merged together some types with similar functions while cleanly
separating others.</p>
<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>
<p>Python 3.0’s <a class="reference internal" href="../library/functions.html#str" title="str"><tt class="xref py py-func docutils literal"><span class="pre">str()</span></tt></a> (<tt class="docutils literal"><span class="pre">PyString_*</span></tt> functions in C) type is equivalent to
2.x’s <tt class="xref py py-func docutils literal"><span class="pre">unicode()</span></tt> (<tt class="docutils literal"><span class="pre">PyUnicode_*</span></tt>). The old 8-bit string type has become
<a class="reference internal" href="../library/functions.html#bytes" title="bytes"><tt class="xref py py-func docutils literal"><span class="pre">bytes()</span></tt></a>. Python 2.6 and later provide a compatibility header,
<tt class="file docutils literal"><span class="pre">bytesobject.h</span></tt>, mapping <tt class="docutils literal"><span class="pre">PyBytes</span></tt> names to <tt class="docutils literal"><span class="pre">PyString</span></tt> ones. For best
compatibility with 3.0, <tt class="xref c c-type docutils literal"><span class="pre">PyUnicode</span></tt> should be used for textual data and
<tt class="xref c c-type docutils literal"><span class="pre">PyBytes</span></tt> for binary data. It’s also important to remember that
<tt class="xref c c-type docutils literal"><span class="pre">PyBytes</span></tt> and <tt class="xref c c-type docutils literal"><span class="pre">PyUnicode</span></tt> in 3.0 are not interchangeable like
<tt class="xref c c-type docutils literal"><span class="pre">PyString</span></tt> and <tt class="xref c c-type docutils literal"><span class="pre">PyUnicode</span></tt> are in 2.x. The following example
shows best practices with regards to <tt class="xref c c-type docutils literal"><span class="pre">PyUnicode</span></tt>, <tt class="xref c c-type docutils literal"><span class="pre">PyString</span></tt>,
and <tt class="xref c c-type docutils literal"><span class="pre">PyBytes</span></tt>.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include "stdlib.h"</span>
<span class="cp">#include "Python.h"</span>
<span class="cp">#include "bytesobject.h"</span>
<span class="cm">/* text example */</span>
<span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
<span class="nf">say_hello</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">name</span><span class="p">,</span> <span class="o">*</span><span class="n">result</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PyArg_ParseTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"U:say_hello"</span><span class="p">,</span> <span class="o">&</span><span class="n">name</span><span class="p">))</span>
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">PyUnicode_FromFormat</span><span class="p">(</span><span class="s">"Hello, %S!"</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span>
<span class="k">return</span> <span class="n">result</span><span class="p">;</span>
<span class="p">}</span>
<span class="cm">/* just a forward */</span>
<span class="k">static</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">do_encode</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">);</span>
<span class="cm">/* bytes example */</span>
<span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
<span class="nf">encode_object</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">encoded</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">result</span><span class="p">,</span> <span class="o">*</span><span class="n">myobj</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PyArg_ParseTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"O:encode_object"</span><span class="p">,</span> <span class="o">&</span><span class="n">myobj</span><span class="p">))</span>
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">encoded</span> <span class="o">=</span> <span class="n">do_encode</span><span class="p">(</span><span class="n">myobj</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">encoded</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">PyBytes_FromString</span><span class="p">(</span><span class="n">encoded</span><span class="p">);</span>
<span class="n">free</span><span class="p">(</span><span class="n">encoded</span><span class="p">);</span>
<span class="k">return</span> <span class="n">result</span><span class="p">;</span>
<span class="p">}</span>
</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>
<p>In Python 3.0, there is only one integer type. It is called <a class="reference internal" href="../library/functions.html#int" title="int"><tt class="xref py py-func docutils literal"><span class="pre">int()</span></tt></a> on the
Python level, but actually corresponds to 2.x’s <tt class="xref py py-func docutils literal"><span class="pre">long()</span></tt> type. In the
C-API, <tt class="docutils literal"><span class="pre">PyInt_*</span></tt> functions are replaced by their <tt class="docutils literal"><span class="pre">PyLong_*</span></tt> neighbors. The
best course of action here is using the <tt class="docutils literal"><span class="pre">PyInt_*</span></tt> functions aliased to
<tt class="docutils literal"><span class="pre">PyLong_*</span></tt> found in <tt class="file docutils literal"><span class="pre">intobject.h</span></tt>. The abstract <tt class="docutils literal"><span class="pre">PyNumber_*</span></tt> APIs
can also be used in some cases.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include "Python.h"</span>
<span class="cp">#include "intobject.h"</span>
<span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
<span class="nf">add_ints</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">int</span> <span class="n">one</span><span class="p">,</span> <span class="n">two</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">result</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PyArg_ParseTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"ii:add_ints"</span><span class="p">,</span> <span class="o">&</span><span class="n">one</span><span class="p">,</span> <span class="o">&</span><span class="n">two</span><span class="p">))</span>
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="k">return</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="n">one</span> <span class="o">+</span> <span class="n">two</span><span class="p">);</span>
<span class="p">}</span>
</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>
<p>Python 3.0 has a revamped extension module initialization system. (See
<span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-3121"><strong>PEP 3121</strong></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.</p>
<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include "Python.h"</span>
<span class="k">struct</span> <span class="n">module_state</span> <span class="p">{</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">error</span><span class="p">;</span>
<span class="p">};</span>
<span class="cp">#if PY_MAJOR_VERSION >= 3</span>
<span class="cp">#define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))</span>
<span class="cp">#else</span>
<span class="cp">#define GETSTATE(m) (&_state)</span>
<span class="k">static</span> <span class="k">struct</span> <span class="n">module_state</span> <span class="n">_state</span><span class="p">;</span>
<span class="cp">#endif</span>
<span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
<span class="nf">error_out</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">m</span><span class="p">)</span> <span class="p">{</span>
<span class="k">struct</span> <span class="n">module_state</span> <span class="o">*</span><span class="n">st</span> <span class="o">=</span> <span class="n">GETSTATE</span><span class="p">(</span><span class="n">m</span><span class="p">);</span>
<span class="n">PyErr_SetString</span><span class="p">(</span><span class="n">st</span><span class="o">-></span><span class="n">error</span><span class="p">,</span> <span class="s">"something bad happened"</span><span class="p">);</span>
<span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">static</span> <span class="n">PyMethodDef</span> <span class="n">myextension_methods</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
<span class="p">{</span><span class="s">"error_out"</span><span class="p">,</span> <span class="p">(</span><span class="n">PyCFunction</span><span class="p">)</span><span class="n">error_out</span><span class="p">,</span> <span class="n">METH_NOARGS</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">},</span>
<span class="p">{</span><span class="nb">NULL</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">}</span>
<span class="p">};</span>
<span class="cp">#if PY_MAJOR_VERSION >= 3</span>
<span class="k">static</span> <span class="kt">int</span> <span class="nf">myextension_traverse</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">m</span><span class="p">,</span> <span class="n">visitproc</span> <span class="n">visit</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">arg</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Py_VISIT</span><span class="p">(</span><span class="n">GETSTATE</span><span class="p">(</span><span class="n">m</span><span class="p">)</span><span class="o">-></span><span class="n">error</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">static</span> <span class="kt">int</span> <span class="nf">myextension_clear</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">m</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Py_CLEAR</span><span class="p">(</span><span class="n">GETSTATE</span><span class="p">(</span><span class="n">m</span><span class="p">)</span><span class="o">-></span><span class="n">error</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
<span class="k">static</span> <span class="k">struct</span> <span class="n">PyModuleDef</span> <span class="n">moduledef</span> <span class="o">=</span> <span class="p">{</span>
<span class="n">PyModuleDef_HEAD_INIT</span><span class="p">,</span>
<span class="s">"myextension"</span><span class="p">,</span>
<span class="nb">NULL</span><span class="p">,</span>
<span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">module_state</span><span class="p">),</span>
<span class="n">myextension_methods</span><span class="p">,</span>
<span class="nb">NULL</span><span class="p">,</span>
<span class="n">myextension_traverse</span><span class="p">,</span>
<span class="n">myextension_clear</span><span class="p">,</span>
<span class="nb">NULL</span>
<span class="p">};</span>
<span class="cp">#define INITERROR return NULL</span>
<span class="n">PyObject</span> <span class="o">*</span>
<span class="n">PyInit_myextension</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span>
<span class="cp">#else</span>
<span class="cp">#define INITERROR return</span>
<span class="kt">void</span>
<span class="n">initmyextension</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span>
<span class="cp">#endif</span>
<span class="p">{</span>
<span class="cp">#if PY_MAJOR_VERSION >= 3</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">module</span> <span class="o">=</span> <span class="n">PyModule_Create</span><span class="p">(</span><span class="o">&</span><span class="n">moduledef</span><span class="p">);</span>
<span class="cp">#else</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">module</span> <span class="o">=</span> <span class="n">Py_InitModule</span><span class="p">(</span><span class="s">"myextension"</span><span class="p">,</span> <span class="n">myextension_methods</span><span class="p">);</span>
<span class="cp">#endif</span>
<span class="k">if</span> <span class="p">(</span><span class="n">module</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="n">INITERROR</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">module_state</span> <span class="o">*</span><span class="n">st</span> <span class="o">=</span> <span class="n">GETSTATE</span><span class="p">(</span><span class="n">module</span><span class="p">);</span>
<span class="n">st</span><span class="o">-></span><span class="n">error</span> <span class="o">=</span> <span class="n">PyErr_NewException</span><span class="p">(</span><span class="s">"myextension.Error"</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">st</span><span class="o">-></span><span class="n">error</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">module</span><span class="p">);</span>
<span class="n">INITERROR</span><span class="p">;</span>
<span class="p">}</span>
<span class="cp">#if PY_MAJOR_VERSION >= 3</span>
<span class="k">return</span> <span class="n">module</span><span class="p">;</span>
<span class="cp">#endif</span>
<span class="p">}</span>
</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>
<p>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.</p>
</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 internal" href="#">Porting Extension Modules to 3.0</a><ul>
<li><a class="reference internal" href="#conditional-compilation">Conditional compilation</a></li>
<li><a class="reference internal" href="#changes-to-object-apis">Changes to Object APIs</a><ul>
<li><a class="reference internal" href="#str-unicode-unification">str/unicode Unification</a></li>
<li><a class="reference internal" href="#long-int-unification">long/int Unification</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-initialization-and-state">Module initialization and state</a></li>
<li><a class="reference internal" href="#other-options">Other options</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="pyporting.html"
title="previous chapter">Porting Python 2 Code to Python 3</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="curses.html"
title="next chapter">Curses Programming with Python</a></p>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</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="../py-modindex.html" title="Python 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="pyporting.html" title="Porting Python 2 Code to Python 3"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" >Python HOWTOs</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Sep 04, 2011.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
