pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/corekit/protochain.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+"""Protocol Chain
+====================
+
+.. module:: pcapkit.corekit.protochain
+
+:mod:`pcapkit.corekit.protochain` contains special protocol
+collection class :class:`~pcapkit.corekit.protochain.ProtoChain`.
+
+"""
+import collections.abc
+import copy
+from typing import TYPE_CHECKING, overload
+
+from pcapkit.utilities.compat import cached_property
+from pcapkit.utilities.exceptions import IndexNotFound
+
+if TYPE_CHECKING:
+    from typing import Iterator, Optional, Type
+
+    from typing_extensions import Self
+
+    from pcapkit.protocols.protocol import ProtocolBase as Protocol
+
+__all__ = ['ProtoChain']
+
+
+class ProtoChain(collections.abc.Sequence):
+    """Protocols chain.
+
+    Args:
+        proto: New protocol class on the top stack.
+        alias: New protocol alias on the top stack.
+        basis: Original protocol chain as base stacks.
+
+    """
+
+    #: Internal data storage for protocol chain.
+    __data__: 'tuple[tuple[str, Type[Protocol]], ...]'
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    @cached_property
+    def protocols(self) -> 'tuple[Type[Protocol], ...]':
+        """List of protocols in the chain."""
+        return tuple(data[1] for data in self.__data__)
+
+    @cached_property
+    def aliases(self) -> 'tuple[str, ...]':
+        """Protocol names."""
+        return tuple(data[0] for data in self.__data__)
+
+    @property
+    def chain(self) -> 'str':
+        """Protocol chain string."""
+        return self.__str__()
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    @classmethod
+    def from_list(cls, data: 'list[Protocol | Type[Protocol]]') -> 'Self':
+        """Create a protocol chain from a list.
+
+        Args:
+            data: Protocol chain list.
+
+        """
+        from pcapkit.protocols.protocol import \
+            ProtocolBase as Protocol  # pylint: disable=import-outside-toplevel
+
+        temp_data = []
+        for proto in data:
+            if isinstance(proto, Protocol):
+                alias = proto.alias
+                proto = type(proto)
+
+            temp_data.append((alias, proto))
+
+        obj = cls.__new__(cls)
+        obj.__data__ = tuple(temp_data)
+        return obj
+
+    def index(self, value: 'str | Protocol | Type[Protocol]',
+              start: 'Optional[int]' = None, stop: 'Optional[int]' = None) -> 'int':
+        """First index of ``value``.
+
+        Args:
+            value: Value to search.
+            start: start offset.
+            stop: stop offset.
+
+        Raises:
+            IndexNotFound: If the value is not present.
+
+        """
+        if start is None:
+            start = 0
+        elif start < 0:
+            start = max(len(self) + start, 0)
+
+        if stop is not None and stop < 0:
+            stop += len(self)
+
+        # prepare comparison values
+        from pcapkit.protocols.protocol import \
+            ProtocolBase as Protocol  # pylint: disable=import-outside-toplevel
+        comp = Protocol.expand_comp(value)
+
+        pool = self.__data__[start:stop]
+        for idx, (alias, proto) in enumerate(pool):
+            test_comp = (proto, alias.upper(), *(name.upper() for name in proto.id()))
+            for test in comp:
+                if test in test_comp:
+                    return start + idx
+        raise IndexNotFound(f'{value!r} is not in {self.__class__.__name__!r}')
+
+    def count(self, value: 'str | Protocol | Type[Protocol]') -> int:
+        """Number of occurrences of ``value``.
+
+        Args:
+            value: Value to search.
+
+        """
+        # prepare comparison values
+        from pcapkit.protocols.protocol import \
+            ProtocolBase as Protocol  # pylint: disable=import-outside-toplevel
+        comp = Protocol.expand_comp(value)
+
+        cnt = 0
+        for alias, proto in self.__data__:
+            test_comp = (proto, alias.upper(), *(name.upper() for name in proto.id()))
+            for test in comp:
+                if test in test_comp:
+                    cnt += 1
+                    break
+        return cnt
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __init__(self, proto: 'Protocol | Type[Protocol]', alias: 'Optional[str]' = None, *,
+                 basis: 'Optional[ProtoChain]' = None):
+        """Initialisation.
+
+        Args:
+            proto: New protocol class on the top stack.
+            alias: New protocol alias on the top stack.
+            basis: Original protocol chain as base stacks.
+
+        """
+        from pcapkit.protocols.protocol import \
+            ProtocolBase as Protocol  # pylint: disable=import-outside-toplevel
+        if isinstance(proto, Protocol):
+            if alias is None:
+                alias = proto.alias
+            proto = type(proto)
+
+        if alias is None:
+            alias = proto.__name__
+
+        temp_data = [(alias, proto)]
+        if basis is not None:
+            temp_data.extend(basis)
+        self.__data__ = tuple(temp_data)
+
+    def __repr__(self) -> 'str':
+        """Returns representation of protocol chain data.
+
+        Example:
+            >>> protochain
+            ProtoChain(Ethernet, IPv6, Raw)
+
+        """
+        return f"ProtoChain({', '.join(map(lambda p: p[1].__name__, self.__data__))})"
+
+    def __str__(self) -> 'str':
+        """Returns formatted hex representation of source data stream.
+
+        Example:
+            >>> protochain
+            ProtoChain(Ethernet, IPv6, Raw)
+            >>> print(protochain)
+            Ethernet:IPv6:Raw
+
+        """
+        return ':'.join(map(lambda p: p[0], self.__data__))
+
+    def __contains__(self, name: 'str | Protocol | Type[Protocol]') -> 'bool':  # type: ignore[override]
+        """Returns if ``name`` is in the chain.
+
+        Args:
+            name: Name to search.
+
+        Returns:
+            Whether ``name`` is in the chain.
+
+        """
+        from pcapkit.protocols.protocol import \
+            ProtocolBase as Protocol  # pylint: disable=import-outside-toplevel
+        comp = Protocol.expand_comp(name)
+
+        for alias, proto in self.__data__:
+            test_comp = (proto, alias.upper(), *(name.upper() for name in proto.id()))
+            for test in comp:
+                if test in test_comp:
+                    return True
+        return False
+
+    @overload
+    def __getitem__(self, index: 'int') -> 'str': ...
+    @overload
+    def __getitem__(self, index: 'slice') -> 'tuple[str, ...]': ...
+
+    def __getitem__(self, index: 'int | slice') -> 'str | tuple[str, ...]':
+        """Subscription (``getitem``) support.
+
+        Args:
+            index: Indexing key.
+
+        Returns:
+            Protocol alias at such index.
+
+        """
+        if isinstance(index, slice):
+            return tuple(data[0] for data in self.__data__[index])
+        return self.__data__[index][0]
+
+    def __iter__(self) -> 'Iterator[tuple[str, Type[Protocol]]]':
+        """Iterator support.
+
+        Returns:
+            Iterator of protocol alias and class.
+
+        """
+        return iter(self.__data__)
+
+    def __len__(self) -> 'int':
+        """Length support.
+
+        Returns:
+            Length of protocol chain.
+
+        """
+        return len(self.__data__)
+
+    def __add__(self, other: 'ProtoChain') -> 'ProtoChain':
+        """Merge protocol chain by appending protocols from ``other``.
+
+        Args:
+            other: Protocol chain to be merged.
+
+        Returns:
+            Merged protocol chain.
+
+        """
+        new = copy.copy(self)
+        new.__data__ += other.__data__
+        return new

