Skip to content

Commit 3807439

Browse files
authored
fix(toolkit): lead every adapter message with its engine's own __engine_name__ (#2399)
The pcapkit.toolkit adapters put the engine name mid-sentence instead of leading with it, unlike the <prefix>: <lowercase description>: ... {value!r} form #2232/#2257 established, and hand-typed the name rather than reading it off the engine class's own __engine_name__. Each adapter module gains _ENGINE = <EngineClass>.__engine_name__ (plus the import), so a rename in pcapkit/foundation/engines/ cannot leave the adapter spelling the old name. Four modules, five sub-bugs: - pcap_ct.py/pypcap.py: "IPv4 reassembly is not supported by the pcap-ct engine: ..." -> "PCAP_CT: IPv4 reassembly is not supported: ..." (and the PyPCAP sibling). - pypcapfile.py: "invalid PyPCAPFile IPv4 address: 5" -> "PyPCAPFile: invalid IPv4 address: 5" (same for MAC address); the IPv6 UnsupportedCall and the "Frame N: TCP over IPv6 ..." warning get the same treatment. - pyshark.py: boolean-field, frame.time_epoch and no-frame-layer messages all reordered the same way. - scapy.py: the import-time warning reordered; the quoted package name is lowercased to 'scapy' to match the actual failing import and the sibling dependency warnings elsewhere in the codebase, which quote the installable name. The engine classes' toolkit imports are all function-local, so the new toolkit -> foundation.engines import introduces no cycle. Tests: new tests/toolkit/test_engine_message_prefix_2304_unit.py (9 tests) pins each message whole and asserts each module's _ENGINE is the engine class's own attribute. Existing pins in the four engines' test files updated for the new text.
1 parent 63e8dea commit 3807439

10 files changed

Lines changed: 305 additions & 29 deletions

‎pcapkit/toolkit/pcap_ct.py‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
"""
3333
from typing import TYPE_CHECKING
3434

35+
from pcapkit.foundation.engines.pcap_ct import PCAP_CT
3536
from pcapkit.utilities.exceptions import UnsupportedCall
3637

3738
if TYPE_CHECKING:
@@ -48,6 +49,13 @@
4849
'ipv4_reassembly', 'ipv6_reassembly', 'tcp_reassembly', 'tcp_traceflow',
4950
]
5051

52+
#: Message prefix shared by every adapter below, read off
53+
#: :attr:`PCAP_CT.__engine_name__
54+
#: <pcapkit.foundation.engines.pcap_ct.PCAP_CT.__engine_name__>` rather than
55+
#: spelled out, so the engine cannot be renamed there and still be named the old
56+
#: way here (:issue:`2304`).
57+
_ENGINE = PCAP_CT.__engine_name__
58+
5159
#: Explanatory suffix shared by every unsupported adapter below.
5260
_NO_DISSECTION = ("'pcap-ct' is a libpcap binding and performs no protocol "
5361
"dissection, so there is no protocol layer to read")
@@ -109,7 +117,7 @@ def ipv4_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'IP_Packet[IPv4Add
109117
UnsupportedCall: Always, as `pcap-ct`_ provides no IPv4 layer to read.
110118
111119
"""
112-
raise UnsupportedCall(f'IPv4 reassembly is not supported by the pcap-ct engine: {_NO_DISSECTION}')
120+
raise UnsupportedCall(f'{_ENGINE}: IPv4 reassembly is not supported: {_NO_DISSECTION}')
113121

114122

115123
def ipv6_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'IP_Packet[IPv6Address] | None':
@@ -123,7 +131,7 @@ def ipv6_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'IP_Packet[IPv6Add
123131
UnsupportedCall: Always, as `pcap-ct`_ provides no IPv6 layer to read.
124132
125133
"""
126-
raise UnsupportedCall(f'IPv6 reassembly is not supported by the pcap-ct engine: {_NO_DISSECTION}')
134+
raise UnsupportedCall(f'{_ENGINE}: IPv6 reassembly is not supported: {_NO_DISSECTION}')
127135

128136

129137
def tcp_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'TCP_Packet | None':
@@ -137,7 +145,7 @@ def tcp_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'TCP_Packet | None'
137145
UnsupportedCall: Always, as `pcap-ct`_ provides no TCP layer to read.
138146
139147
"""
140-
raise UnsupportedCall(f'TCP reassembly is not supported by the pcap-ct engine: {_NO_DISSECTION}')
148+
raise UnsupportedCall(f'{_ENGINE}: TCP reassembly is not supported: {_NO_DISSECTION}')
141149

