Root Protocol¶
pcapkit.protocols.protocol
contains
Protocol
only, which is
an abstract base class for all protocol family, with pre-defined
utility arguments and methods of specified protocols.
- class pcapkit.protocols.protocol.Protocol(file=None, length=None, **kwargs)[source]¶
Bases:
Generic
[PT
]Abstract base class for all protocol family.
- Parameters
*args (Any) – Arbitrary positional arguments.
**kwargs (Any) – Arbitrary keyword arguments.
- Return type
Protocol[PT]
- __init__(file: BinaryIO, length: Optional[int] = None, **kwargs: Any) None [source]¶
- __init__(**kwargs: Any) None
Initialisation.
- Parameters
- __post_init__(file: BinaryIO, length: Optional[int] = None, **kwargs: Any) None [source]¶
- __post_init__(**kwargs: Any) None
Post initialisation hook.
- Parameters
See also
For construction arguments, please refer to
self.make
.- Return type
- __repr__()[source]¶
Returns representation of parsed protocol data.
Example
>>> protocol <Frame alias='...' frame=(..., packet=b'...', sethernet=..., protocols='Ethernet:IPv6:Raw')>
- Return type
- __str__()[source]¶
Returns formatted hex representation of source data stream.
Example
>>> protocol Frame(..., packet=b"...", sethernet=..., protocols='Ethernet:IPv6:Raw') >>> print(protocol) 00 00 00 00 00 00 00 a6 87 f9 27 93 16 ee fe 80 00 00 00 ..........'........ 00 00 00 1c cd 7c 77 ba c7 46 b7 87 00 0e aa 00 00 00 00 .....|w..F......... fe 80 00 00 00 00 00 00 1c cd 7c 77 ba c7 46 b7 01 01 a4 ..........|w..F.... 5e 60 d9 6b 97 ^`.k.
- Return type
- __iter__()[source]¶
Iterate through
self._data
.- Return type
- __getitem__(key)[source]¶
Subscription (
getitem
) support.If
key
is aProtocol
object, the method will fetch its indexes (id()
).Later, search the packet’s chain of protocols with the calculated
key
.If no matches, then raises
ProtocolNotFound
.
- Parameters
- Returns
The sub-packet from the current packet of indexed protocol.
- Raises
ProtocolNotFound – If
key
is not in the current packet.- Return type
See also
The method calls
self.expand_comp
to handle thekey
and expand it for robust searching.
- __contains__(name)[source]¶
Returns if certain protocol is in the instance.
See also
The method calls
self.expand_comp
to handle thename
and expand it for robust searching.
- abstract classmethod __index__()[source]¶
Numeral registry index of the protocol.
- Return type
StdlibEnum | AenumEnum
- __hash__()[source]¶
Return the hash value for
self._data
.- Return type
- property protochain: ProtoChain¶
Protocol chain of current instance.
- Return type
- classmethod id()[source]¶
Index ID of the protocol.
By default, it returns the name of the protocol. In certain cases, the method may return multiple values.
- static decode(byte, *, encoding=None, errors='strict')[source]¶
-
Should decoding failed using
encoding
, the method will try again decoding thebytes
as'unicode_escape'
with'replace'
for error handling.See also
The method is a wrapping function for
bytes.decode()
.- Parameters
byte (
bytes
) – Source bytestring.encoding (
Optional
[str
]) – The encoding with which to decode thebytes
. If not provided,pcapkit
will first try detecting its encoding usingchardet
. The fallback encoding would is UTF-8.errors (
Literal
[‘strict’, ‘ignore’, ‘replace’]) – The error handling scheme to use for the handling of decoding errors. The default is'strict'
meaning that decoding errors raise aUnicodeDecodeError
. Other possible values are'ignore'
and'replace'
as well as any other name registered withcodecs.register_error()
that can handleUnicodeDecodeError
.
- Return type
- static unquote(url, *, encoding='utf-8', errors='replace')[source]¶
Unquote URLs into readable format.
Should decoding failed , the method will try again replacing
'%'
with'\x'
then decoding theurl
as'unicode_escape'
with'replace'
for error handling.See also
This method is a wrapper function for
urllib.parse.unquote()
.- Parameters
url (
str
) – URL string.encoding (
str
) – The encoding with which to decode thebytes
.errors (
Literal
[‘strict’, ‘ignore’, ‘replace’]) – The error handling scheme to use for the handling of decoding errors. The default is'strict'
meaning that decoding errors raise aUnicodeDecodeError
. Other possible values are'ignore'
and'replace'
as well as any other name registered withcodecs.register_error()
that can handleUnicodeDecodeError
.
- Return type
- static expand_comp(value)[source]¶
Expand protocol class to protocol name.
The method is used to expand protocol class to protocol name, in the following manner:
If
value
is a protocol instance, the method will return the protocol class, and the protocol names in upper case obtained fromProtocol.id
.If
value
is a protocol class, the method will return the protocol class itself, and the protocols names in upper case obtained fromProtocol.id
.If
value
isstr
, the method will attempt to search for the existing registered protocol class frompcapkit.protocols.__proto__
and follow step 2; otherwise, return the value itself.
- _read_protos(size)[source]¶
Read next layer protocol type.
If succeed, returns the enum of next layer protocol.
If fail, returns
None
.
- Parameters
size (int) – buffer size
- Return type
Optional[StdlibEnum | AenumEnum]
- _read_fileng(*args, **kwargs)[source]¶
Read file buffer (
self._file
).This method wraps the
file.read
call.
- _read_unpack(size=1, *, signed=False, lilendian=False, quiet=False)[source]¶
Read bytes and unpack for integers.
- Parameters
- Return type
- Returns
Unpacked data upon success
- Raises
StructError – If unpack (
struct.pack()
) failed, andstruct.error
raised.
- _read_packet(length: Optional[int] = None, *, header: None = None) bytes [source]¶
- _read_packet(*, header: int, payload: Optional[int] = None, discard: Literal[True]) bytes
- _read_packet(*, header: int, payload: Optional[int] = None, discard: Literal[False] = False) DataType_Packet
Read raw packet data.
- Parameters
length – length of the packet
header – length of the packet header
payload – length of the packet payload
discard – flag if discard header data
- classmethod _make_pack(integer, *, size=1, signed=False, lilendian=False)[source]¶
Pack integers to bytes.
- classmethod _make_index(name: int | StdlibEnum | AenumEnum, *, pack: Literal[False] = False) int [source]¶
- classmethod _make_index(name: int | StdlibEnum | AenumEnum, *, pack: Literal[True], size: int = 4, signed: bool = False, lilendian: bool = False) bytes
- classmethod _make_index(name: str, default: Optional[int] = None, *, namespace: Type[StdlibEnum] | Type[AenumEnum], pack: Literal[False] = False) int
- classmethod _make_index(name: str, default: Optional[int] = None, *, namespace: Type[StdlibEnum] | Type[AenumEnum], pack: Literal[True], size: int = 4, signed: bool = False, lilendian: bool = False) bytes
- classmethod _make_index(name: str, default: Optional[int] = None, *, namespace: dict[int, str], reversed: Literal[False] = False, pack: Literal[False] = False) int
- classmethod _make_index(name: str, default: Optional[int] = None, *, namespace: dict[int, str], reversed: Literal[False] = False, pack: Literal[True], size: int = 4, signed: bool = False, lilendian: bool = False) bytes
- classmethod _make_index(name: str, default: Optional[int] = None, *, namespace: dict[str, int], reversed: Literal[True], pack: Literal[False] = False) int
- classmethod _make_index(name: str, default: Optional[int] = None, *, namespace: dict[str, int], reversed: Literal[True], pack: Literal[True], size: int = 4, signed: bool = False, lilendian: bool = False) bytes
Return first index of
name
from adict
or enumeration.- Parameters
name – item to be indexed
default – default value
namespace – namespace for item
reversed – if namespace is
str -> int
pairspack – if need
struct.pack()
to pack the resultsize – buffer size
signed – signed flag
lilendian – little-endian flag
- Returns
Index of
name
from a dict or enumeration. Ifpack
isTrue
, returnsbytes
; otherwise, returnsint
.- Raises
ProtocolNotImplemented – If
name
is NOT innamespace
anddefault
isNone
.
- __layer__: Optional[Literal['Link', 'Internet', 'Transport', 'Application']]¶
- __proto__: DefaultDict[int, tuple[str, str]]¶
&
self._import_next_layer
. The values should be a tuple representing the module name and class name.
- _info: PT¶
Parsed packet data.
- _file: BinaryIO¶
Source packet stream.