Annotation-based syntax for ctypes structs

Turn this:

class S(ctypes.Structure):
   _fields_ = [ ('a', ctypes.c_int), ('b', ctypes.c_char_p) ]

Into this:

class S(ctypes.Structure):
    a : ctypes.c_int
    b : ctypes.c_char_p

See discussion on https://discuss.python.org/t/annotation-based-sugar-for-ctypes/26579

Working on implementation

Linked PRs

The overwhelming support present on this issue, along with the repeated requests from users, has convinced me that this is worth the effort. I've put up an implementation at #153781, which I'll polish and/or merge during the EuroPython sprints this weekend.

gh-104533: Add a dataclass-like decorator for `ctypes` structures (GH…

The original discussion at https://discuss.python.org/t/annotation-based-sugar-for-ctypes/26579

Also had a proposal for sugaring the syntax of functions, too:

This:

libm = ctypes.CDLL('libm.so')
pow = libm.pow
pow.restype = ctypes.c_double
pow.argtypes = (ctypes.c_double, ctypes, c_double)

into this:

libm = ctypes.CDLL('libm.so')

@libm
def pow(a: ctypes.c_double, b:ctypes.c_double) -> c_double:
    pass

Any interest in pursuing this, too?

pythongh-104533: Add a dataclass-like decorator for `ctypes` structur…

Yes, but let's do that in a new issue. I'm uncomfortable with making CDLL/PyDLL callable like in your example, but a decorator that simply accepts a DLL should be fine:

@wrap_dll_function(ctypes.pythonapi)
def PyObject_GetAttrString(op: ctypes.py_object, attr: ctypes.c_char_p) -> ctypes.py_object:
    ...

@wrap_dll_function(ctypes.pythonapi)
def PyObject_GetAttrString(op: ctypes.py_object, attr: ctypes.c_char_p) -> ctypes.py_object:
...

Did you mean the ellipsis literally? It’s actually a good idea to require it and have the decorator wrapper verify that the function body consists of an ellipsis as a signal to the reader that the function body is not there.

I did. Maybe pass should be the documented option? I'm not a big fan of actually trying to validate that the function has no body, because that would involve weird bytecode or AST introspection, which would significantly complicate the implementation.

pythongh-104533: Fix @ctypes.util.struct with endian

pythongh-104533: Fix @ctypes.util.struct with string annotations

gh-104533: Fix `@ctypes.util.struct` with string annotations (#154040)

gh-104533: Fix `@ctypes.util.struct` with endian (#154038)

gh-104533: Update test_ctypes.test_structures (#154091)

gh-104533: Use `@ctypes.util.struct` decorator (#154031)

gh-104533: Fix ctypes test_pointer_proto_missing_argtypes_error() (#1…

@ZeroIntensity

@ZeroIntensity, a question about ctypes.util.struct: what should it do with a class that subclasses ctypes.Union? Right now it drops the base and builds a Structure, so the fields no longer overlap:

from ctypes import Union, c_int, c_double, sizeof
from ctypes.util import struct

@struct
class U(Union):
    i: c_int
    d: c_double

print(U.__mro__[1].__name__, sizeof(U))

Structure 16

The docs only promise structure types, so this might be intended. If it isn't, it could either raise TypeError or build a Union. I'm happy to open an issue and a PR for whichever you'd prefer.

I think it should raise a TypeError. We may want to add a @ctypes.util.union decorator, but I'll handle that separately.

Navigation Menu

Repository navigation

Annotation-based syntax for ctypes structs #104533

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Annotation-based syntax for ctypes structs #104533

Description

Linked PRs

Activity

ZeroIntensity commented on Jul 15, 2026

orent commented on Jul 18, 2026

ZeroIntensity commented on Jul 18, 2026

orent commented on Jul 18, 2026

ZeroIntensity commented on Jul 18, 2026

fedonman commented on Sep 23, 2026

ZeroIntensity commented on Sep 23, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions