https://github.com/python/cpython/commit/8943bb722f2f88a95ea6c5ee36bb5d540740d792
commit: 8943bb722f2f88a95ea6c5ee36bb5d540740d792
branch: main
author: Petr Viktorin <[email protected]>
committer: encukou <[email protected]>
date: 2025-08-04T15:40:42+02:00
summary:
gh-136520: Clarify docs for _pack_ & _align_ (GH-137036)
Move docs to the reference section & reduce the “tutorial” part to a quick
intro & link.
Clarify what values are accepted.
Add macro/attribute equivalents.
Discourage _align_ values that aren't powers of two.
files:
M Doc/library/ctypes.rst
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 09f596101b4d1e..d8dac24c8ab532 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -700,14 +700,10 @@ compiler does it. It is possible to override this
behavior entirely by specifyi
:attr:`~Structure._layout_` class attribute in the subclass definition; see
the attribute documentation for details.
-It is possible to specify the maximum alignment for the fields by setting
-the :attr:`~Structure._pack_` class attribute to a positive integer.
-This matches what ``#pragma pack(n)`` does in MSVC.
-
-It is also possible to set a minimum alignment for how the subclass itself is
packed in the
-same way ``#pragma align(n)`` works in MSVC.
-This can be achieved by specifying a :attr:`~Structure._align_` class attribute
-in the subclass definition.
+It is possible to specify the maximum alignment for the fields and/or for the
+structure itself by setting the class attributes :attr:`~Structure._pack_`
+and/or :attr:`~Structure._align_`, respectively.
+See the attribute documentation for details.
:mod:`ctypes` uses the native byte order for Structures and Unions. To build
structures with non-native byte order, you can use one of the
@@ -2792,11 +2788,18 @@ fields, or any other data types containing pointer type
fields.
.. attribute:: _pack_
An optional small integer that allows overriding the alignment of
- structure fields in the instance. :attr:`_pack_` must already be defined
- when :attr:`_fields_` is assigned, otherwise it will have no effect.
- Setting this attribute to 0 is the same as not setting it at all.
+ structure fields in the instance.
+
+ This is only implemented for the MSVC-compatible memory layout
+ (see :attr:`_layout_`).
- This is only implemented for the MSVC-compatible memory layout.
+ Setting :attr:`!_pack_` to 0 is the same as not setting it at all.
+ Otherwise, the value must be a positive power of two.
+ The effect is equivalent to ``#pragma pack(N)`` in C, except
+ :mod:`ctypes` may allow larger *n* than what the compiler accepts.
+
+ :attr:`!_pack_` must already be defined
+ when :attr:`_fields_` is assigned, otherwise it will have no effect.
.. deprecated-removed:: 3.14 3.19
@@ -2809,9 +2812,22 @@ fields, or any other data types containing pointer type
fields.
.. attribute:: _align_
- An optional small integer that allows overriding the alignment of
+ An optional small integer that allows increasing the alignment of
the structure when being packed or unpacked to/from memory.
- Setting this attribute to 0 is the same as not setting it at all.
+
+ The value must not be negative.
+ The effect is equivalent to ``__attribute__((aligned(N)))`` on GCC
+ or ``#pragma align(N)`` on MSVC, except :mod:`ctypes` may allow
+ values that the compiler would reject.
+
+ :attr:`!_align_` can only *increase* a structure's alignment
+ requirements. Setting it to 0 or 1 has no effect.
+
+ Using values that are not powers of two is discouraged and may lead to
+ surprising behavior.
+
+ :attr:`!_align_` must already be defined
+ when :attr:`_fields_` is assigned, otherwise it will have no effect.
.. versionadded:: 3.13
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
