Skip to content

docs: prose sweep after the defect wave (foundation-docs) (#1103) #1186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JarryShaw merged 1 commit into from
Oct 7, 2026
Merged

docs: prose sweep after the defect wave (foundation-docs) (#1103) #1186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/source/ext.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -510,6 +510,11 @@ The following code snippet shows how to create a new engine class:
f'Frame {extractor._frnum:>3d}: {packet2chain(packet)}'
) # print verbose message as `Frame XXX: Ethernet:IP:TCP:...`

# NOTE: The extractor's shared global-header step parses the global
# header with the built-in engine and, unless output is disabled,
# dumps it and sets the output format that `ext.format` reports.
ext.record_header()

# NOTE: Here we use the API entry point, i.e., scapy.sendrecv.sniff,
# to read the input file and extract the network packets. The API
# entry point returns an iterable instance, which is then converted
Expand Down
11 changes: 11 additions & 0 deletions docs/source/pcapkit/foundation/engines/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,17 @@ offers, and the ones that cannot say so rather than quietly doing less:
| | PCAP savefiles only, otherwise |
| | :exc:`~pcapkit.utilities.exceptions.FormatError` |
+-----------------------------------------------------------------+---------------------------------------------------------------+
| :class:`~pcapkit.foundation.engines.dpkt.DPKT`, | no PCAP output, since each frame reaches the writer as a |
| :class:`~pcapkit.foundation.engines.scapy.Scapy`, | plain :obj:`dict` -- ``json`` is written instead, with a |
| :class:`~pcapkit.foundation.engines.pyshark.PyShark`, | :class:`~pcapkit.utilities.warnings.FormatWarning` |
| :class:`~pcapkit.foundation.engines.pypcap.PyPCAP`, | |
| :class:`~pcapkit.foundation.engines.pcap_ct.PCAP_CT` and | |
| :class:`~pcapkit.foundation.engines.pypcapfile.PyPCAPFile` | |
+-----------------------------------------------------------------+---------------------------------------------------------------+
| :class:`~pcapkit.foundation.engines.pcapng.PCAPNG` | no PCAP output for a PCAP-NG input, which declares its link |
| | type and timestamp resolution per interface -- |
| | :exc:`~pcapkit.utilities.exceptions.FormatError` |
+-----------------------------------------------------------------+---------------------------------------------------------------+

Availability
------------
Expand Down
2 changes: 2 additions & 0 deletions docs/source/pcapkit/foundation/extraction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ extracts parameters from a PCAP file.
.. automethod:: make_name

.. automethod:: record_header
.. automethod:: _open_output
.. automethod:: record_frames

.. autoattribute:: __output__
Expand All @@ -63,6 +64,7 @@ extracts parameters from a PCAP file.
.. autoattribute:: _flag_e
.. autoattribute:: _flag_f
.. autoattribute:: _flag_q
.. autoattribute:: _flag_o
.. autoattribute:: _flag_r
.. autoattribute:: _flag_t
.. autoattribute:: _flag_v
Expand Down
6 changes: 3 additions & 3 deletions pcapkit/all.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,8 @@
'scapy_ipv4_reassembly', 'scapy_ipv6_reassembly', 'scapy_tcp_reassembly', 'scapy_tcp_traceflow',
# Scapy engine

# pcapkit.utilities -- unlisted since 769a17c78 (2022-05-29): its names stay
# reachable as attributes, but ``import *`` leaves out generic helpers such
# as ``warn``, ``reset``, ``configure`` and ``detect``
# pcapkit.utilities -- unlisted: its names stay reachable as attributes, but
# ``import *`` leaves out generic helpers such as ``warn``, ``reset``,
# ``configure`` and ``detect``
#'beholder_ng', 'seekset_ng', # Decorators
]
7 changes: 4 additions & 3 deletions pcapkit/dumpkit/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,9 +247,10 @@ def make_dumper(output: 'Type[ABCDumper]') -> 'Type[ABCDumper]':
# concrete writer this applies to.
escape_strings = issubclass(output, dictdumper.plist.PLIST)
# NOTE: :class:`~dictdumper.json.JSON` escapes every string *value* it
# writes, but interpolates a mapping key into ``'"{item}": '`` raw, so a key
# carrying a ``"`` or a ``\`` closes the JSON string early (GitHub issue
# #1152). The defect is :mod:`dictdumper`'s, so it is worked around here.
# writes, but interpolates a mapping key into ``'"{item}": '`` raw: a ``"``
# in a key closes the JSON string early, and a ``\`` escapes the character
# after it (GitHub issue #1152). The defect is :mod:`dictdumper`'s, so it is
# worked around here.
escape_json_keys = issubclass(output, dictdumper.json.JSON)
escape_keys = escape_strings or escape_json_keys

