Typing Stubs for cffi

Warnings

• gotcha Installing `types-cffi` does not install the `cffi` runtime library. `types-cffi` only provides type annotations. You must install `cffi` separately (e.g., `pip install cffi`) for your code to run.
  Fix: Ensure both `pip install types-cffi` and `pip install cffi` are executed.
• breaking `types-cffi` versions are aligned with `cffi` runtime versions. For example, `types-cffi==2.0.x.YYYYMMDD` provides stubs for `cffi==2.0.*`. Using significantly mismatched versions (e.g., `types-cffi` for `cffi` 2.0 with a `cffi` 1.x runtime) can lead to incorrect type checking results or missed errors.
  Fix: Keep `types-cffi` and `cffi` versions in sync, ideally pinning both to compatible major/minor versions. Refer to typeshed documentation for specific compatibility.
• deprecated The behavior of `ffi.new_handle()` changed in `cffi` v1.3.1 to guarantee unique `void *` values, even when called on the same object multiple times. Code relying on previous CPython behavior (where it might return two `cdata` objects with the same `void *` value) could break if not keeping the result of `ffi.new_handle()` alive explicitly.
  Fix: Always ensure the Python object returned by `ffi.new_handle()` is kept alive for as long as the C `void *` value might be used. Review code for explicit handle management.
• breaking For `cffi` projects targeting Python 3.12 and newer, if they utilize `cffi` features that historically depended on `distutils` (which was removed in Python 3.12), they must explicitly add `setuptools` as a dependency. `cffi` itself does not add this runtime dependency to avoid unnecessary installs for projects that don't need it.
  Fix: Add `setuptools` to your project's `install_requires` if you build `cffi` extensions that previously relied on `distutils` functionality with Python 3.12 or newer.
• gotcha While typeshed aims to minimize breaking changes in stubs, any update to `types-cffi` (or any `types-*` package) can introduce changes that might cause your code to fail type checking, even if the runtime behavior of `cffi` hasn't changed. This is inherent to the evolving nature of type annotations.
  Fix: Consider pinning `types-cffi` to a known good version in your `requirements.txt` (e.g., `types-cffi==2.0.0.20260402`) and update it periodically, or use version ranges that align with `cffi`'s compatibility.

Install

• pip install types-cffi Install types-cffi
• pip install cffi Install cffi runtime (required)

Imports

• FFI

  from cffi import FFI

  types-cffi provides stubs for the 'cffi' library; you do not directly import from 'types-cffi'.
• lib

  from cffi import lib

  types-cffi provides stubs for the 'cffi' library; you do not directly import from 'types-cffi'.

Quickstart

This quickstart demonstrates a basic usage of `cffi` to call a C standard library function, `puts`. When `types-cffi` is installed, a static type checker will provide type hints for `ffi`, `lib`, and other `cffi` objects, helping to catch type-related errors at development time. The example intentionally avoids platform-specific library loading to be more general, using `ffi.dlopen(None)` for Unix-like systems to access the standard C library.

import os
from cffi import FFI

# Initialize FFI
ffi = FFI()

# Declare C functions (e.g., from the standard C library)
ffi.cdef("""int puts(const char* s);""")

# Load the C library (None on Unix-like systems typically opens libc)
try:
    libc = ffi.dlopen(None) # type: ignore
except OSError:
    print("Could not load libc. This example might not run on all systems.\n"\
          "Ensure a C standard library is available and discoverable.")
    exit(1)

# Call a C function with type checking (implicitly using types-cffi)
message = ffi.new("char[]", b"Hello from C via CFFI and types-cffi!")
return_code = libc.puts(message)

print(f"C puts() returned: {return_code}")

# Example of type checking at development time:
# If you misspelled 'puts' or passed an int instead of bytes, 
# a type checker (like MyPy) would flag it due to types-cffi.