gh-128715: Expose ctypes.CField, with info attributes

Doc/library/ctypes.rst

@@ -657,12 +657,13 @@ Nested structures can also be initialized in the constructor in several ways::
  >>> r = RECT((1, 2), (3, 4))
 
 Field :term:`descriptor`\s can be retrieved from the *class*, they are useful
-for debugging because they can provide useful information::
+for debugging because they can provide useful information.
+See :class:`CField`::
 
- >>> print(POINT.x)
- <Field type=c_long, ofs=0, size=4>
- >>> print(POINT.y)
- <Field type=c_long, ofs=4, size=4>
+ >>> POINT.x
+ <ctypes.CField 'x' type=c_int, ofs=0, size=4>
+ >>> POINT.y
+ <ctypes.CField 'y' type=c_int, ofs=4, size=4>
  >>>
 
 
@@ -2812,6 +2813,98 @@ fields, or any other data types containing pointer type fields.
  present in :attr:`_fields_`.
 
 
+.. class:: CField(*args, **kw)
+
+ Descriptor for fields of a :class:`Structure` and :class:`Union`.
+ For example::
+
+ >>> class Color(Structure):
+ ... _fields_ = (
+ ... ('red', c_uint8),
+ ... ('green', c_uint8),
+ ... ('blue', c_uint8),
+ ... ('intense', c_bool, 1),
+ ... ('blinking', c_bool, 1),
+ ... )
+ ...
+ >>> Color.red
+ <ctypes.CField 'red' type=c_ubyte, ofs=0, size=1>
+ >>> Color.green.type
+ <class 'ctypes.c_ubyte'>
+ >>> Color.blue.byte_offset
+ 2
+ >>> Color.intense
+ <ctypes.CField 'intense' type=c_bool, ofs=3, bit_size=1, bit_offset=0>
+ >>> Color.blinking.bit_offset
+ 1
+
+ All attributes are read-only.
+
+ :class:`!CField` objects are created via :attr:`~Structure._fields_`;
+ do not instantiate the class directly.
+
+ .. versionadded:: next
+
+ Previously, descriptors only had ``offset`` and ``size`` attributes
+ and a readable string representation; the :class:`!CField` class was not
+ available directly.
+
+ .. attribute:: name
+
+ Name of the field, as a string.
+
+ .. attribute:: type
+
+ Type of the field, as a :ref:`ctypes class <ctypes-data-types>`.
+
+ .. attribute:: offset
+ byte_offset
+
+ Offset of the field, in bytes.
+
+ For bitfields, this is the offset of the underlying byte-aligned
+ *storage unit*; see :attr:`~CField.bit_offset`.
+
+ .. attribute:: byte_size
+
+ Size of the field, in bytes.
+
+ For bitfields, this is the size of the underlying *storage unit*.
+ Typically, it has the same size as the bitfield's type.
+
+ .. attribute:: size
+
+ For non-bitfields, equivalent to :attr:`~CField.byte_size`.
+
+ For bitfields, this contains a backwards-compatible bit-packed
+ value that combines :attr:`~CField.bit_size` and
+ :attr:`~CField.bit_offset`.
+ Prefer using the explicit attributes instead.
+
+ .. attribute:: is_bitfield
+
+ True if this is a bitfield.
+
+ .. attribute:: bit_offset
+ bit_size
+
+ The location of a bitfield within its *storage unit*, that is, within
+ :attr:`~CField.byte_size` bytes of memory starting at
+ :attr:`~CField.byte_offset`.
+
+ To get the field's value, read the storage unit as an integer,
+ :ref:`shift left <shifting>` by :attr:`!bit_offset` and
+ take the :attr:`!bit_size` least significant bits.
+
+ For non-bitfields, :attr:`!bit_offset` is zero
+ and :attr:`!bit_size` is equal to ``byte_size * 8``.
+
+ .. attribute:: is_anonymous
+
+ True if this field is anonymous, that is, it contains nested sub-fields
+ that should be be merged into a containing structure or union.
+
+
 .. _ctypes-arrays-pointers:
 
 Arrays and pointers

Doc/whatsnew/3.14.rst

@@ -487,6 +487,11 @@ ctypes
  to help match a non-default ABI.
  (Contributed by Petr Viktorin in :gh:`97702`.)
 
+* The class of :class:`~ctypes.Structure`/:class:`~ctypes.Union`
+ field descriptors is now available as :class:`~ctypes.CField`,
+ and has new attributes to aid debugging and introspection.
+ (Contributed by Petr Viktorin in :gh:`128715`.)
+
 * On Windows, the :exc:`~ctypes.COMError` exception is now public.
  (Contributed by Jun Komoda in :gh:`126686`.)
 

Include/internal/pycore_global_strings.h

