Traditionally, the C API of Python will change with every release. Most changes

will be source-compatible, typically by only adding API, rather than changing

existing API or removing API (although some interfaces do get removed after

being deprecated first).

Unfortunately, the API compatibility does not extend to binary compatibility

(the ABI). The reason is primarily the evolution of struct definitions, where

addition of a new field, or changing the type of a field, might not break the

API, but can break the ABI. As a consequence, extension modules need to be

recompiled for every Python release (although an exception is possible on Unix

when none of the affected interfaces are used). In addition, on Windows,

extension modules link with a specific pythonXY.dll and need to be recompiled to

link with a newer one.

Since Python 3.2, a subset of the API has been declared to guarantee a stable

ABI. Extension modules wishing to use this API (called "limited API") need to

define ``Py_LIMITED_API``. A number of interpreter details then become hidden

from the extension module; in return, a module is built that works on any 3.x

version (x>=2) without recompilation.

Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API``

to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python

version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules

will work on all subsequent Python releases, but fail to load (because of

As of Python 3.2, the set of functions available to the limited API is

documented in PEP 384. In the C API documentation, API elements that are not

part of the limited API are marked as "Not part of the limited API."

extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',

'pyspecific', 'c_annotations']

from os import path

from docutils import nodes

from docutils.parsers.rst import directives

from sphinx import addnodes

from sphinx.domains.c import CObject

class RCEntry:

def __init__(self, name):

self.name = name

self.args = []

self.result_type = ''

self.result_refs = None

class Annotations(dict):

@classmethod

def fromfile(cls, filename):

d = cls()

fp = open(filename, 'r')

try:

for line in fp:

line = line.strip()

if line[:1] in ("", "#"):

# blank lines and comments

continue

parts = line.split(":", 4)

if len(parts) != 5:

raise ValueError("Wrong field count in %r" % line)

function, type, arg, refcount, comment = parts

# Get the entry, creating it if needed:

try:

entry = d[function]

except KeyError:

entry = d[function] = RCEntry(function)

if not refcount or refcount == "null":

refcount = None

else:

refcount = int(refcount)

# Update the entry with the new parameter or the result

# information.

if arg:

entry.args.append((arg, type, refcount))

else:

entry.result_type = type

entry.result_refs = refcount

finally:

fp.close()

return d

def add_annotations(self, app, doctree):

for node in doctree.traverse(addnodes.desc_content):

par = node.parent

if par['domain'] != 'c':

continue

if par['notlimited']:

node.insert(0, nodes.emphasis(' Not part of the stable API.',

' Not part of the stable API.',

classes=['notlimited']))

if par['objtype'] != 'function':

continue

if not par[0].has_key('names') or not par[0]['names']:

continue

entry = self.get(par[0]['names'][0])

if not entry:

continue

elif entry.result_type not in ("PyObject*", "PyVarObject*"):

continue

if entry.result_refs is None:

rc = 'Return value: Always NULL.'

elif entry.result_refs:

rc = 'Return value: New reference.'

else:

rc = 'Return value: Borrowed reference.'

node.insert(0, nodes.emphasis(rc, rc, classes=['refcount']))

def init_annotations(app):

refcounts = Annotations.fromfile(

path.join(app.srcdir, app.config.refcount_file))

app.connect('doctree-read', refcounts.add_annotations)

def setup(app):

app.add_config_value('refcount_file', '', True)

app.connect('builder-inited', init_annotations)

# monkey-patch C object...

CObject.option_spec = {

'noindex': directives.flag,

'notlimited': directives.flag,

}

old_handle_signature = CObject.handle_signature

def new_handle_signature(self, sig, signode):

signode.parent['notlimited'] = 'notlimited' in self.options

return old_handle_signature(self, sig, signode)

CObject.handle_signature = new_handle_signature

.refcount {

color: #060;

}

.notlimited {

color: #922;

}