Cython Generation

Generates a Cython wrappers from description dictionaries. This module relies heavily on the type system to convert between C/C++, Cython, and Python types in a seamless way. While this module does not explicitly rely on the auto-describer, it sure helps! The functions in this module are conceptually easy to understand – given class descriptions they generate strings of Cython code – their implementations do a lot of heavy lifting.

This module is available as an xdress plugin by the name xdress.cythongen. Note that while the module does not rely on the autodescriber, the plugin does.

author:Anthony Scopatz <scopatz@gmail.com>

Cython Generation API

class xdress.cythongen.XDressPlugin

The main cython generator plugin.

The __init__() method may take no arguments or keyword arguments.

requires = ('xdress.autodescribe',)

This plugin requires autodescribe.

xdress.cythongen.classcpppxd(desc, exceptions=True, ts=None)

Generates a cpp_*.pxd Cython header snippet for exposing a C/C++ class or struct to other Cython wrappers based off of a dictionary description of the class or struct.

Parameters:

desc : dict

Class description dictonary.

exceptions : bool or str, optional

Cython exception annotation. Set to True to automatically detect exception types, False for when exceptions should not be included, and a str (such as ‘+’ or ‘-1’) to apply to everywhere.

ts : TypeSystem, optional

A type system instance.

Returns:

cimport_tups : set of tuples

Set of Cython cimport tuples for cpp_*.pxd header file.

cpppxd : str

Cython cpp_*.pxd header file as in-memory string.

xdress.cythongen.classpxd(desc, classes=(), ts=None, max_callbacks=8)

Generates a *pxd Cython header snippet for exposing a C/C++ class to other Cython wrappers based off of a dictionary description.

Parameters:

desc : dict

Class description dictonary.

classes : sequence, optional

Listing of all class names that are handled by cythongen. This may be the same dictionary as in modpyx().

ts : TypeSystem, optional

A type system instance.

max_callbacks : int, optional

The default maximum number of callbacks for function pointers.

Returns:

cimport_tups : set of tuples

Set of Cython cimport tuples for .pxd header file.

pxd : str

Cython *.pxd header snippet for class.

xdress.cythongen.classpyx(desc, classes=None, ts=None, max_callbacks=8)

Generates a *.pyx Cython wrapper implementation for exposing a C/C++ class based off of a dictionary description. The environment is a dictionary of all class names known to their descriptions.

Parameters:

desc : dict

Class description dictonary.

classes : dict, optional

Dictionary which maps all class names that are required to their own descriptions. This is required for resolving class heirarchy dependencies.

ts : TypeSystem, optional

A type system instance.

max_callbacks : int, optional

The default maximum number of callbacks for function pointers.

Returns:

pyx : str

Cython *.pyx implementation file as in-memory string.

xdress.cythongen.cpppxd_sorted_names(mod, ts)

Sorts the variable names in a cpp_*.pxd module so that C/C++ declarations happen in the proper order.

xdress.cythongen.funccpppxd(desc, exceptions=True, ts=None)

Generates a cpp_*.pxd Cython header snippet for exposing a C/C++ function to other Cython wrappers based off of a dictionary description.

Parameters:

desc : dict

Function description dictonary.

exceptions : bool or str, optional

Cython exception annotation. Set to True to automatically detect exception types, False for when exceptions should not be included, and a str (such as ‘+’ or ‘-1’) to apply to everywhere.

ts : TypeSystem, optional

A type system instance.

Returns:

cimport_tups : set of tuples

Set of Cython cimport tuples for cpp_*.pxd header file.

cpppxd : str

Cython cpp_*.pxd header file as in-memory string.

xdress.cythongen.funcpyx(desc, ts=None)

Generates a *.pyx Cython wrapper implementation for exposing a C/C++ function based off of a dictionary description.

Parameters:

desc : dict

function description dictonary.

ts : TypeSystem, optional

A type system instance.

Returns:

pyx : str

Cython *.pyx implementation as in-memory string.

xdress.cythongen.gencpppxd(env, exceptions=True, ts=None)

Generates all cpp_*.pxd Cython header files for an environment of modules.

Parameters:

env : dict

Environment dictonary mapping target module names to module description dictionaries.

exceptions : bool or str, optional

