pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/utilities/compat.py

@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Any, Callable, Iterator, Optional, Type, Union
+
+__all__ = [
+    # functions
+    'final', 'localcontext', 'show_flag_values',
+
+    # exceptions
+    'ModuleNotFoundError',
+
+    # classes
+    'Collection', 'cached_property',
+    'StrEnum',
+
+    # modules
+    'pathlib',
+
+    # typing
+    'Mapping', 'Tuple', 'List', 'Dict', 'TypeAlias',
+]
+
+if sys.version_info < (3, 6):
+    class ModuleNotFoundError(ImportError):  # pylint: disable=redefined-builtin
+        """Module not found."""
+else:
+    from builtins import ModuleNotFoundError
+
+if sys.version_info <= (3, 5):
+    from collections.abc import Container, Iterable, Sized  # pylint: disable=unused-import
+
+    def _check_methods(C: 'Type[Any]', *methods: 'str') -> 'bool | Any':
+        mro = C.__mro__
+        for method in methods:
+            for B in mro:
+                if method in B.__dict__:
+                    if B.__dict__[method] is None:
+                        return NotImplemented
+                    break
+            else:
+                return NotImplemented
+        return True
+
+    class Collection(Sized, Iterable, Container):  # pylint: disable=abstract-method
+
+        __slots__ = ()
+
+        @classmethod
+        def __subclasshook__(cls, C: 'Type[Any]') -> 'bool | Any':
+            if cls is Collection:
+                return _check_methods(C, "__len__", "__iter__", "__contains__")
+            return NotImplemented
+else:
+    from collections.abc import Collection
+
+if sys.version_info <= (3, 4):
+    import pathlib2 as pathlib  # pylint: disable=import-error
+else:
+    import pathlib
+
+# functools.cached_property added in 3.8
+if sys.version_info < (3, 8):
+    from threading import RLock
+    from typing import Generic, TypeVar  # isort: split
+
+    _T = TypeVar("_T")
+    _S = TypeVar("_S")
+
+    _NOT_FOUND = object()
+
+    class cached_property(Generic[_T]):
+        def __init__(self, func: 'Callable[[Any], _T]') -> 'None':
+            self.func = func  # type: Callable[[Any], _T]
+            self.attrname = None  # type: Optional[str]
+            self.__doc__ = func.__doc__
+            self.lock = RLock()
+
+        def __set_name__(self, owner: 'Type[Any]', name: 'str') -> 'None':
+            if self.attrname is None:
+                self.attrname = name
+            elif name != self.attrname:
+                raise TypeError(
+                    "Cannot assign the same cached_property to two different names "
+                    f"({self.attrname!r} and {name!r})."
+                )
+
+        def __get__(self, instance: 'Optional[_S]',
+                    owner: 'Optional[Type[Any]]' = None) -> 'Union[cached_property[_T], _T]':
+            if instance is None:
+                return self
+            if self.attrname is None:
+                raise TypeError(
+                    "Cannot use cached_property instance without calling __set_name__ on it.")
+            try:
+                cache = instance.__dict__
+            except AttributeError:  # not all objects have __dict__ (e.g. class defines slots)
+                msg = (
+                    f"No '__dict__' attribute on {type(instance).__name__!r} "
+                    f"instance to cache {self.attrname!r} property."
+                )
+                raise TypeError(msg) from None
+            val = cache.get(self.attrname, _NOT_FOUND)
+            if val is _NOT_FOUND:
+                with self.lock:
+                    # check if another thread filled cache while we awaited lock
+                    val = cache.get(self.attrname, _NOT_FOUND)
+                    if val is _NOT_FOUND:
+                        val = self.func(instance)
+                        try:
+                            cache[self.attrname] = val
+                        except TypeError:
+                            msg = (
+                                f"The '__dict__' attribute on {type(instance).__name__!r} instance "
+                                f"does not support item assignment for caching {self.attrname!r} property."
+                            )
+                            raise TypeError(msg) from None
+            return val
+else:
+    from functools import cached_property
+
+if sys.version_info < (3, 9):
+    from typing import Dict, List, Mapping, Tuple
+else:
+    from collections.abc import Mapping
+
+    Tuple: 'TypeAlias' = tuple
+    List: 'TypeAlias' = list
+    Dict: 'TypeAlias' = dict
+
+if sys.version_info < (3, 11):
+    from aenum import StrEnum
+else:
+    from enum import StrEnum
+
+if sys.version_info < (3, 8):
+    from typing_extensions import final
+else:
+    from typing import final
+
+if sys.version_info < (3, 11):
+    from contextlib import contextmanager
+    from decimal import localcontext as _localcontext
+
+    if TYPE_CHECKING:
+        from decimal import Context
+        from types import TracebackType
+
+        class _ContextManager:
+            def __init__(self, new_context: Context) -> None: ...
+            def __enter__(self) -> Context: ...
+            def __exit__(self, t: type[BaseException] | None, v: BaseException | None, tb: TracebackType | None) -> None: ...
+
+    @contextmanager
+    def localcontext(ctx: 'Optional[Context]' = None, **kwargs: 'Any') -> '_ContextManager':
+        """Return a context manager that will set the default context to a copy
+        of ctx on entry to the with-statement and restore the previous default
+        context when exiting the with-statement. If no context is specified, a
+        copy of the current default context is used."""
+        with _localcontext(ctx) as lc:
+            for attr, value in kwargs.items():
+                setattr(lc, attr, value)
+            yield lc
+else:
+    from decimal import localcontext
+
+if sys.version_info < (3, 11):
+    from enum import Enum
+
+    if TYPE_CHECKING:
+        from enum import IntFlag
+
+    def _iter_bits_lsb(num: 'int') -> 'Iterator[int]':
+        # num must be a positive integer
+        original = num
+        if isinstance(num, Enum):
+            num = num.value
+        if num < 0:
+            raise ValueError('%r is not a positive integer' % original)
+        while num:
+            b = num & (~num + 1)
+            yield b
+            num ^= b
+
+    def show_flag_values(value: 'IntFlag') -> 'list[int]':
+        return list(_iter_bits_lsb(value))
+else:
+    from enum import show_flag_values  # type: ignore[attr-defined]
+
+if sys.version_info < (3, 10):
+    from typing_extensions import TypeAlias
+else:
+    from typing import TypeAlias