142150

143151
def tcp_traceflow(packet: 'bytes', timestamp: 'float', *, data_link: 'Enum_LinkType',
@@ -154,4 +162,4 @@ def tcp_traceflow(packet: 'bytes', timestamp: 'float', *, data_link: 'Enum_LinkT
154162
UnsupportedCall: Always, as `pcap-ct`_ provides no TCP layer to read.
155163
156164
"""
157-
raise UnsupportedCall(f'TCP flow tracing is not supported by the pcap-ct engine: {_NO_DISSECTION}')
165+
raise UnsupportedCall(f'{_ENGINE}: TCP flow tracing is not supported: {_NO_DISSECTION}')

‎pcapkit/toolkit/pypcap.py‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
"""
3232
from typing import TYPE_CHECKING
3333

34+
from pcapkit.foundation.engines.pypcap import PyPCAP
3435
from pcapkit.utilities.exceptions import UnsupportedCall
3536

3637
if TYPE_CHECKING:
@@ -47,6 +48,13 @@
4748
'ipv4_reassembly', 'ipv6_reassembly', 'tcp_reassembly', 'tcp_traceflow',
4849
]
4950

51+
#: Message prefix shared by every adapter below, read off
52+
#: :attr:`PyPCAP.__engine_name__
53+
#: <pcapkit.foundation.engines.pypcap.PyPCAP.__engine_name__>` rather than
54+
#: spelled out, so the engine cannot be renamed there and still be named the old
55+
#: way here (:issue:`2304`).
56+
_ENGINE = PyPCAP.__engine_name__
57+
5058
#: Explanatory suffix shared by every unsupported adapter below.
5159
_NO_DISSECTION = ("'pypcap' is a libpcap binding and performs no protocol "
5260
"dissection, so there is no protocol layer to read")
@@ -108,7 +116,7 @@ def ipv4_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'IP_Packet[IPv4Add
108116
UnsupportedCall: Always, as `PyPCAP`_ provides no IPv4 layer to read.
109117
110118
"""
111-
raise UnsupportedCall(f'IPv4 reassembly is not supported by the PyPCAP engine: {_NO_DISSECTION}')
119+
raise UnsupportedCall(f'{_ENGINE}: IPv4 reassembly is not supported: {_NO_DISSECTION}')
112120

113121

114122
def ipv6_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'IP_Packet[IPv6Address] | None':
@@ -122,7 +130,7 @@ def ipv6_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'IP_Packet[IPv6Add
122130
UnsupportedCall: Always, as `PyPCAP`_ provides no IPv6 layer to read.
123131
124132
"""
125-
raise UnsupportedCall(f'IPv6 reassembly is not supported by the PyPCAP engine: {_NO_DISSECTION}')
133+
raise UnsupportedCall(f'{_ENGINE}: IPv6 reassembly is not supported: {_NO_DISSECTION}')
126134

127135

128136
def tcp_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'TCP_Packet | None':
@@ -136,7 +144,7 @@ def tcp_reassembly(packet: 'bytes', *, count: 'int' = -1) -> 'TCP_Packet | None'
136144
UnsupportedCall: Always, as `PyPCAP`_ provides no TCP layer to read.
137145
138146
"""
139-
raise UnsupportedCall(f'TCP reassembly is not supported by the PyPCAP engine: {_NO_DISSECTION}')
147+
raise UnsupportedCall(f'{_ENGINE}: TCP reassembly is not supported: {_NO_DISSECTION}')
140148

141149

142150
def tcp_traceflow(packet: 'bytes', timestamp: 'float', *, data_link: 'Enum_LinkType',
@@ -153,4 +161,4 @@ def tcp_traceflow(packet: 'bytes', timestamp: 'float', *, data_link: 'Enum_LinkT
153161
UnsupportedCall: Always, as `PyPCAP`_ provides no TCP layer to read.
154162
155163
"""
156-
raise UnsupportedCall(f'TCP flow tracing is not supported by the PyPCAP engine: {_NO_DISSECTION}')
164+
raise UnsupportedCall(f'{_ENGINE}: TCP flow tracing is not supported: {_NO_DISSECTION}')

‎pcapkit/toolkit/pypcapfile.py‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848

4949
from pcapkit.const.reg.ethertype import EtherType as Enum_EtherType
5050
from pcapkit.const.reg.transtype import TransType as Enum_TransType
51+
from pcapkit.foundation.engines.pypcapfile import PyPCAPFile
5152
from pcapkit.foundation.reassembly.data.ip import Packet as IP_Packet
5253
from pcapkit.foundation.reassembly.data.tcp import Packet as TCP_Packet
5354
from pcapkit.foundation.traceflow.data.tcp import Packet as TF_TCP_Packet
@@ -77,6 +78,13 @@
7778
'ipv4_reassembly', 'ipv6_reassembly', 'tcp_reassembly', 'tcp_traceflow',
7879
]
7980