Expand Down
6 changes: 4 additions & 2 deletions pcapkit/dumpkit/pcap.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ class PCAPIO(DumperBase):
protocol: data link type
byteorder: header byte order
nanosecond: nanosecond-resolution file flag
**kwargs: arbitrary keyword arguments
**kwargs: further global header fields, i.e. ``thiszone``, ``sigfigs``
and ``snaplen``, and arbitrary keyword arguments

"""
if TYPE_CHECKING:
Expand Down Expand Up @@ -89,7 +90,8 @@ def __init__(self, fname: 'str', *, protocol: 'Enum_LinkType | StdlibIntEnum | A
protocol: data link type
byteorder: header byte order
nanosecond: nanosecond-resolution file flag
**kwargs: arbitrary keyword arguments
**kwargs: further global header fields, i.e. ``thiszone``,
``sigfigs`` and ``snaplen``, and arbitrary keyword arguments

"""
#: int: Frame counter.
Expand Down
4 changes: 4 additions & 0 deletions pcapkit/foundation/engines/pcapng.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,10 @@ def run(self) -> 'None':
block, and then save the related information into the internal
context storage.

Raises:
FormatError: If the first block is not a section header block, or if
the output format is PCAP.

"""
ext = self._extractor

Expand Down
22 changes: 12 additions & 10 deletions pcapkit/foundation/extraction.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,8 @@ class Extractor(Generic[_P]):

#: Input file object.
_ifile: 'BufferedReader'
#: Output file object.
#: Output writer. It holds the writer class until :meth:`_open_output`
#: replaces it with the writer, or under split mode with a factory.
_ofile: 'Dumper | Type[Dumper]'

#: Position of the input stream at the previous end of stream, or
Expand Down Expand Up @@ -668,7 +669,8 @@ def run(self) -> 'None': # pylint: disable=inconsistent-return-statements

Raises:
FormatError: If the selected engine cannot read the input's format --
for the default engine, if it is neither PCAP nor PCAP-NG.
for the default engine, if it is neither PCAP nor PCAP-NG -- or if
the built-in PCAP-NG engine reads a PCAP-NG input to PCAP output.

:rtype: None
"""
Expand Down Expand Up @@ -893,14 +895,14 @@ def record_header(self) -> 'EngineBase[_P]':
def _open_output(self, **kwargs: 'Any') -> 'None':
"""Create the output writer.

The engines call this at their global-header step, passing the header's
link type, byte order and timestamp resolution as ``protocol``,
``byteorder`` and ``nanosecond``, and the PCAP engine also its
``thiszone``, ``sigfigs`` and ``snaplen``: :class:`~pcapkit.dumpkit.pcap.PCAPIO`
writes its own global header from them, and the other writers ignore
them. :meth:`run` calls it again, without arguments, after the engine
has started, for the engines that have no such step. Only the first
call has an effect.
The built-in engines call this at their global-header step. The PCAP
engine passes the header's fields as ``protocol``, ``byteorder``,
``nanosecond``, ``thiszone``, ``sigfigs`` and ``snaplen``:
:class:`~pcapkit.dumpkit.pcap.PCAPIO` writes its own global header from
them, and the other writers ignore them. The PCAP-NG engine passes none.
:meth:`run` calls it again, without arguments, after the engine has
started, for the engines that have no such step. Only the first call has
an effect.

Under split mode, i.e. :attr:`self._flag_f <Extractor._flag_f>` is
:data:`True`, :attr:`self._ofile <Extractor._ofile>` stays a factory,
Expand Down
Loading