pypcapkit 1.0.3__cp310-none-any.whl → 1.1.0__cp310-none-any.whl

pcapkit/corekit/fields/collections.py

@@ -3,7 +3,7 @@
 
 import copy
 import io
-from typing import TYPE_CHECKING, TypeVar, cast
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
 
 from pcapkit.corekit.fields.field import _Field
 from pcapkit.corekit.multidict import OrderedMultiDict
@@ -25,9 +25,10 @@ if TYPE_CHECKING:
     from pcapkit.protocols.schema.schema import Schema
 
 _TL = TypeVar('_TL', 'Schema', '_Field', 'bytes')
+_TS = TypeVar('_TS', bound='Schema')
 
 
-class ListField(_Field[List[_TL]]):
+class ListField(_Field[List[_TL]], Generic[_TL]):
     """Field list for protocol fields.
 
     Args:
@@ -55,7 +56,7 @@ class ListField(_Field[List[_TL]]):
     def __init__(self, length: 'int | Callable[[dict[str, Any]], int]' = lambda _: -1,
                  item_type: 'Optional[_Field]' = None,
                  callback: 'Callable[[Self, dict[str, Any]], None]' = lambda *_: None) -> 'None':
-        self._name = '<list>'
+        #self._name = '<list>'
         self._callback = callback
         self._item_type = item_type
 
@@ -74,9 +75,8 @@ class ListField(_Field[List[_TL]]):
         Returns:
             Updated field instance.
 
-        Notes:
-            This method will return a new instance of :class:`ListField`
-            instead of updating the current instance.
+        This method will return a new instance of :class:`ListField`
+        instead of updating the current instance.
 
         """
         new_self = copy.copy(self)
@@ -160,7 +160,7 @@ class ListField(_Field[List[_TL]]):
         return temp
 
 
-class OptionField(ListField):
+class OptionField(ListField, Generic[_TS]):
     """Field list for protocol options.
 
     Args:
@@ -181,7 +181,7 @@ class OptionField(ListField):
     """
 
     @property
-    def base_schema(self) -> 'Type[Schema]':
+    def base_schema(self) -> 'Type[_TS]':
         """Base schema."""
         return self._base_schema
 
@@ -191,7 +191,7 @@ class OptionField(ListField):
         return self._type_name
 
     @property
-    def registry(self) -> 'defaultdict[int | StdlibEnum | AenumEnum, Type[Schema]]':
+    def registry(self) -> 'defaultdict[int | StdlibEnum | AenumEnum, Type[_TS]]':
         """Option registry."""
         return self._registry
 
@@ -206,13 +206,13 @@ class OptionField(ListField):
         return self._option_padding
 
     def __init__(self, length: 'int | Callable[[dict[str, Any]], int]' = lambda _: -1,
-                 base_schema: 'Optional[Type[Schema]]' = None,
+                 base_schema: 'Optional[Type[_TS]]' = None,
                  type_name: 'str' = 'type',
-                 registry: 'Optional[defaultdict[int | StdlibEnum | AenumEnum, Type[Schema]]]' = None,
+                 registry: 'Optional[defaultdict[int | StdlibEnum | AenumEnum, Type[_TS]]]' = None,
                  eool: 'Optional[int | StdlibEnum | AenumEnum]' = None,
                  callback: 'Callable[[Self, dict[str, Any]], None]' = lambda *_: None) -> 'None':
         super().__init__(length, None, callback)
-        self._name = '<option>'
+        #self._name = '<option>'
         self._eool = eool
         self._option_padding = 0
 
@@ -228,7 +228,7 @@ class OptionField(ListField):
             raise FieldValueError('Field <option> has no registry.')
         self._registry = registry
 
