Structures with non-native byte order cannot contain pointer type fields, or any other data types containing pointer type fields.
Concrete structure and union types must be created by subclassing one
of these types, and at least define a _fields_ class variable.
ctypes will create descriptors which allow reading and writing the
fields by direct attribute accesses. These are the
For integer type fields like c_int, a third optional item can be given. It must be a small positive integer defining the bit width of the field.
Field names must be unique within one structure or union. This is not checked, only one field can be accessed when names are repeated.
It is possible to define the _fields_ class variable after the class statement that defines the Structure subclass, this allows to create data types that directly or indirectly reference themselves:
class List(Structure): pass List._fields_ = [("pnext", POINTER(List)), ... ]
The _fields_ class variable must, however, be defined before
the type is first used (an instance is created,
called on it, and so on). Later assignments to the _fields_
class variable will raise an AttributeError.
Structure and union subclass constructors accept both positional and named arguments. Positional arguments are used to initialize the fields in the same order as they appear in the _fields_ definition, named arguments are used to initialize the fields with the corresponding name.
It is possible to defined sub-subclasses of structure types, they inherit the fields of the base class plus the _fields_ defined in the sub-subclass, if any.
_anonymous_must be already defined when _fields_ is assigned, otherwise it will have no effect.
The fields listed in this variable must be structure or union type
ctypes will create descriptors in the structure type
that allows to access the nested fields directly, without the need
to create the structure or union field.
Here is an example type (Windows):
class _U(Union): _fields_ = [("lptdesc", POINTER(TYPEDESC)), ("lpadesc", POINTER(ARRAYDESC)), ("hreftype", HREFTYPE)] class TYPEDESC(Structure): _fields_ = [("u", _U), ("vt", VARTYPE)] _anonymous_ = ("u",)
TYPEDESC structure describes a COM data type, the
field specifies which one of the union fields is valid. Since the
u field is defined as anonymous field, it is now possible to
access the members directly off the TYPEDESC instance.
td.u.lptdesc are equivalent, but the former
is faster since it does not need to create a temporary union
td = TYPEDESC() td.vt = VT_PTR td.lptdesc = POINTER(some_type) td.u.lptdesc = POINTER(some_type)
It is possible to defined sub-subclasses of structures, they inherit the fields of the base class. If the subclass definition has a separate _fields_ variable, the fields specified in this are appended to the fields of the base class.
Structure and union constructors accept both positional and keyword arguments. Positional arguments are used to initialize member fields in the same order as they are appear in _fields_. Keyword arguments in the constructor are interpreted as attribute assignments, so they will initialize _fields_ with the same name, or create new attributes for names not present in _fields_.
See About this document... for information on suggesting changes.