ADR-0047: Compile ctypes declarations into direct calls linked at build time¶
Status¶
Accepted
Date¶
2026-11-17
Context¶
ADR-0003 decides that a program calls C through the standard ctypes
module, so it runs under CPython too, and that TyPy compiles the
declarations into direct calls. FFI-01 to FFI-04 ask for that in 0.5: a
library named by a string literal is linked when the program is built, a
function declared by its argtypes and restype at module level is
called with the conversions ctypes defines, and typy.toml says whether
a library is linked statically or dynamically. This record covers
libraries, functions and the scalar types; pointers and structures follow
in records of their own.
CPython 3.12 to 3.15 convert alike, measured on 2026-11-17 through
libc.so.6 and libm.so.6:
| Type | Argument | Result |
|---|---|---|
c_int8 to c_uint64, c_int, c_long, c_size_t, c_ssize_t |
An int or a bool, wrapped to the type's width |
The value, signed or unsigned as the type is |
c_bool |
Any value, by its truth | True when the low byte is not zero |
c_float, c_double |
An int, a float or a bool; an int too large for a float raises ctypes.ArgumentError |
A float; c_float rounds through 32 bits |
c_char_p |
bytes, whose own buffer C reads, or None for null |
A copy of the C string as bytes, or None for null |
c_void_p |
An int wrapped to 64 bits, bytes, or None for null |
An int, or None for null |
Any other argument raises ctypes.ArgumentError, whose text 3.15 words
differently for c_char_p. CPython loads a library when CDLL runs and
finds a function when the program first names it, so a missing library is
OSError and a missing function AttributeError, at run time.
Options considered¶
- A
ctypesof the runtime's own:dlopen,dlsymand a call made at run time from the declared types, as CPython'sctypesdoes withlibffi. The program behaves as CPython's does in every case, and every call pays for the dynamic call and the checks. - Declarations compiled with the program. The checker reads each library and each function's declaration from the module, types each call from it, and code generation calls the function directly with the conversions inline; the library is linked when the program is built.
Decision¶
TyPy uses option 2, as ADR-0003 foresees.
- Libraries.
NAME = ctypes.CDLL("library")andNAME = ctypes.cdll.LoadLibrary("library"), at module level with a string literal, under any nameimport ctypes,import ctypes as Corfrom ctypes import CDLL, cdllgives, declare the library, which the build links. A library name that is not a literal, or a library declared other than at module level, is E0430 under FFI-01. - Functions.
NAME.function.argtypesis assigned a list or tuple ofctypestypes, andNAME.function.restypeactypestype orNone, each once, at module level, before any call of the function at module level. A call of a function without both, or one that comes before them, is E0430 under FFI-02. The checker reads the declarations from the module's statements, which then do nothing when the program runs. - Calls.
NAME.function(arguments)takes positional arguments of the types the table gives, checked when the program is compiled: an argument of another type is E0404 and a wrong number of arguments E0404, where CPython raisesctypes.ArgumentError. Ac_boolargument takes any value a truth test takes. Each conversion is the table's, and aninttoo large for afloatraisesctypes.ArgumentErrorwith CPython's text,argument 1: OverflowError: int too large to convert to float. - Values. A library and a function are not values otherwise: storing, passing or printing one is planned for 1.0 (FFI-09).
- Text for C. Every
strandbytesobject keeps a zero after its data, so ac_char_pargument is the object's own buffer, as CPython passes it, and stays valid while the object lives. - Linking (FFI-04). Each library a module declares is linked
dynamically as
-l:libraryunlesstypy.tomlsays otherwise:
library-paths = ["lib"]
[libraries."libtools.so.3"]
link = "static"
A static library is linked as -l:BASE.a, where BASE is the name up
to .so, so libtools.so.3 links libtools.a. library-paths names
directories under the project root where the linker looks first, as
-L. A library or a function the linker cannot find is E0702 when the
program is built.
Consequences¶
- A call of a C function costs what a call from C costs, with each conversion a few instructions; the program loads no library at run time but those the system loader loads.
- A missing library or function stops the build, where CPython raises
OSErrororAttributeErrorwhen the program runs. - A wrong argument is found when the program is compiled, so the
ctypes.ArgumentErrorof a wrong type never arises; the one that can is thefloatconversion's. - A program whose declarations depend on a condition, or come after a module-level call, is refused, though CPython runs it.
- The library's own binding, written by a library build (ADR-0046), compiles as any module does.
Related requirements¶
FFI-01, FFI-02, FFI-03, FFI-04, FFI-08, FFI-09, STD-07, ADR-0003, ADR-0046.