pcapkit/utilities/decorators.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Decorator Functions
+=========================
+
+.. module:: pcapkit.utilities.decorators
+
+:mod:`pcapkit.utilities.decorators` contains several useful
+decorators, including :func:`~pcapkit.utilities.decorators.seekset`,
+:func:`~pcapkit.utilities.decorators.beholder` and
+:func:`~pcapkit.utilities.decorators.prepare`.
+
+"""
+import functools
+import io
+import os
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.utilities.exceptions import StructError, stacklevel
+from pcapkit.utilities.logging import DEVMODE, VERBOSE, logger
+
+if TYPE_CHECKING:
+    from typing import IO, Any, Callable, Optional, Type, TypeVar
+
+    from typing_extensions import Concatenate, ParamSpec
+
+    from pcapkit.protocols.protocol import ProtocolBase as Protocol
+    from pcapkit.protocols.schema.schema import Schema
+
+    P = ParamSpec('P')
+    R_seekset = TypeVar('R_seekset')
+    R_beholder = TypeVar('R_beholder', bound=Protocol)
+    R_prepare = TypeVar('R_prepare', bound=Schema)
+
+__all__ = ['seekset', 'beholder', 'prepare']
+
+
+def seekset(func: 'Callable[Concatenate[Protocol, P], R_seekset]') -> 'Callable[P, R_seekset]':
+    """Read file from start then set back to original.
+
+    Important:
+        This decorator function is designed for decorating *class methods*.
+
+    The decorator will keep the current offset of :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>`,
+    then call the decorated function. Afterwards, it will rewind the  offset of
+    :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>` to the original and returns the return value from
+    the decorated function.
+
+    Note:
+        The decorated function should have following signature::
+
+            func(self: 'pcapkit.protocols.protocol.ProtocolBase',
+                 *args: 'typing.Any', **kwargs: 'typing.Any') -> 'typing.Any'
+
+    See Also:
+        :meth:`pcapkit.protocols.protocol.Protocol._read_packet`
+
+    :param func: decorated function
+    :meta decorator:
+    """
+    @functools.wraps(func)
+    def seekcur(*args: 'P.args', **kw: 'P.kwargs') -> 'R_seekset':
+        # extract self object
+        self = cast('Protocol', args[0])
+
+        # move file pointer
+        seek_cur = self._file.tell()
+        self._file.seek(self._seekset, os.SEEK_SET)
+
+        # call method
+        return_ = func(*args, **kw)
+
+        # reset file pointer
+        self._file.seek(seek_cur, os.SEEK_SET)
+        return return_
+    return seekcur
+
+
+def beholder(func: 'Callable[Concatenate[Protocol, int, Optional[int], P], R_beholder]') -> 'Callable[P, R_beholder]':
+    """Behold extraction procedure.
+
+    Important:
+        This decorator function is designed for decorating *class methods*.
+
+    This decorator first keep the current offset of
+    :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>`, then
+    try to call the decorated function. Should any exception raised, it will
+    re-parse the :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>`
+    as :class:`~pcapkit.protocols.misc.raw.Raw` protocol.
+
+    Note:
+        The decorated function should have following signature::
+
+            func(self: 'pcapkit.protocols.protocol.ProtocolBase',
+                 proto: 'int', length: 'typing.Optional[int]',
+                 *args: 'typing.Any', **kwargs: 'typing.Any') -> 'pcapkit.protocols.protocol.ProtocolBase'
+
+    See Also:
+        :meth:`pcapkit.protocols.protocol.Protocol._decode_next_layer`
+
+    :param func: decorated function
+    :meta decorator:
+    """
+    @functools.wraps(func)
+    def behold(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_beholder':
+        # extract self object & args
+        self = cast('R_beholder', args[0])
+        try:
+            length = cast('int', args[2])
+        except IndexError:
+            length = None
+
+        # record file pointer
+        try:
+            # call method
+            return func(*args, **kwargs)
+        except Exception as exc:
+            if isinstance(exc, StructError) and exc.eof:  # pylint: disable=no-member
+                from pcapkit.protocols.misc.null import NoPayload as protocol  # isort: skip # pylint: disable=import-outside-toplevel
+            else:
+                from pcapkit.protocols.misc.raw import Raw as protocol  # type: ignore[assignment] # isort: skip # pylint: disable=import-outside-toplevel
+            # error = traceback.format_exc(limit=1).strip().rsplit(os.linesep, maxsplit=1)[-1]
+
+            # log error
+            logger.warning(str(exc), exc_info=exc if VERBOSE else None, stack_info=DEVMODE, stacklevel=stacklevel())
+
+            file_ = self.__header__.get_payload()
+            next_ = protocol(file_, length, error=str(exc))
+            return cast('R_beholder', next_)
+    return behold
+
+
+def prepare(func: 'Callable[Concatenate[Type[R_prepare], bytes | IO[bytes], Optional[int], Optional[dict[str, Any]], P], R_prepare]') -> 'Callable[P, R_prepare]':
+    """Prepare schema packet data before unpacking.
+
+    Important:
+        This decorate function is designed for decorating the
+        :meth:`Schema.unpack <pcapkit.protocols.schema.schema.Schema.unpack>`
+        *class method*.
+
+    This decorator will revise the parameter list provided to the original
+    :meth:`Schema.unpack <pcapkit.protocols.schema.schema.Schema.unpack>` method
+    and extract necessary information based on the given parameters, then provide
+    the revised version of parameter list to the original method.
+
+    Note:
+        The decorated function should have following signature::
+
+            func(cls: 'typing.Type[pcapkit.protocols.schema.schema.Schema]',
+                 data: 'bytes | typing.IO[bytes]',
+                 length: 'Optional[int],
+                 packet: 'Optional[dict[str, Any]',
+                 *args: 'typing.Any', **kwargs: 'Any') -> 'pcapkit.protocols.schema.schema.Schema'
+
+    See Also:
+        :meth:`pcapkit.protocols.schema.schema.Schema.unpack`
+
+    :param func: decorated function
+    :meta decorator:
+    """
+    @functools.wraps(func)
+    def unpack(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_prepare':
+        cls = cast('Type[R_prepare]', args[0])
+        data = cast('bytes | IO[bytes]', args[1])
+        length = cast('Optional[int]', args[2])
+        packet = cast('Optional[dict[str, Any]]', args[3])
+
+        if isinstance(data, bytes):
+            length = len(data) if length is None else length
+            data = io.BytesIO(data)
+        else:
+            if length is None:
+                current = data.tell()
+                length = data.seek(0, io.SEEK_END) - current
+                data.seek(current)
+
+        if length == 0:
+            raise EOFError
+
+        if packet is None:
+            packet = {}
+        packet['__length__'] = length
+
+        # call the user customised preparation method
+        # then proceed with the unpacking process
+        # and eventually revise the schema data
+        cls.pre_unpack(packet)
+        schema = func(cls, data, length, packet)
+        ret = schema.post_process(packet)
+
+        return cast('R_prepare', ret)
+    return unpack