81+
#: Message prefix shared by every message below, read off
82+
#: :attr:`PyPCAPFile.__engine_name__
83+
#: <pcapkit.foundation.engines.pypcapfile.PyPCAPFile.__engine_name__>` rather
84+
#: than spelled out, so the engine cannot be renamed there and still be named
85+
#: the old way here (:issue:`2304`).
86+
_ENGINE = PyPCAPFile.__engine_name__
87+
8088
#: IPv4 **DF** (don't fragment) bit, within the three-bit flags field.
8189
IPV4_FLAG_DF = 0b010
8290

@@ -163,7 +171,7 @@ def _parse_ipv4_address(value: 'Any') -> 'IPv4Address':
163171
164172
"""
165173
if not isinstance(value, bytes):
166-
raise ProtocolError(f'invalid PyPCAPFile IPv4 address: {value!r}')
174+
raise ProtocolError(f'{_ENGINE}: invalid IPv4 address: {value!r}')
167175
try:
168176
if len(value) != 4:
169177
# Dotted-decimal ASCII text, the actual PyPCAPFile 0.12.0 form --
@@ -172,7 +180,7 @@ def _parse_ipv4_address(value: 'Any') -> 'IPv4Address':
172180
return ipaddress.IPv4Address(value.decode('ascii'))
173181
return ipaddress.IPv4Address(value)
174182
except (ValueError, UnicodeDecodeError) as error:
175-
raise ProtocolError(f'invalid PyPCAPFile IPv4 address: {value!r}') from error
183+
raise ProtocolError(f'{_ENGINE}: invalid IPv4 address: {value!r}') from error
176184

177185

178186
def _parse_mac_address(value: 'Any') -> 'str':
@@ -201,14 +209,14 @@ def _parse_mac_address(value: 'Any') -> 'str':
201209
202210
"""
203211
if not isinstance(value, (bytes, bytearray)):
204-
raise ProtocolError(f'invalid PyPCAPFile MAC address: {value!r}')
212+
raise ProtocolError(f'{_ENGINE}: invalid MAC address: {value!r}')
205213
raw = bytes(value)
206214
if len(raw) == 6:
207215
return raw.hex(':')
208216
try:
209217
return raw.decode('ascii')
210218
except UnicodeDecodeError as error:
211-
raise ProtocolError(f'invalid PyPCAPFile MAC address: {value!r}') from error
219+
raise ProtocolError(f'{_ENGINE}: invalid MAC address: {value!r}') from error
212220

213221

214222
def _maybe_unhex(value: 'bytes') -> 'bytes':
@@ -410,9 +418,9 @@ def _decline_ipv6_tcp(packet: 'Packet', count: 'int') -> 'None':
410418
_ipv6_tcp_warned[key] = anchor
411419
while config.IPV6_TCP_WARNED_LIMIT != -1 and len(_ipv6_tcp_warned) > config.IPV6_TCP_WARNED_LIMIT:
412420
_ipv6_tcp_warned.popitem(last=False)
413-
warn(f"Frame {count}: TCP over IPv6 is left out of TCP reassembly and flow tracing, as "
414-
"'pypcapfile' has no IPv6 decoder; later such frames of this capture are left out "
415-
'without another warning', AttributeWarning, stacklevel=stacklevel())
421+
warn(f'{_ENGINE}: frame {count}: TCP over IPv6 is left out of TCP reassembly and flow '
422+
"tracing, as 'pypcapfile' has no IPv6 decoder; later such frames of this capture are "
423+
'left out without another warning', AttributeWarning, stacklevel=stacklevel())
416424

417425

