cffi

cffi lets Python code call into C libraries and write C extensions using C-like declarations instead of hand-written CPython C-API boilerplate. It supports two complementary modes: ABI mode, which calls a shared library at runtime via dlopen/LoadLibrary without a C compiler, and API mode, which generates and compiles a small C extension ahead of time for better performance and static-linking-friendly deployment.

Because it targets both CPython and PyPy, cffi is the de facto standard binding layer used by many popular packages that wrap native libraries — most notably cryptography, but also numerous packages needing to talk to system libraries, compression codecs, or other C dependencies without maintaining separate CPython/PyPy C-extension code paths.

What You Get

• An FFI() object with cdef() for declaring C function signatures, types, and structs using ordinary C syntax
• ABI mode (dlopen) for calling into a shared library at runtime with no C compiler required
• API mode (set_source() + compile()) for generating and building a small C extension ahead of time for speed and packaging
• A setuptools_ext integration that plugs cffi’s build step directly into a package’s setup.py
• Support for both CPython and PyPy, with a backend_ctypes fallback implementation
• A C parser (cparser.py) that understands a practical subset of C declaration syntax without needing the real system headers

Common Use Cases

• Wrapping an existing C library (crypto, compression, system, or vendor SDK) so it can be called from Python with type-checked signatures
• Building a package that must run on both CPython and PyPy without maintaining two separate native-extension implementations
• Serving as the low-level binding layer underneath a higher-level Python package (e.g. cryptography) that needs OpenSSL or similar native code
• Calling into a system shared library at runtime (ABI mode) in environments where compiling a C extension isn’t practical

Under The Hood

Architecture: The package splits cleanly between a Python-level declaration/parsing layer and a native execution layer. src/cffi/cparser.py implements a purpose-built parser for the subset of C declaration syntax needed by cdef(), translating parsed C types into an internal model.py type-graph (structs, pointers, function signatures). src/cffi/recompiler.py and src/cffi/vengine_cpy.py/vengine_gen.py drive API-mode code generation, emitting and compiling a real C extension module against a bundled/system libffi (src/c/libffi_x86_x64, src/c/libffi_arm64 vendor prebuilt libffi binaries for common architectures) for ABI-mode calls when no C source is generated. src/cffi/api.py exposes the public FFI class that ties declaration, compilation, and dynamic-library loading together, while backend_ctypes.py provides a pure-Python (no C compiler) fallback backend built on the standard-library ctypes module for restricted environments. Tech Stack: Python 3.10+, with pycparser as the sole runtime dependency on CPython (PyPy ships its own built-in cffi backend so the dependency is conditionally excluded there); the project vendors precompiled libffi binaries for x86/x64 and arm64 rather than requiring a system libffi install on those platforms; build tooling is setuptools (PEP 639-compliant pyproject.toml) with a custom setup_base.py/setup.py for the native-extension build step. Code Quality: The testing/ directory contains 89 files covering ABI mode, API mode, the ctypes backend, embedding, and edge cases in the C parser, run via pytest src/c/ testing/ per the README’s own documented workflow; CI runs across CPython 3.10–3.15 (including free-threaded builds per suppressions_free_threading.txt) and PyPy, reflecting the cross-implementation compatibility burden this project has carried for over a decade. API Design: The core workflow — write a cdef() C declaration block, call either dlopen() (ABI) or set_source()+compile() (API) — is intentionally close to how a C programmer already thinks about headers and linking, which keeps the learning curve low for anyone with C experience, though the ABI-vs-API mode distinction and libffi packaging details add real depth for anyone shipping a compiled extension across platforms.