-    def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list[Schema]':
+    def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list[_TS]':
         """Unpack field value from :obj:`bytes`.
 
         Args:
@@ -256,7 +256,7 @@ class OptionField(ListField):
         new_packet = packet.copy()
         new_packet[self.name] = OrderedMultiDict()
 
-        temp = []  # type: list[Schema]
+        temp = []  # type: list[_TS]
         while length > 0:
             # unpack option type using base schema
             meta = self._base_schema.unpack(file, length, packet)  # type: ignore[call-arg,misc,var-annotated]

pcapkit/corekit/fields/field.py

@@ -16,6 +16,8 @@ if TYPE_CHECKING:
 
     from typing_extensions import Literal, Self
 
+    from pcapkit.protocols.schema.schema import Schema
+
 _T = TypeVar('_T')
 
 
@@ -41,6 +43,10 @@ class _Field(Generic[_T], metaclass=abc.ABCMeta):
         :meth:`~_Field.pack` should be considerate of the template format
         and the actual value provided for packing.
 
+    Args:
+        *args: Arbitrary positional arguments.
+        **kwargs: Arbitrary keyword arguments.
+
     """
 
     if TYPE_CHECKING:
@@ -98,9 +104,8 @@ class _Field(Generic[_T], metaclass=abc.ABCMeta):
         Returns:
             Updated field instance.
 
-        Notes:
-            This method will return a new instance of :class:`_Field` instead of
-            updating the current instance.
+        This method will return a new instance of :class:`_Field` instead of
+        updating the current instance.
 
         """
         new_self = copy.copy(self)
@@ -109,7 +114,9 @@ class _Field(Generic[_T], metaclass=abc.ABCMeta):
 
     # NOTE: This method is created as a placeholder for the necessary attributes.
     def __init__(self, *args: 'Any', **kwargs: 'Any') -> 'None':
-        self._name = f'<{type(self).__name__[:-5].lower()}>'
+        if not hasattr(self, '_name'):
+            self._name = f'<{type(self).__name__[:-5].lower()}>'
+
         self._default = NoValue
         self._template = '0s'
         self._callback = lambda *_: None
@@ -119,6 +126,22 @@ class _Field(Generic[_T], metaclass=abc.ABCMeta):
             return f'<{self.__class__.__name__}>'
         return f'<{self.__class__.__name__} {self.name}>'
 
+    def __set_name__(self, owner: 'Schema', name: 'str') -> 'None':
+        """Set field name and update field list (if applicable).
+
+        This method is to be called by the metaclass during class creation.
+        It is used to set the field name and update the field list, i.e.,
+        :attr:`Schema.__fields__ <pcapkit.protocols.schema.schema.Schema.__fields__>`
+        mapping dictionary.
+
+        """
+        # Update field list (if applicable)
+        if hasattr(owner, '__fields__'):
+            owner.__fields__[name] = self
+
+        # Set field name
+        self.name = name
+
     def pre_process(self, value: '_T', packet: 'dict[str, Any]') -> 'Any':  # pylint: disable=unused-argument
         """Process field value before construction (packing).
 
@@ -204,7 +227,10 @@ class Field(_Field[_T], Generic[_T]):
     def __init__(self, length: 'int | Callable[[dict[str, Any]], int]',
                  default: '_T | NoValueType' = NoValue,
                  callback: 'Callable[[Self, dict[str, Any]], None]' = lambda *_: None) -> 'None':
-        self._name = '<unknown>'
+        #self._name = '<unknown>'
+        if not hasattr(self, '_name'):
+            self._name = f'<{type(self).__name__[:-5].lower()}>'
+
         self._default = default
         self._callback = callback
 
@@ -222,9 +248,8 @@ class Field(_Field[_T], Generic[_T]):
         Returns:
             New instance of :class:`Field`.
 
-        Notes:
-            This method will return a new instance of :class:`Field` instead of
-            updating the current instance.
+        This method will return a new instance of :class:`Field` instead of
+        updating the current instance.
 
         """
         new_self = copy.copy(self)

pcapkit/corekit/fields/ipaddress.py

@@ -3,7 +3,6 @@
 
 import abc
 import ipaddress
-from sys import prefix
 from typing import TYPE_CHECKING, Generic, TypeVar, cast
 
 from pcapkit.corekit.fields.field import _T, Field, NoValue

pcapkit/corekit/fields/misc.py

@@ -141,9 +141,8 @@ class ConditionalField(_Field[_TC]):
         Returns:
             Updated field instance.
 
-        Notes:
-            This method will return a new instance of :class:`ConditionalField`
-            instead of updating the current instance.
+        This method will return a new instance of :class:`ConditionalField`
+        instead of updating the current instance.
 
         """
         new_self = copy.copy(self)
