Skip to content

Commit 51d07f7

Browse files
committed
refactor(corekit)!: move the byte-order field helpers into corekit (#1711)
packet_byteorder and byteorder_callback act on a NumberField and on the __packet__ key SchemaField hands a nested schema, but lived under one protocol family's schema package. - corekit: git mv pcapkit/protocols/schema/misc/byteorder.py to pcapkit/corekit/fields/byteorder.py, next to the NumberField and SchemaField it serves. It imports only sys and typing at runtime, so no cycle; it is not added to corekit.fields' __all__. - protocols: the old module is removed with no re-export, so importing pcapkit.protocols.schema.misc.byteorder now raises ModuleNotFoundError; frame.py and pcapng.py import from corekit. - docs: the page moves to corekit/fields/byteorder.rst; the old page and its toctree entry are removed, and every reference names the new module. - tests: the #1519 tests move to tests/corekit and run against the new path, plus an old-path-is-gone test and a no-upward-import check. New tests fail on 94bce81 and origin/main; touched suites pass on 3.8, 3.9, 3.10, 3.11 and 3.14; Sphinx warnings unchanged at 45. Closes #1711
1 parent 27ccb5f commit 51d07f7

14 files changed

Lines changed: 74 additions & 34 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Byte-Order Helpers
2+
==================
3+
4+
.. module:: pcapkit.corekit.fields.byteorder
5+
6+
:mod:`pcapkit.corekit.fields.byteorder` contains the field callback that reads
7+
a capture file's byte order out of the packet data. It is shared by the PCAP
8+
frame header (:mod:`~pcapkit.protocols.schema.misc.pcap.frame`) and the PCAP-NG
9+
blocks (:mod:`~pcapkit.protocols.schema.misc.pcapng`).
10+
11+
Auxiliary Functions
12+
-------------------
13+
14+
.. autofunction:: pcapkit.corekit.fields.byteorder.byteorder_callback
15+
.. autofunction:: pcapkit.corekit.fields.byteorder.packet_byteorder

‎docs/source/pcapkit/corekit/fields/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ describe the structure of protocol headers.
1515
ipaddress
1616
collections
1717
misc
18+
byteorder
1819

1920
Every field class is a :class:`~pcapkit.corekit.fields.field.FieldBase`
2021
subclass, responsible for parsing and/or formatting the field value. The class

‎docs/source/pcapkit/protocols/misc/byteorder.rst‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs/source/pcapkit/protocols/misc/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,5 @@ indication of empty payload, the PCAP header classes, and the PCAP-NG
1616

1717
pcap
1818
pcapng
19-
byteorder
2019
raw
2120
null

‎docs/source/pcapkit/protocols/misc/pcapng.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -512,9 +512,9 @@ Auxiliary Functions
512512
-------------------
513513

514514
The byte order of every block but the Section Header Block is read by
515-
:func:`~pcapkit.protocols.schema.misc.byteorder.byteorder_callback`, which is
515+
:func:`~pcapkit.corekit.fields.byteorder.byteorder_callback`, which is
516516
shared with the PCAP frame header and documented in
517-
:mod:`pcapkit.protocols.schema.misc.byteorder`.
517+
:mod:`pcapkit.corekit.fields.byteorder`.
518518

519519
.. autofunction:: pcapkit.protocols.schema.misc.pcapng.shb_byteorder_callback
520520
.. autofunction:: pcapkit.protocols.schema.misc.pcapng.pcapng_block_selector

‎examples/generators/endian.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
That is how GitHub issue #605 survived: ``Frame.unpack`` seeded the byte order
1414
under the key ``bytesorder`` where ``byteorder_callback`` -- then in
1515
:file:`pcapkit/protocols/schema/misc/pcap/frame.py`, now in
16-
:file:`pcapkit/protocols/schema/misc/byteorder.py` -- reads ``byteorder``, so the
16+
:file:`pcapkit/corekit/fields/byteorder.py` -- reads ``byteorder``, so the
1717
lookup always missed and always fell back to :data:`sys.byteorder`. Reading a
1818
big-endian capture then byte-swapped ``ts_sec``, ``ts_usec``, ``incl_len`` and
1919
``orig_len`` -- and because ``incl_len`` is the payload length, the first record

pcapkit/protocols/schema/misc/byteorder.py renamed to pcapkit/corekit/fields/byteorder.py

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
# -*- coding: utf-8 -*-
2-
"""byte-order helpers shared by the PCAP and PCAP-NG schemas
2+
"""byte-order field helpers
33
4-
:mod:`pcapkit.protocols.schema.misc.byteorder` holds the field callback that
5-
reads a capture file's byte order out of the packet data. The record header of
6-
a classic PCAP file (:mod:`~pcapkit.protocols.schema.misc.pcap.frame`) and the
4+
:mod:`pcapkit.corekit.fields.byteorder` holds the field callback that reads a
5+
capture file's byte order out of the packet data. The record header of a
6+
classic PCAP file (:mod:`~pcapkit.protocols.schema.misc.pcap.frame`) and the
77
blocks of a PCAP-NG file (:mod:`~pcapkit.protocols.schema.misc.pcapng`) both use
8-
it.
8+
it. It acts on a :class:`~pcapkit.corekit.fields.numbers.NumberField` and on the
9+
``__packet__`` key :class:`~pcapkit.corekit.fields.misc.SchemaField` hands a
10+
nested schema, so it lives with the fields rather than with either schema
11+
(:issue:`1711`).
912
1013
"""
1114

‎pcapkit/corekit/fields/misc.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -567,7 +567,7 @@ def nested_packet_context(packet: 'dict[str, Any]') -> 'dict[str, Any]':
567567
reserved ``__packet__`` key, for a callback that needs to name the
568568
outer schema specifically rather than whichever schema happens to
569569
declare a given field -- see
570-
:func:`pcapkit.protocols.schema.misc.byteorder.packet_byteorder` and
570+
:func:`pcapkit.corekit.fields.byteorder.packet_byteorder` and
571571
:meth:`~pcapkit.protocols.schema.misc.pcapng.BlockType.post_process`
572572
for why that distinction matters, and note that both already
573573
hand-roll this exact fallback and so are unaffected by (and do not

‎pcapkit/protocols/schema/misc/pcap/frame.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44

55
from typing import TYPE_CHECKING
66

7+
from pcapkit.corekit.fields.byteorder import byteorder_callback
78
from pcapkit.corekit.fields.misc import PayloadField
89
from pcapkit.corekit.fields.numbers import UInt32Field
9-
from pcapkit.protocols.schema.misc.byteorder import byteorder_callback
1010
from pcapkit.protocols.schema.schema import Schema, schema_final
1111

1212
__all__ = ['Frame']

‎pcapkit/protocols/schema/misc/pcapng.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
from pcapkit.const.pcapng.secrets_type import SecretsType as Enum_SecretsType
1818
from pcapkit.const.pcapng.verdict_type import VerdictType as Enum_VerdictType
1919
from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
20+
from pcapkit.corekit.fields.byteorder import byteorder_callback, packet_byteorder
2021
from pcapkit.corekit.fields.collections import OptionField
2122
from pcapkit.corekit.fields.ipaddress import (IPv4AddressField, IPv4InterfaceField,
2223
IPv6AddressField, IPv6InterfaceField)
@@ -26,7 +27,6 @@
2627
from pcapkit.corekit.fields.strings import (BitField, BytesField, DecodedString, PaddingField,
2728
StringField)
2829
from pcapkit.corekit.multidict import MultiDict, OrderedMultiDict
29-
from pcapkit.protocols.schema.misc.byteorder import byteorder_callback, packet_byteorder
3030
from pcapkit.protocols.schema.schema import EnumSchema, Schema, schema_final
3131
from pcapkit.utilities.exceptions import FieldValueError, ProtocolError, stacklevel
3232
from pcapkit.utilities.logging import SPHINX_TYPE_CHECKING
@@ -177,7 +177,7 @@ def shb_byteorder_callback(field: 'NumberField', packet: 'dict[str, Any]') -> 'N
177177
one would otherwise inherit the *previous* section's byte order. The magic
178178
is therefore also written back as ``packet['byteorder']``, which is what the
179179
SHB's own options -- read by
180-
:func:`~pcapkit.protocols.schema.misc.byteorder.byteorder_callback`, after this field --
180+
:func:`~pcapkit.corekit.fields.byteorder.byteorder_callback`, after this field --
181181
resolve their byte order from.
182182
183183
A Section Header Block of 12 octets has no room for the magic, and its

0 commit comments

Comments
 (0)