Cython exception annotation. Set to True to automatically detect exception types, False for when exceptions should not be included, and a str (such as ‘+’ or ‘-1’) to apply to everywhere.

ts : TypeSystem, optional

A type system instance.

Returns:

cpppxds : dict

Maps environment target names to Cython cpp_*.pxd header files strings.

xdress.cythongen.genpxd(env, classes=(), ts=None, max_callbacks=8)

Generates all pxd Cython header files for an environment of modules.

Parameters:

env : dict

Environment dictonary mapping target module names to module description dictionaries.

classes : sequence, optional

Listing of all class names that are handled by cythongen. This may be the same dictionary as in genpyx()

ts : TypeSystem, optional

A type system instance.

max_callbacks : int, optional

The default maximum number of callbacks for function pointers.

Returns:

pxds : str

Maps environment target names to Cython pxd header files strings.

xdress.cythongen.genpyx(env, classes=None, ts=None, max_callbacks=8)

Generates all pyx Cython implementation files for an environment of modules.

Parameters:

env : dict

Environment dictonary mapping target module names to module description dictionaries.

classes : dict, optional

Dictionary which maps all class names that are required to their own descriptions. This is required for resolving class heirarchy dependencies. If None, this will be computed here.

ts : TypeSystem, optional

A type system instance.

max_callbacks : int, optional

The default maximum number of callbacks for function pointers.

Returns:

pyxs : str

Maps environment target names to Cython pxd header files strings.

xdress.cythongen.modcpppxd(mod, exceptions=True, ts=None)

Generates a cpp_*.pxd Cython header file for exposing a C/C++ module to other Cython wrappers based off of a dictionary description of the module.

Parameters:

mod : dict

Module description dictonary.

exceptions : bool or str, optional

Cython exception annotation. Set to True to automatically detect exception types, False for when exceptions should not be included, and a str (such as ‘+’ or ‘-1’) to apply to everywhere.

ts : TypeSystem, optional

A type system instance.

Returns:

cpppxd : str

Cython cpp_*.pxd header file as in-memory string.

xdress.cythongen.modpxd(mod, classes=(), ts=None, max_callbacks=8)

Generates a pxd Cython header file for exposing C/C++ data to other Cython wrappers based off of a dictionary description.

Parameters:

mod : dict

Module description dictonary.

classes : sequence, optional

Listing of all class names that are handled by cythongen. This may be the same dictionary as in modpyx().

ts : TypeSystem, optional

A type system instance.

max_callbacks : int, optional

The default maximum number of callbacks for function pointers.

Returns:

pxd : str

Cython .pxd header file as in-memory string.

xdress.cythongen.modpyx(mod, classes=None, ts=None, max_callbacks=8)

Generates a pyx Cython implementation file for exposing C/C++ data to other Cython wrappers based off of a dictionary description.

Parameters:

mod : dict

Module description dictonary.

classes : dict, optional

Dictionary which maps all class names that are required to their own descriptions. This is required for resolving class heirarchy dependencies.

ts : TypeSystem, optional

A type system instance.

max_callbacks : int, optional

The default maximum number of callbacks for function pointers.

Returns:

pyx : str

Cython pyx header file as in-memory string.

xdress.cythongen.pxd_sorted_names(mod)

Sorts the names in a module to make sure that pxd declarations happen in the proper order.

xdress.cythongen.varcpppxd(desc, exceptions=True, ts=None)

Generates a cpp_*.pxd Cython header snippet for exposing a C/C++ variable to other Cython wrappers based off of a dictionary description.

Parameters:

desc : dict

Function description dictonary.

exceptions : bool or str, optional

Cython exception annotation. Set to True to automatically detect exception types, False for when exceptions should not be included, and a str (such as ‘+’ or ‘-1’) to apply to everywhere.

ts : TypeSystem, optional

A type system instance.

Returns:

cimport_tups : set of tuples

Set of Cython cimport tuples for cpp_*.pxd header file.

cpppxd : str

Cython cpp_*.pxd header file as in-memory string.

xdress.cythongen.varpyx(desc, ts=None)

Generates a *.pyx Cython wrapper implementation for exposing a C/C++ variable based off of a dictionary description.

Parameters:

desc : dict

Variable description dictonary.

ts : TypeSystem, optional

A type system instance.

Returns:

pyx : str

Cython *.pyx implementation as in-memory string.