gh-104533: Add a dataclass-like decorator for `ctypes` structures by ZeroIntensity · Pull Request #153781 · python/cpython

ZeroIntensity · 2026-07-15T19:20:26Z

Issue: Annotation-based syntax for ctypes structs #104533

read-the-docs-community · 2026-07-15T19:24:35Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33620062 | 📁 Comparing 2e469b6 against main (b4662e8)

🔍 Preview build

3 files changed

±library/ctypes.html
±whatsnew/3.16.html
±whatsnew/changelog.html

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

johnslavik · 2026-07-16T11:31:27Z

+def struct(class_or_none=None, /, *, align=None, layout=None, endian='native', pack=None):
+ process_the_struct = functools.partial(
+ _process_struct,
+ align=align,
+ layout=layout,
+ endian=endian,
+ pack=pack
+ )
+
+ if class_or_none is None:
+ def inner(klass):
+ return process_the_struct(klass)
+
+ return inner
+
+ return process_the_struct(class_or_none)


I meant it like this:
Suggested change
defstruct(class_or_none=None, /, *, align=None, layout=None, endian='native', pack=None):
process_the_struct=functools.partial(
_process_struct,
align=align,
layout=layout,
endian=endian,
pack=pack
)
ifclass_or_noneisNone:
definner(klass):
returnprocess_the_struct(klass)
returninner
returnprocess_the_struct(class_or_none)
defstruct(class_or_none=None, /, *, align=None, layout=None, endian='native', pack=None):
ifclass_or_noneisNone:
returnfunctools.partial(
struct,
align=align,
layout=layout,
endian=endian,
pack=pack,
)
return_process_struct(
class_or_none,
align=align,
layout=layout,
endian=endian,
pack=pack,
)
That's how decorators of this fashion are usually made.
Feel free to ignore.

process_the_struct isn't defined here; what are you trying to show?

Edited the suggestion

johnslavik · 2026-07-16T11:33:21Z

+.. decorator:: struct(*, align=None, layout, endian='native', pack=None)
+ :module: ctypes.util


Consider adding a collation: old syntax vs. new syntax.

I don't think that's necessary -- the examples for Structure are right above.

Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

…es (pythonGH-153781) Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

GalaxySnail · 2026-07-18T11:26:58Z

+ For controlling field-specific data, wrap the annotation in :class:`typing.Annotated`
+ with :class:`CFieldInfo` as the second argument, like so:


Maybe a silly question, but why does this use Annotated instead of dataclasses-style field: SomeType = field(anonymous=True) syntax? Did I miss a consensus on this?

Annotated is more correct, isn't it? field() from dataclasses predates typing.Annotated, so that's why it's used there.

Yes, it is more correct.

vstinner · 2026-07-18T20:53:36Z

Oh, this new API looks easier to use than ctypes.Structure, I'm excited!

fromctypes.utilimportstructfromctypesimportc_int@structclassPoint:
x: c_inty: c_intpoint=Point(1, 2)
print(point)

ZeroIntensity added 3 commits July 15, 2026 14:53

Implement a dataclass-like struct decorator for ctypes.
f0db59d

Add docs.
b73c912

Add blurb.
94eb25a

ZeroIntensity added the topic-ctypes label Jul 15, 2026

bedevere-appBot mentioned this pull request Jul 15, 2026
Annotation-based syntax for ctypes structs #104533
Closed

Fix Sphinx warnings.
bba7682

johnslavik reviewed Jul 15, 2026
View reviewed changes

Comment threadLib/ctypes/util.py Outdated
Comment threadLib/ctypes/util.py Outdated
Comment threadLib/ctypes/util.py Outdated
Comment threadLib/ctypes/util.py Outdated

ZeroIntensityand others added 4 commits July 16, 2026 03:31

Apply suggestions from code review
91eb76b
Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

Use functools.wraps.
103a740

Use functools.partial.
b14dd51

Add tests for CFieldInfo.
864b811

ZeroIntensity marked this pull request as ready for review July 16, 2026 09:39

ZeroIntensity requested a review from AA-Turner as a code owner July 16, 2026 09:39

bedevere-appBot added the awaiting core review label Jul 16, 2026

johnslavik approved these changes Jul 16, 2026
View reviewed changes

merwok reviewed Jul 16, 2026
View reviewed changes

Comment threadLib/ctypes/util.py Outdated

ZeroIntensityand others added 2 commits July 16, 2026 12:01

Update Lib/ctypes/util.py
c0afd38
Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

Use 'decorated_class' instead of 'klass'.
2e469b6

ZeroIntensity merged commit 5b85756 into python:mainJul 18, 2026
51 checks passed

ZeroIntensity deleted the ctypes/struct-decorator branch July 18, 2026 08:48

bedevere-appBot removed the awaiting core review label Jul 18, 2026

fedonman pushed a commit to fedonman/cpython that referenced this pull request Jul 18, 2026
pythongh-104533: Add a dataclass-like decorator forctypesstructur…
df78419
…es (pythonGH-153781) Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>

GalaxySnail reviewed Jul 18, 2026
View reviewed changes

-defstruct(class_or_none=None, /, *, align=None, layout=None, endian='native', pack=None):
-process_the_struct=functools.partial(
-_process_struct,
-align=align,
-layout=layout,
-endian=endian,
-pack=pack
-)
-ifclass_or_noneisNone:
-definner(klass):
-returnprocess_the_struct(klass)
-returninner
-returnprocess_the_struct(class_or_none)
+defstruct(class_or_none=None, /, *, align=None, layout=None, endian='native', pack=None):
+ifclass_or_noneisNone:
+returnfunctools.partial(
+struct,
+align=align,
+layout=layout,
+endian=endian,
+pack=pack,
+ )
+return_process_struct(
+class_or_none,
+align=align,
+layout=layout,
+endian=endian,
+pack=pack,
+ )

		.. decorator:: struct(*, align=None, layout, endian='native', pack=None)
		:module: ctypes.util

		For controlling field-specific data, wrap the annotation in :class:`typing.Annotated`
		with :class:`CFieldInfo` as the second argument, like so:

Uh oh!

Uh oh!

Conversation

ZeroIntensity commented Jul 15, 2026• edited by bedevere-app BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-communityBot commented Jul 15, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

johnslavikJul 16, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityJul 16, 2026

Choose a reason for hiding this comment

Uh oh!

johnslavikJul 18, 2026

Choose a reason for hiding this comment

Uh oh!

johnslavikJul 16, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityJul 16, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

GalaxySnailJul 18, 2026

Choose a reason for hiding this comment

Uh oh!

ZeroIntensityJul 18, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johnslavikJul 18, 2026

Choose a reason for hiding this comment

Uh oh!

vstinner commented Jul 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ZeroIntensity commented Jul 15, 2026•
edited by bedevere-app Bot
Loading

read-the-docs-communityBot commented Jul 15, 2026•
edited
Loading

johnslavikJul 16, 2026•
edited
Loading

johnslavikJul 16, 2026•
edited
Loading

ZeroIntensityJul 16, 2026•
edited
Loading

ZeroIntensityJul 18, 2026•
edited
Loading