Goals

The interface is based on LuaJIT’s FFI, and follows a few principles:

  • The goal is to call C code from Python without learning a 3rd language: existing alternatives require users to learn domain specific language (Cython, SWIG) or API (ctypes). The CFFI design requires users to know only C and Python, minimizing the extra bits of API that need to be learned.

  • Keep all the Python-related logic in Python so that you don’t need to write much C code (unlike CPython native C extensions).

  • The preferred way is to work at the level of the API (Application Programming Interface): the C compiler is called from the declarations you write to validate and link to the C language constructs. Alternatively, it is also possible to work at the ABI level (Application Binary Interface), the way ctypes work. However, on non-Windows platforms, C libraries typically have a specified C API but not an ABI (e.g. they may document a “struct” as having at least these fields, but maybe more).

  • Try to be complete. For now some C99 constructs are not supported, but all C89 should be, including macros (and including macro “abuses”, which you can manually wrap in saner-looking C functions).

  • Attempt to support both PyPy and CPython, with a reasonable path for other Python implementations like IronPython and Jython.

  • Note that this project is not about embedding executable C code in Python, unlike Weave. This is about calling existing C libraries from Python.

  • There is no C++ support. Sometimes, it is reasonable to write a C wrapper around the C++ code and then call this C API with CFFI. Otherwise, look at other projects. I would recommend cppyy, which has got some similarities (and also works efficiently on both CPython and PyPy).

Get started by reading the overview.

Comments and bugs

The best way to contact us is on the IRC #cffi or #pypy channels of irc.libera.chat. Feel free to discuss matters either there or in the mailing list. Please report to the issue tracker any bugs.

As a general rule, when there is a design issue to resolve, we pick the solution that is the “most C-like”. We hope that this module has got everything you need to access C code and nothing more.

— the authors, Armin Rigo and Maciej Fijalkowski