cexi 0.0.3

Cee EXtensions Interpolation

Cee EXtensions Interpolation

Rationale

cexi aims to facilitate developing of C extension for CPython. In particular interfacing between python and C. In general building C extensions is a tedious process, especially when it comes to interfacing between two languages. cexi aims to make it easier by providing a simple interface to write C extensions in a pythonic way. It's not a replacement for Cython, CFFI, SWIG, Boost.Python or PyBind11, but rather a tool to make writing C extensions easier. It's main features are:

• pythonic interface to write C extensions
• automatic re/compilation of C extensions
• automatic loading of C extensions

Code example

from cexi import Module, s

class Foo(Module):

    class options:
        flags = ['-O3']

    """
    #include "stdio.h"
    """

    @s.cee
    def foo(x: int) -> int:
        """
        return x + 1;
        """

    @s.share
    def bar(self, x: int) -> int:
        return x ** 2

    @s.py
    def baz(x: int, y: int) -> (int, int):
        """
        printf("baz\\n");
        int ret = x + y;
        bar(ret, &ret);
        return(foo(x + y), ret);
        """

    def wrapped_baz(self, x, y):
        print(f'calling {self.baz}')
        return self.baz(x, y)

Foo().foo(1)  # => 2
ret = Foo().wrapped_baz(3, 4) # => prints
                              # calling <cexi.proxy.Proxy object at 0x7f4bae56cf10>
                              # baz

print(ret)  # => prints (8, 49)


class Foo(Module, near=__file__):
    pass


class Foo(Module):
    directory = Path('/some/path')

Breakdown

Each extension begins with a class definition that inherits from cexi.Module. User can define flags that will be passed to compiler via options class attribute.

class Foo(Module):

    class options:
        flags = ['-O3']

Module docstring is directly inserted at the beginning of cee extension. It's useful to include headers that will be used in extension's code.

class Foo(Module):
    """
    #include "stdio.h"
    """

Then user can define functions that will be compiled as extension's functions. There are three types of functions:

• @s.cee - plain cee function, it's useful to organize plain cee routines. .cee functions aren't available for use in python, they're simply excluded from final class namespace
• @s.share - .share is a plain python function that is added to module to be used in cee code it's signature is transformed as such: func([input parameters]) -> <output parameters> => int func([input parameters], [pointers to output parameters]) e.g. bar here becomes int bar(int x, int *a), it returns non-zero value on failure & modify pointer to the return value
• @s.py - .py is a cee extension function. it's available from python & can use both .cee & .share functions at will Untagged functions are left untouched, i.e. they're just instance's methods. cexi.Module children act as singletones - on instantiation they're get loaded/compiled by default they are built inside temporaty directories, but users are able to make modules persistent. There are two ways to do it:
• near parameter - if it's set to __file__ module will be built in directory at __file__/../<module name>_cexi_module
• directory class attribute - if it's set module will be built in specified directory

Persistent extensions compiled on-demand. If extension is persistent cexi first loads it's module. Then it compares revisions, which are hashed module's contents. Thus if class definition is changed since last compilation it will be re-compiled and re-loaded.

You can also compile persistent extensions with command

python -mcexi <module path>:<class name>

Installation

pip install cexi