418426
def _transport(ipv4: 'IP') -> 'Optional[bytes]':
@@ -747,7 +755,7 @@ def ipv6_reassembly(packet: 'Packet', *, count: 'int' = -1) -> 'IP_Packet[IPv6Ad
747755
UnsupportedCall: Always, as `PyPCAPFile`_ has no IPv6 decoder.
748756
749757
"""
750-
raise UnsupportedCall('IPv6 reassembly is not supported by the PyPCAPFile engine: '
758+
raise UnsupportedCall(f'{_ENGINE}: IPv6 reassembly is not supported: '
751759
"'pypcapfile' has no IPv6 decoder, so no IPv6 fragment header "
752760
'can be read')
753761

‎pcapkit/toolkit/pyshark.py‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
from typing import TYPE_CHECKING, cast
2020

2121
from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
22+
from pcapkit.foundation.engines.pyshark import PyShark
2223
from pcapkit.foundation.traceflow.data.tcp import Packet as TF_TCP_Packet
2324
from pcapkit.utilities.exceptions import MissingKeyError, ProtocolError
2425

@@ -29,6 +30,13 @@
2930

3031
__all__ = ['packet2dict', 'tcp_traceflow', 'ENCAP_TYPE_TO_LINKTYPE', 'FILTER_NAME_TO_LINKTYPE']
3132

33+
#: Message prefix shared by every message below, read off
34+
#: :attr:`PyShark.__engine_name__
35+
#: <pcapkit.foundation.engines.pyshark.PyShark.__engine_name__>` rather than
36+
#: spelled out, so the engine cannot be renamed there and still be named the old
37+
#: way here (:issue:`2304`).
38+
_ENGINE = PyShark.__engine_name__
39+
3240
#: ``frame.encap_type`` -- Wireshark's internal ``WTAP_ENCAP_*`` number, which |pyshark|_
3341
#: exposes as ``packet.frame_info.encap_type`` -- to the matching
3442
#: :class:`~pcapkit.const.reg.linktype.LinkType` member. This is :func:`tcp_traceflow`'s primary
@@ -343,7 +351,7 @@ def _parse_flag(value: 'Any', name: 'str') -> 'bool':
343351
flag = _BOOLEAN_FIELD.get(str(value))
344352
if flag is not None:
345353
return flag
346-
raise ProtocolError(f'invalid PyShark boolean field {name}: {value!r}')
354+
raise ProtocolError(f'{_ENGINE}: invalid boolean field {name}: {value!r}')
347355

348356

349357
def _parse_epoch(value: 'Any') -> 'float':
@@ -362,7 +370,7 @@ def _parse_epoch(value: 'Any') -> 'float':
362370
try:
363371
return float(decimal.Decimal(str(value)))
364372
except decimal.InvalidOperation:
365-
raise ProtocolError(f'invalid PyShark frame.time_epoch: {value!r}') from None
373+
raise ProtocolError(f'{_ENGINE}: invalid frame.time_epoch: {value!r}') from None
366374

367375

368376
def _absolute(tcp: 'Any', name: 'str') -> 'int':
@@ -600,7 +608,7 @@ def tcp_traceflow(packet: 'Packet', *, count: 'int' = -1) -> 'TF_TCP_Packet | No
600608
# first layer that is not the frame layer.
601609
frame = _frame_layer(packet)
602610
if frame is None:
603-
raise ProtocolError(f'PyShark packet {packet.number} has no frame layer')
611+
raise ProtocolError(f'{_ENGINE}: packet {packet.number} has no frame layer')
604612
encap_type = getattr(frame, 'encap_type', None)
605613
if encap_type is None:
606614
name = [layer for layer in packet.layers if layer is not frame][0].layer_name

‎pcapkit/toolkit/scapy.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939

4040
from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
4141
from pcapkit.const.reg.transtype import TransType as Enum_TransType
42+
from pcapkit.foundation.engines.scapy import Scapy
4243
from pcapkit.foundation.reassembly.data.ip import Packet as IP_Packet
4344
from pcapkit.foundation.reassembly.data.tcp import Packet as TCP_Packet
4445
from pcapkit.foundation.traceflow.data.data import FrameRecord
@@ -55,11 +56,18 @@
5556
from pcapkit.utilities.exceptions import MissingKeyError, ModuleNotFound, stacklevel
5657
from pcapkit.utilities.warnings import ScapyWarning, warn
5758

59+
#: Message prefix shared by every message below, read off
60+
#: :attr:`Scapy.__engine_name__
61+
#: <pcapkit.foundation.engines.scapy.Scapy.__engine_name__>` rather than spelled
62+
#: out, so the engine cannot be renamed there and still be named the old way
63+
#: here (:issue:`2304`).
64+
_ENGINE = Scapy.__engine_name__
65+
5866
try:
5967
import scapy
6068
except ModuleNotFoundError:
6169
scapy = None
62-
warn("dependency package 'Scapy' not found",
70+
warn(f"{_ENGINE}: dependency package 'scapy' not found",
6371
ScapyWarning, stacklevel=stacklevel())
6472

6573
if TYPE_CHECKING:

0 commit comments

Comments
 (0)