@@ -245,6 +245,7 @@ struct _Py_global_strings{
  STRUCT_FOR_ID(_get_sourcefile)
  STRUCT_FOR_ID(_handle_fromlist)
  STRUCT_FOR_ID(_initializing)
+ STRUCT_FOR_ID(_internal_use)
  STRUCT_FOR_ID(_io)
  STRUCT_FOR_ID(_is_text_encoding)
  STRUCT_FOR_ID(_isatty_open_only)
@@ -295,6 +296,7 @@ struct _Py_global_strings{
  STRUCT_FOR_ID(before)
  STRUCT_FOR_ID(big)
  STRUCT_FOR_ID(binary_form)
+ STRUCT_FOR_ID(bit_offset)
  STRUCT_FOR_ID(bit_size)
  STRUCT_FOR_ID(block)
  STRUCT_FOR_ID(bound)
@@ -305,6 +307,8 @@ struct _Py_global_strings{
  STRUCT_FOR_ID(buffers)
  STRUCT_FOR_ID(bufsize)
  STRUCT_FOR_ID(builtins)
+ STRUCT_FOR_ID(byte_offset)
+ STRUCT_FOR_ID(byte_size)
  STRUCT_FOR_ID(byteorder)
  STRUCT_FOR_ID(bytes)
  STRUCT_FOR_ID(bytes_per_sep)

Lib/ctypes/__init__.py

@@ -12,6 +12,7 @@
 from _ctypes import RTLD_LOCAL, RTLD_GLOBAL
 from _ctypes import ArgumentError
 from _ctypes import SIZEOF_TIME_T
+from _ctypes import CField
 
 from struct import calcsize as _calcsize
 

Lib/ctypes/_layout.py

@@ -19,29 +19,6 @@ def round_up(n, multiple):
  assert multiple > 0
  return ((n + multiple - 1) // multiple) * multiple
 
-def LOW_BIT(offset):
- return offset & 0xFFFF
-
-def NUM_BITS(bitsize):
- return bitsize >> 16
-
-def BUILD_SIZE(bitsize, offset):
- assert 0 <= offset, offset
- assert offset <= 0xFFFF, offset
- # We don't support zero length bitfields.
- # And GET_BITFIELD uses NUM_BITS(size) == 0,
- # to figure out whether we are handling a bitfield.
- assert bitsize > 0, bitsize
- result = (bitsize << 16) + offset
- assert bitsize == NUM_BITS(result), (bitsize, result)
- assert offset == LOW_BIT(result), (offset, result)
- return result
-
-def build_size(bit_size, bit_offset, big_endian, type_size):
- if big_endian:
- return BUILD_SIZE(bit_size, 8 * type_size - bit_offset - bit_size)
- return BUILD_SIZE(bit_size, bit_offset)
-
 _INT_MAX = (1 << (ctypes.sizeof(ctypes.c_int) * 8) - 1) - 1
 
 
@@ -213,13 +190,10 @@ def get_layout(cls, input_fields, is_struct, base):
 
  offset = round_down(next_bit_offset, type_bit_align) // 8
  if is_bitfield:
- effective_bit_offset = next_bit_offset - 8 * offset
- size = build_size(bit_size, effective_bit_offset,
- big_endian, type_size)
- assert effective_bit_offset <= type_bit_size
+ bit_offset = next_bit_offset - 8 * offset
+ assert bit_offset <= type_bit_size
  else:
  assert offset == next_bit_offset / 8
- size = type_size
 
  next_bit_offset += bit_size
  struct_size = round_up(next_bit_offset, 8) // 8
@@ -253,18 +227,17 @@ def get_layout(cls, input_fields, is_struct, base):
  offset = next_byte_offset - last_field_bit_size // 8
  if is_bitfield:
  assert 0 <= (last_field_bit_size + next_bit_offset)
- size = build_size(bit_size,
- last_field_bit_size + next_bit_offset,
- big_endian, type_size)
- else:
- size = type_size
+ bit_offset = last_field_bit_size + next_bit_offset
  if type_bit_size:
  assert (last_field_bit_size + next_bit_offset) < type_bit_size
 
  next_bit_offset += bit_size
  struct_size = next_byte_offset
 
- assert (not is_bitfield) or (LOW_BIT(size) <= size * 8)
+ if is_bitfield and big_endian:
+ # On big-endian architectures, bit fields are also laid out
+ # starting with the big end.
+ bit_offset = type_bit_size - bit_size - bit_offset
 
  # Add the format spec parts
  if is_struct:
@@ -286,16 +259,21 @@ def get_layout(cls, input_fields, is_struct, base):
  # a bytes name would be rejected later, but we check early
  # to avoid a BytesWarning with `python -bb`
  raise TypeError(
- "field{name!r}: name must be a string, not bytes")
+f"field{name!r}: name must be a string, not bytes")
  format_spec_parts.append(f"{fieldfmt}:{name}:")
 
  result_fields.append(CField(
  name=name,
  type=ctype,
-size=size,
-offset=offset,
+byte_size=type_size,
+byte_offset=offset,
  bit_size=bit_size if is_bitfield else None,
+ bit_offset=bit_offset if is_bitfield else None,
  index=i,
+
+ # Do not use CField outside ctypes, yet.
+ # The constructor is internal API and may change without warning.
+ _internal_use=True,
  ))
  if is_bitfield and not gcc_layout:
  assert type_bit_size > 0