Skip to content

Commit 0f6dce8

Browse files
committed
refactor(corekit): move the stream proxy classes into corekit.io (#1516)
- `_PeekableStream` (foundation/extraction.py) and `_NamedStream` (foundation/engines/pypcapfile.py) move to `pcapkit.corekit.io` as the public `PeekableStream` and `NamedStream`, beside `SeekableReader`, and join its `__all__`. Bodies are unchanged; both importers now take them from there. - Document both on the corekit io page. - tests/corekit/test_io_stream_proxies_1516_unit.py pins peek semantics, attribute forwarding, `.name` and read forwarding from the new module; the `_NamedStream` test in test_pypcapfile_engine.py moves there.
1 parent 81efa60 commit 0f6dce8

6 files changed

Lines changed: 282 additions & 96 deletions

File tree

‎docs/source/pcapkit/corekit/io.rst‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
1-
Seekable I/O Object
2-
===================
1+
I/O Objects
2+
===========
33

44
.. module:: pcapkit.corekit.io
55

66
:mod:`pcapkit.corekit.io` contains
77
:class:`~pcapkit.corekit.io.SeekableReader`, a seekable customisation of
8-
:class:`io.BufferedReader`.
8+
:class:`io.BufferedReader`, and two stream proxies:
9+
:class:`~pcapkit.corekit.io.PeekableStream`, which adds ``peek`` to a seekable
10+
stream, and :class:`~pcapkit.corekit.io.NamedStream`, which gives a stream a
11+
``name``.
912

1013
.. autoclass:: pcapkit.corekit.io.SeekableReader
1114
:no-members:
@@ -41,3 +44,14 @@ Seekable I/O Object
4144

4245
.. automethod:: fileno
4346
.. automethod:: isatty
47+
48+
.. autoclass:: pcapkit.corekit.io.PeekableStream
49+
:no-members:
50+
51+
.. automethod:: peek
52+
53+
.. autoclass:: pcapkit.corekit.io.NamedStream
54+
:no-members:
55+
56+
.. autoattribute:: name
57+
.. automethod:: read

‎pcapkit/corekit/io.py‎

Lines changed: 78 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
# -*- coding: utf-8 -*-
2-
"""Seekable I/O Object
3-
=========================
2+
"""I/O Objects
3+
===============
44
55
.. module:: pcapkit.corekit.io
66
77
:mod:`pcapkit.corekit.io` contains seekable I/O object
88
:class:`~pcapkit.corekit.io.SeekableReader`, which is a customised
9-
implementation to :class:`io.BufferedReader`.
9+
implementation to :class:`io.BufferedReader`, and the stream proxies
10+
:class:`~pcapkit.corekit.io.PeekableStream`, which adds ``peek`` to a
11+
seekable stream, and :class:`~pcapkit.corekit.io.NamedStream`, which gives
12+
a stream a ``name``.
1013
1114
"""
1215
import io
@@ -19,11 +22,11 @@
1922

2023
if TYPE_CHECKING:
2124
from io import BytesIO, RawIOBase
22-
from typing import IO, Iterable, Optional
25+
from typing import IO, Any, BinaryIO, Iterable, Optional
2326

2427
from typing_extensions import Buffer
2528

26-
__all__ = ['SeekableReader']
29+
__all__ = ['SeekableReader', 'PeekableStream', 'NamedStream']
2730

2831

2932
class SeekableReader(io.BufferedReader):
@@ -677,3 +680,73 @@ def peek(self, size: 'int' = 0) -> 'bytes':
677680
self._write_buffer(buf_tmp)
678681
buf += buf_tmp
679682
return buf
683+
684+
685+
class PeekableStream:
686+
"""Give a seekable binary stream without ``peek`` one.
687+
688+
:class:`~pcapkit.foundation.extraction.Extractor` and the PCAP-NG engine
689+
read ahead with ``peek``, which :class:`io.BufferedReader` has and a plain
690+
:class:`typing.IO` such as :class:`io.BytesIO` does not (#1506). The
691+
read-ahead is a read and a seek back, and every other attribute is the
692+
stream's own. It is not an :class:`io.IOBase`, so it has no finaliser that
693+
could close the caller's stream behind their back (#610).
694+
695+
Arguments:
696+
stream: seekable binary stream
697+
698+
"""
699+
700+
def __init__(self, stream: 'IO[bytes]') -> 'None':
701+
self._stream = stream
702+
703+
def peek(self, size: 'int' = 0) -> 'bytes':
704+
"""Return up to ``size`` octets, at least one if any remain, without consuming them.
705+
706+
Arguments:
707+
size: number of octets wanted
708+
709+
Returns:
710+
The octets at the current position.
711+
712+
"""
713+
pos = self._stream.tell()
714+
try:
715+
return self._stream.read(max(size, 1))
716+
finally:
717+
self._stream.seek(pos, io.SEEK_SET)
718+
719+
def __getattr__(self, name: 'str') -> 'Any':
720+
return getattr(self._stream, name)
721+
722+
723+
class NamedStream:
724+
"""Read-only proxy that gives a stream the ``name`` attribute.
725+
726+
:func:`pcapfile.savefile.load_savefile` dereferences ``input_file.name``
727+
unconditionally, on the way into its trace helper. That is fine for the
728+
:class:`~io.BufferedReader` :class:`~pcapkit.foundation.extraction.Extractor`
729+
normally holds, but not for the :class:`~pcapkit.corekit.io.SeekableReader`
730+
it substitutes when the caller supplied a non-seekable stream -- that class
731+
exposes no ``name``, so the load would fail with :exc:`AttributeError` before
732+
a single byte was read.
733+
734+
Args:
735+
stream: Underlying binary stream.
736+
name: Name to report as :attr:`name`.
737+
738+
"""
739+
740+
def __init__(self, stream: 'BinaryIO', name: 'str') -> 'None':
741+
self._stream = stream
742+
#: Name of the underlying stream.
743+
self.name = name
744+
745+
def read(self, size: 'int' = -1) -> 'bytes':
746+
"""Read from the underlying stream.
747+
748+
Args:
749+
size: Number of bytes to read; all remaining bytes if negative.
750+
751+
"""
752+
return self._stream.read(size)

‎pcapkit/foundation/engines/pypcapfile.py‎

Lines changed: 3 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
from typing import TYPE_CHECKING, cast
1717

1818
from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
19+
from pcapkit.corekit.io import NamedStream
1920
from pcapkit.foundation.engines.engine import EngineBase
2021
from pcapkit.foundation.reassembly import ReassemblyManager
2122
from pcapkit.utilities.exceptions import FormatError, stacklevel
@@ -24,45 +25,13 @@
2425
__all__ = ['PyPCAPFile']
2526

2627
if TYPE_CHECKING:
27-
from typing import Any, BinaryIO, Callable, Iterator, Optional
28+
from typing import Any, Callable, Iterator, Optional
2829

2930
from pcapfile.structs import pcap_packet as PCAPFilePacket
3031

3132
from pcapkit.foundation.extraction import Extractor
3233

3334

34-
class _NamedStream:
35-
"""Read-only proxy that gives a stream the ``name`` attribute.
36-
37-
:func:`pcapfile.savefile.load_savefile` dereferences ``input_file.name``
38-
unconditionally, on the way into its trace helper. That is fine for the
39-
:class:`~io.BufferedReader` :class:`~pcapkit.foundation.extraction.Extractor`
40-
normally holds, but not for the :class:`~pcapkit.corekit.io.SeekableReader`
41-
it substitutes when the caller supplied a non-seekable stream -- that class
42-
exposes no ``name``, so the load would fail with :exc:`AttributeError` before
43-
a single byte was read.
44-
45-
Args:
46-
stream: Underlying binary stream.
47-
name: Name to report as :attr:`name`.
48-
49-
"""
50-
51-
def __init__(self, stream: 'BinaryIO', name: 'str') -> 'None':
52-
self._stream = stream
53-
#: Name of the underlying stream.
54-
self.name = name
55-
56-
def read(self, size: 'int' = -1) -> 'bytes':
57-
"""Read from the underlying stream.
58-
59-
Args:
60-
size: Number of bytes to read; all remaining bytes if negative.
61-
62-
"""
63-
return self._stream.read(size)
64-
65-
6635
class PyPCAPFile(EngineBase['PCAPFilePacket']):
6736
"""PyPCAPFile engine support.
6837
@@ -233,7 +202,7 @@ def run(self) -> 'None':
233202
"so 'ipv6=True' will be ignored", AttributeWarning, stacklevel=stacklevel())
234203

235204
sfile = pcapfile.savefile.load_savefile(
236-
_NamedStream(ext._ifile, ext._ifnm), layers=0, lazy=True,
205+
NamedStream(ext._ifile, ext._ifnm), layers=0, lazy=True,
237206
)
238207
self._dlink = Enum_LinkType.get(sfile.header.ll_type)
239208
self._declf = self._get_decoder(sfile.header.ll_type)

‎pcapkit/foundation/extraction.py‎

Lines changed: 3 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
from dictdumper.dumper import Dumper
2626

2727
from pcapkit.corekit.context import ContextRegistry
28-
from pcapkit.corekit.io import SeekableReader
28+
from pcapkit.corekit.io import PeekableStream, SeekableReader
2929
from pcapkit.corekit.module import ModuleDescriptor
3030
from pcapkit.dumpkit.common import make_dumper
3131
from pcapkit.foundation.engines.engine import Engine, EngineBase
@@ -187,44 +187,6 @@ def _restore_shipped_dumper(registry: 'dict[str, Any]', format: 'str', # pylint
187187
_PATH_ENGINES = frozenset({'scapy', 'pyshark', 'pypcap', 'pcap_ct'})
188188

189189

190-
class _PeekableStream:
191-
"""Give a seekable binary stream without ``peek`` one.
192-
193-
:class:`Extractor` and the PCAP-NG engine read ahead with ``peek``, which
194-
:class:`io.BufferedReader` has and a plain :class:`typing.IO` such as
195-
:class:`io.BytesIO` does not (#1506). The read-ahead is a read and a seek
196-
back, and every other attribute is the stream's own. It is not an
197-
:class:`io.IOBase`, so it has no finaliser that could close the caller's
198-
stream behind their back (#610).
199-
200-
Arguments:
201-
stream: seekable binary stream
202-
203-
"""
204-
205-
def __init__(self, stream: 'IO[bytes]') -> 'None':
206-
self._stream = stream
207-
208-
def peek(self, size: 'int' = 0) -> 'bytes':
209-
"""Return up to ``size`` octets, at least one if any remain, without consuming them.
210-
211-
Arguments:
212-
size: number of octets wanted
213-
214-
Returns:
215-
The octets at the current position.
216-
217-
"""
218-
pos = self._stream.tell()
219-
try:
220-
return self._stream.read(max(size, 1))
221-
finally:
222-
self._stream.seek(pos, io.SEEK_SET)
223-
224-
def __getattr__(self, name: 'str') -> 'Any':
225-
return getattr(self._stream, name)
226-
227-
228190
class Extractor(Generic[_P]):
229191
"""Extractor for PCAP files.
230192
@@ -1487,8 +1449,8 @@ def __init__(self,
14871449
self._ifile = SeekableReader(self._ifile, buffer_size, buffer_save, buffer_path,
14881450
stream_closing=self._flag_s)
14891451
elif not hasattr(self._ifile, 'peek'):
1490-
logger.debug('input stream has no peek(), wrapping it in _PeekableStream')
1491-
self._ifile = cast('BufferedReader', _PeekableStream(self._ifile))
1452+
logger.debug('input stream has no peek(), wrapping it in PeekableStream')
1453+
self._ifile = cast('BufferedReader', PeekableStream(self._ifile))
14921454

14931455
if not self._flag_q:
14941456
output, ext = self.__output__[fmt]

0 commit comments

Comments
 (0)