@@ -273,7 +272,7 @@ class PayloadField(_Field[_TP]):
                  default: '_TP | NoValueType | bytes' = NoValue,
                  protocol: 'Optional[Type[_TP]]' = None,
                  callback: 'Callable[[Self, dict[str, Any]], None]' = lambda *_: None) -> 'None':
-        self._name = '<payload>'
+        #self._name = '<payload>'
         self._default = default  # type: ignore[assignment]
         self._protocol = protocol  # type: ignore[assignment]
         self._callback = callback
@@ -293,9 +292,8 @@ class PayloadField(_Field[_TP]):
         Returns:
             Updated field instance.
 
-        Notes:
-            This method will return a new instance of :class:`PayloadField`
-            instead of updating the current instance.
+        This method will return a new instance of :class:`PayloadField`
+        instead of updating the current instance.
 
         """
         new_self = copy.copy(self)
@@ -409,7 +407,7 @@ class SwitchField(_Field[_TC]):
         return self._field
 
     def __init__(self, selector: 'Callable[[dict[str, Any]], _Field[_TC]]' = lambda _: NoValueField()) -> 'None':  # type: ignore[assignment,return-value]
-        self._name = '<switch>'
+        #self._name = '<switch>'
         self._field = cast('_Field[_TC]', NoValueField())
         self._selector = selector
 
@@ -422,9 +420,8 @@ class SwitchField(_Field[_TC]):
         Returns:
             New field instance.
 
-        Notes:
-            This method will return a new instance of :class:`SwitchField`
-            instead of updating the current instance.
+        This method will return a new instance of :class:`SwitchField`
+        instead of updating the current instance.
 
         """
         new_self = copy.copy(self)
@@ -527,7 +524,7 @@ class SchemaField(_Field[_TS]):
                  default: '_TS | NoValueType | bytes' = NoValue,
                  packet: 'Optional[dict[str, Any]]' = None,
                  callback: 'Callable[[Self, dict[str, Any]], None]' = lambda *_: None) -> 'None':
-        self._name = '<schema>'
+        #self._name = '<schema>'
         self._callback = callback
 
         if packet is None:
@@ -557,9 +554,8 @@ class SchemaField(_Field[_TS]):
         Returns:
             New field instance.
 
-        Notes:
-            This method will return a new instance of :class:`SchemaField`
-            instead of updating the current instance.
+        This method will return a new instance of :class:`SchemaField`
+        instead of updating the current instance.
 
         """
         new_self = copy.copy(self)
@@ -679,7 +675,7 @@ class ForwardMatchField(_Field[_TC]):
         return self._field
 
     def __init__(self, field: '_Field[_TC]') -> 'None':
-        self._name = '<forward_match>'
+        #self._name = '<forward_match>'
         self._field = field
 
     def __call__(self, packet: 'dict[str, Any]') -> 'Self':
@@ -691,9 +687,8 @@ class ForwardMatchField(_Field[_TC]):
         Returns:
             Updated field instance.
 
-        Notes:
-            This method will return a new instance of :class:`ConditionalField`
-            instead of updating the current instance.
+        This method will return a new instance of :class:`ConditionalField`
+        instead of updating the current instance.
 
         """
         new_self = copy.copy(self)

pcapkit/corekit/fields/numbers.py

@@ -92,9 +92,8 @@ class NumberField(Field[int], Generic[_T]):
         Returns:
             New instance of :class:`NumberField`.
 
-        Notes:
-            This method will return a new instance of :class:`NumberField` instead of
-            updating the current instance.
+        This method will return a new instance of :class:`NumberField` instead of
+        updating the current instance.
 
         """
         new_self = super().__call__(packet)

pcapkit/corekit/fields/strings.py

@@ -56,9 +56,8 @@ class _TextField(Field[_T], Generic[_T]):
         Returns:
             New instance of :class:`_TextField`.
 
-        Notes:
-            This method will return a new instance of :class:`_TextField` instead of
-            updating the current instance.
+        This method will return a new instance of :class:`_TextField` instead of
+        updating the current instance.
 
         """
         new_self = super().__call__(packet)

