#5018·scapy

`Packet.fields_desc` type annotation is inconsistent with runtime behavior

Author: anci3ntr0ckCreated Jun 18, 2026Updated Jul 16, 2026

Brief description

Packet.fields_desc supports Packet / Packet_metaclass but typed as List[AnyField]

Scapy version

2.7.0

Python version

3.14

Operating system

Windows11

Additional environment information

No response

How to reproduce

The type annotation for fields_desc on Packet classes is declared as List[AnyField]:

python
# scapy/packet.py, line 108
fields_desc = []  # type: List[AnyField]

However, at runtime, the Packet_metaclass.__new__ method explicitly handles the case where elements in fields_desc are Packet metaclass instances (i.e., references to other Packet subclasses), not just Field instances:

python
# scapy/base_classes.py, lines 371-380
        if "fields_desc" in dct:  # perform resolution of references to other packets  # noqa: E501
            current_fld = dct["fields_desc"]  # type: List[Union[scapy.fields.Field[Any, Any], Packet_metaclass]]  # noqa: E501
            resolved_fld = []  # type: List[scapy.fields.Field[Any, Any]]
            for fld_or_pkt in current_fld:
                if isinstance(fld_or_pkt, Packet_metaclass):
                    # reference to another fields_desc
                    for pkt_fld in fld_or_pkt.fields_desc:
                        resolved_fld.append(pkt_fld)
                else:
                    resolved_fld.append(fld_or_pkt)

This means fields_desc can contain:

  1. Field instances — the documented/typed behavior
  2. Packet classes (metaclass instances) — which get inlined/expanded by flattening their fields_desc

Actual result

No response

Expected result

The type should be updated to something like:

python
fields_desc = []  # type: List[Union[AnyField, Type[Packet]]]

Related resources

No response