pcapkit/corekit/version.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""Version Info
+==================
+
+.. module:: pcapkit.corekit.version
+
+:mod:`pcapkit.corekit.version` contains :obj:`tuple`
+like class :class:`~pcapkit.corekit.version.VersionInfo`,
+which is originally designed alike :class:`sys.version_info`.
+
+"""
+import collections
+
+__all__ = ['VersionInfo']
+
+
+class VersionInfo(collections.namedtuple('VersionInfo', ['major', 'minor'])):
+    """VersionInfo is alike :class:`sys.version_info`."""
+
+    __slots__ = ()
+
+    #: Major version.
+    major: int
+    #: Minor version.
+    minor: int
+
+    @property
+    def version(self) -> 'str':
+        """Return version string."""
+        return f'{self.major}.{self.minor}'
+
+    def __str__(self) -> 'str':
+        return f'{self.major}.{self.minor}'

pcapkit/dumpkit/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+"""Dump Utilities
+====================
+
+.. module:: pcapkit.dumpkit
+
+:mod:`pcapkit.dumpkit` is the collection of dumpers for
+:mod:`pcapkit` implementation, which is alike those described
+in :mod:`dictdumper`.
+
+"""
+from pcapkit.dumpkit.null import NotImplementedIO
+from pcapkit.dumpkit.pcap import PCAPIO
+
+__all__ = ['PCAPIO', 'NotImplementedIO']

pcapkit/dumpkit/common.py

@@ -0,0 +1,199 @@
+# -*- coding: utf-8 -*-
+"""Common Utilities
+======================
+
+.. module:: pcapkit.dumpkit.common
+
+:mod:`pcapkit.dumpkit.common` is the collection of common utility
+functions for :mod:`pcapkit.dumpkit` implementation, which is
+generally the customised hooks for :class:`dictdumper.Dumper`
+classes.
+
+"""
+import collections
+import datetime
+import decimal
+import enum
+import ipaddress
+import tempfile
+from typing import TYPE_CHECKING
+
+import aenum
+import dictdumper.dumper
+
+from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.multidict import MultiDict, OrderedMultiDict
+from pcapkit.protocols.schema.schema import Schema
+from pcapkit.utilities.logging import logger
+
+__all__ = ['make_dumper']
+
+if TYPE_CHECKING:
+    from typing import Any, DefaultDict, Optional, TextIO, Type
+
+    from dictdumper.dumper import Dumper as ABCDumper
+    from typing_extensions import Literal
+
+
+class DumperBase(dictdumper.dumper.Dumper):
+    """Base :class:`~dictdumper.dumper.Dumper` object.
+
+    Note:
+        This class is for internal use only. For customisation, please use
+        :class:`Dumper` instead.
+
+    """
+
+
+class Dumper(DumperBase):
+    """Base :class:`~dictdumper.dumper.Dumper` object.
+
+    This class is a customised :class:`~dictdumper.dumper.Dumper` for the
+    :mod:`pcapkit.dumpkit` implementation, which is generally customised
+    for automatic registration to the
+    :class:`~pcapkit.foundation.extraction.Extractor` and
+    :class:`~pcapkit.foundation.traceflow.traceflow.TraceFlow` output
+    dumper registries.
+
+    """
+
+    def __init_subclass__(cls, /, fmt: 'Optional[str]' = None,
+                          ext: 'Optional[str]' = None, *args: 'Any', **kwargs: 'Any') -> 'None':
+        """Initialise subclass.
+
+        This method is used to register the subclass to the
+        :class:`~pcapkit.foundation.extraction.Extraction` and
+        :class:`~pcapkit.foundation.traceflow.traceflow.TraceFlow`
+        output dumper registries.
+
+        Args:
+            fmt: Output format to register.
+            ext: Output file extension.
+            *args: Arbitrary positional arguments.
+            **kwargs: Arbitrary keyword arguments.
+
+        If the ``fmt`` is not provided, we will try to get it from the
+        :attr:`~dictdumper.dumper.Dumper.kind` property of the subclass.
+        And if the ``ext`` is not provided, we will infer it from the
+        ``fmt``.
+
+        See Also:
+            - :func:`pcapkit.foundation.registry.foundation.register_dumper`
+            - :func:`pcapkit.foundation.registry.foundation.register_extractor_dumper`
+            - :func:`pcapkit.foundation.registry.foundation.register_traceflow_dumper`
+            - :meth:`pcapkit.foundation.extraction.Extractor.register_dumper`
+            - :meth:`pcapkit.foundation.traceflow.traceflow.TraceFlow.register_dumper`
+
+        """
+        if fmt is None:
+            with tempfile.NamedTemporaryFile() as temp:
+                fmt = cls(temp.name).kind
+        fmt = fmt.lower()
+
+        if ext is None:
+            ext = f'.{fmt}'
+
+        from pcapkit.foundation.extraction import Extractor
+        Extractor.register_dumper(fmt, cls, ext)
+
+        from pcapkit.foundation.traceflow.traceflow import TraceFlow
+        TraceFlow.register_dumper(fmt, cls, ext)
+
+        return super().__init_subclass__()
+
+
+def make_dumper(output: 'Type[ABCDumper]') -> 'Type[ABCDumper]':
+    """Create a customised :class:`~dictdumper.dumper.Dumper` object.
+
+    Args:
+        output: Output class to customise.
+
+    Returns:
+        Customised :class:`~dictdumper.dumper.Dumper` object.
+
+    """
+    class DictDumper(output):
+        """Customised :class:`~dictdumper.dumper.Dumper` object."""
+
+        def object_hook(self, o: 'Any') -> 'Any':
+            """Convert content for function call.
+
+            Args:
+                self: Dumper instance.
+                o: object to convert
+
+            Returns:
+                Converted object.
+
+            """
+            if isinstance(o, decimal.Decimal):
+                return str(o)
+            if isinstance(o, datetime.timedelta):
+                return o.total_seconds()
+            if isinstance(o, (Info, Schema)):
+                return o.to_dict()
+            if isinstance(o, (ipaddress.IPv4Address, ipaddress.IPv6Address)):
+                return str(o)
+            if isinstance(o, (MultiDict, OrderedMultiDict)):
+                temp = collections.defaultdict(list)  # type: DefaultDict[str, list[Any]]
+                for key, val in o.items(multi=True):
+                    if isinstance(key, (enum.Enum, aenum.Enum)):
+                        key = f'{type(key).__name__}::{key.name} [{key.value}]'
+                    temp[key].append(val)
+                return temp
+            if isinstance(o, (enum.Enum, aenum.Enum)):
+                addon = {key: val for key, val in o.__dict__.items() if not key.startswith('_')}
+                if addon:
+                    return {
+                        'enum': f'{type(o).__name__}::{o.name} [{o.value}]',
+                        **addon,
+                    }
+                return f'{type(o).__name__}::{o.name} [{o.value}]'
+            return super(type(self), self).object_hook(o)  # type: ignore[unreachable]
+
+        def default(self, o: 'Any') -> 'Literal["fallback"]':  # pylint: disable=unused-argument
+            """Check content type for function call.
+
+            Args:
+                self: Dumper instance.
+                o: Object to check.
+
+            Returns:
+                Fallback string.
+
+            Notes:
+                This function is a fallback for :meth:`dictdumper.dumper.Dumper.default`.
+                It will be called when :meth:`dictdumper.dumper.Dumper.default` fails
+                to find a suitable function for dumping and it should pair with
+                :func:`pcapkit.dumpkit.common._append_fallback` for use.
+
+            """
+            return 'fallback'
+
+        def _append_fallback(self, value: 'Any', file: 'TextIO') -> 'None':
+            """Fallback function for dumping.
+
+            Args:
+                self: Dumper instance.
+                value: Value to dump.
+                file: File object to write.
+
+            Notes:
+                This function is a fallback for :meth:`dictdumper.dumper.Dumper.default`.
+                It will be called when :meth:`dictdumper.dumper.Dumper.default` fails
+                to find a suitable function for dumping and it should pair with
+                :func:`pcapkit.dumpkit.common.default` for use.
+
+            """
+            if hasattr(value, '__slots__'):
+                new_value = {key: getattr(value, key) for key in value.__slots__}
+            elif hasattr(value, '__dict__'):
+                new_value = vars(value)
+            else:
+                logger.warning('unsupported object type: %s', type(value))
+                new_value = str(value)  # type: ignore[assignment]
+
+            func = self._encode_func(new_value)
+            func(new_value, file)
+
+    return DictDumper

pcapkit/dumpkit/null.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""Null Dumper
+=================
+
+.. module:: pcapkit.dumper.null
+
+:mod:`pcapkit.dumpkit.null` is the dumper for :mod:`pcapkit` implementation,
+specifically for **NotImplemented** format, which is alike those described in
+:mod:`dictdumper`.
+
+Notes:
+   This dumper is used when the given format is not supported, as a fallback.
+   It shall not produce any output.
+
+"""
+from typing import TYPE_CHECKING
+
+from pcapkit.dumpkit.common import DumperBase as Dumper
+
+if TYPE_CHECKING:
+    from typing import IO, Any, Optional
+
+    from typing_extensions import Literal
+
+__all__ = ['NotImplementedIO']
+
+
+class NotImplementedIO(Dumper):
+    """Unspecified output format."""
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    @property
+    def kind(self) -> 'Literal["null"]':
+        """File format of current dumper."""
+        return 'null'
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __call__(self, value: 'dict[str, Any]', name: 'Optional[str]' = None) -> 'NotImplementedIO':  # pylint: disable=unused-argument
+        """Dump a new frame.
+
+        Args:
+            value: content to be dumped
+            name: name of current content block
+
+        Returns:
+            The dumper class itself (to support chain calling).
+
+        """
+        return self
+
+    ##########################################################################
+    # Utilities.
+    ##########################################################################
+
+    def _dump_header(self, **kwargs: 'Any') -> 'None':  # pylint: disable=unused-argument
+        """Initially dump file heads and tails.
+
+        Args:
+            **kwargs: arbitrary keyword arguments
+
+        """
+
+    def _append_value(self, value: 'dict[str, Any]', file: 'IO[bytes]', name: 'str') -> 'None':  # pylint: disable=unused-argument
+        """Call this function to write contents.
+
+        Args:
+            value: content to be dumped
+            file: output file
+            name: name of current content block
+
+        """