pcapkit/corekit/infoclass.py

@@ -10,6 +10,7 @@ designed to work alike :func:`dataclasses.dataclass` as introduced
 in :pep:`557`.
 
 """
+import abc
 import collections.abc
 import enum
 import itertools
@@ -49,6 +50,11 @@ def info_final(cls: 'ST', *, _finalised: 'bool' = True) -> 'ST':
     class. It can be useful to reduce runtime generation
     time as well as caching already generated attributes.
 
+    Notes:
+        The decorator should only be used on the *final*
+        class, otherwise, any subclasses derived from a
+        finalised info class will not be re-finalised.
+
     Args:
         cls: Info class.
         _finalised: Whether to make the info class as finalised.
@@ -56,11 +62,6 @@ def info_final(cls: 'ST', *, _finalised: 'bool' = True) -> 'ST':
     Returns:
         Finalised info class.
 
-    Notes:
-        The decorator should only be used on the *final*
-        class, otherwise, any subclasses derived from a
-        finalised info class will not be re-finalised.
-
     :meta decorator:
     """
     if cls.__finalised__ == FinalisedState.FINAL:
@@ -140,7 +141,59 @@ def info_final(cls: 'ST', *, _finalised: 'bool' = True) -> 'ST':
     return final(cls)
 
 
-class Info(Mapping[str, VT], Generic[VT]):
+class InfoMeta(abc.ABCMeta):
+    """Meta class to add dynamic support to :class:`Info`.
+
+    This meta class is used to generate necessary attributes for the
+    :class:`Info` class. It can be useful to reduce runtime generation
+    cost as well as caching already generated attributes.
+
+    * :attr:`Info.__additional__` and :attr:`Info.__excluded__` are
+      lists of additional and excluded field names, which are used to
+      determine certain names to be included or excluded from the field
+      dictionary. They will be automatically populated from the class
+      attributes of the :class:`Info` class and its base classes.
+
+      .. note::
+
+         This is implemented thru the :meth:`__new__` method, which will
+         inherit the additional and excluded field names from the base
+         classes, as well as populating the additional and excluded field
+         from the subclass attributes.
+
+         .. code-block:: python
+
+            class A(Info):
+                __additional__ = ['a', 'b']
+
+            class B(A):
+                __additional__ = ['c', 'd']
+
+            class C(B):
+                __additional__ = ['e', 'f']
+
+            print(A.__additional__)  # ['a', 'b']
+            print(B.__additional__)  # ['a', 'b', 'c', 'd']
+            print(C.__additional__)  # ['a', 'b', 'c', 'd', 'e', 'f']
+
+    """
+
+    def __new__(cls, name: 'str', bases: 'tuple[type, ...]', attrs: 'dict[str, Any]', **kwargs: 'Any') -> 'Type[Info]':
+        if '__additional__' not in attrs:
+            attrs['__additional__'] = []
+        if '__excluded__' not in attrs:
+            attrs['__excluded__'] = []
+
+        for base in bases:
+            if hasattr(base, '__additional__'):
+                attrs['__additional__'].extend(
+                    name for name in base.__additional__ if name not in attrs['__additional__'])
+            if hasattr(base, '__excluded__'):
+                attrs['__excluded__'].extend(name for name in base.__excluded__ if name not in attrs['__excluded__'])
+        return super().__new__(cls, name, bases, attrs, **kwargs)  # type: ignore[return-value]
+
+
+class Info(Mapping[str, VT], Generic[VT], metaclass=InfoMeta):
     """Turn dictionaries into :obj:`object` like instances.
 
     * :class:`Info` objects inherit from :obj:`dict` type

pcapkit/corekit/protochain.py

@@ -26,7 +26,14 @@ __all__ = ['ProtoChain']
 
 
 class ProtoChain(collections.abc.Sequence):
-    """Protocols chain."""
+    """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]], ...]'