CFFI documentation

C Foreign Function Interface for Python. Interact with almost any C code from Python, based on C-like declarations that you can often copy-paste from header files or documentation.

• Goals
  • Comments and bugs

• What’s New
  • v1.8.3
  • v1.8.2
  • v1.8.1
  • v1.8
  • v1.7
  • v1.6
  • v1.5.2
  • v1.5.1
  • v1.5.0
  • v1.4.2
  • v1.4.1
  • v1.4.0
  • v1.3.1
  • v1.3.0
  • v1.2.1
  • v1.2.0
  • v1.1.2
  • v1.1.1
  • v1.1.0
  • v1.0.3
  • v1.0.2
  • v1.0.1
  • v1.0.0
• Installation and Status
  • Platform-specific instructions
• Overview
  • Simple example (ABI level, in-line)
  • Real example (API level, out-of-line)
  • Struct/Array Example (minimal, in-line)
  • Purely for performance (API level, out-of-line)
  • Out-of-line, ABI level
  • Embedding
  • What actually happened?
  • ABI versus API
• Using the ffi/lib objects
  • Working with pointers, structures and arrays
  • Python 3 support
  • An example of calling a main-like thing
  • Function calls
  • Variadic function calls
  • Extern “Python” (new-style callbacks)
  • Callbacks (old style)
  • Windows: calling conventions
  • FFI Interface
• CFFI Reference
  • FFI Interface
  • Conversions
• Preparing and Distributing modules
  • ffi/ffibuilder.cdef(): declaring types and functions
  • ffi.dlopen(): loading libraries in ABI mode
  • ffibuilder.set_source(): preparing out-of-line modules
  • Letting the C compiler fill the gaps
  • ffibuilder.compile() etc.: compiling out-of-line modules
  • ffi/ffibuilder.include(): combining multiple CFFI interfaces
  • ffi.cdef() limitations
  • Debugging dlopen’ed C libraries
  • ffi.verify(): in-line API-mode
  • Upgrading from CFFI 0.9 to CFFI 1.0
• Using CFFI for embedding
  • Usage
  • More reading
  • Troubleshooting
  • Issues about using the .so
  • Using multiple CFFI-made DLLs
  • Multithreading
  • Testing
  • Embedding and Extending

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.

Get started by reading the overview.

Comments and bugs

The best way to contact us is on the IRC #pypy channel of irc.freenode.net. 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