pre-finalise infoclass to save runtime

Author: JarryShaw

docs/source/pcapkit/corekit/infoclass.rst

@@ -21,3 +21,5 @@ in :pep:`557`.
       :no-value:
    .. autoattribute:: __excluded__
       :no-value:
+
+.. autodecorator:: pcapkit.corekit.infoclass.info_final

pcapkit/corekit/__init__.py

@@ -16,13 +16,13 @@ class :class:`~pcapkit.corekit.infoclass.Info`,
 
 """
 from pcapkit.corekit.fields import *
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 from pcapkit.corekit.multidict import MultiDict, OrderedMultiDict
 from pcapkit.corekit.protochain import ProtoChain
 from pcapkit.corekit.version import VersionInfo
 
 __all__ = [
-    'Info',
+    'Info', 'info_final',
 
     'ProtoChain',
 

pcapkit/corekit/infoclass.py

@@ -12,21 +12,112 @@
 """
 import collections.abc
 import itertools
-from typing import TYPE_CHECKING, Generic, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeVar, cast, final
 
 from pcapkit.utilities.compat import Mapping
-from pcapkit.utilities.exceptions import UnsupportedCall
+from pcapkit.utilities.exceptions import UnsupportedCall, stacklevel
+from pcapkit.utilities.warnings import InfoWarning, warn
 
 if TYPE_CHECKING:
-    from typing import Any, Iterable, Iterator, NoReturn, Optional
+    from typing import Any, Iterable, Iterator, NoReturn, Optional, Type
 
     from typing_extensions import Self
 
-__all__ = ['Info']
+__all__ = ['Info', 'info_final']
 
 VT = TypeVar('VT')
 
 
+def info_final(cls: 'Type[Info[VT]]') -> 'Type[Info[VT]]':
+    """Finalise info class.
+
+    Args:
+        cls: Info class.
+
+    Returns:
+        Finalised info class.
+
+    Notes:
+        This decorator function is used to generate necessary
+        attributes and methods for the decorated :class:`Info`
+        class. It can be useful to reduce runtime generation
+        time as well as caching already generated attributes.
+
+    :meta decorator:
+    """
+    if cls.__finalised__:
+        warn(f'{cls.__name__}: info class has been finalised; now skipping',
+             InfoWarning, stacklevel=stacklevel())
+        return cls
+
+    temp = ['__map__', '__map_reverse__', '__builtin__', '__finalised__']
+    temp.extend(cls.__additional__)
+    for obj in cls.mro():
+        temp.extend(dir(obj))
+    cls.__builtin__ = set(temp)
+    cls.__excluded__.extend(cls.__builtin__)
+
+    # NOTE: We only generate ``__init__`` method for subclasses of the
+    # ``Info`` class, rather than itself, plus that such class does not
+    # override the ``__init__`` method of the meta class.
+    if '__init__' not in cls.__dict__ and cls is not Info:
+        args_ = []  # type: list[str]
+        dict_ = []  # type: list[str]
+
+        for cls_ in cls.mro():
+            # NOTE: We skip the ``Info`` class itself, to avoid superclass
+            # type annotations being considered.
+            if cls_ is Info:
+                break
+
+            # NOTE: We iterate in reversed order to ensure that the type
+            # annotations of the superclasses are considered first.
+            for key in reversed(cls_.__annotations__):
+                # NOTE: We skip duplicated annotations to avoid duplicate
+                # argument in function definition.
+                if key in args_:
+                    continue
+
+                args_.append(key)
+                dict_.append(f'{key}={key}')
+
+        # NOTE: We reverse the two lists such that the order of the
+        # arguments is the same as the order of the type annotations, i.e.,
+        # from the most base class to the most derived class.
+        args_.reverse()
+        dict_.reverse()
+
+        # NOTE: We only generate typed ``__init__`` method if only the class
+        # has type annotations from any of itself and its base classes.
+        if args_:
+            # NOTE: The following code is to make the ``__init__`` method work.
+            # It is inspired from the :func:`dataclasses._create_fn` function.
+            init_ = (
+                f'def __create_fn__():\n'
+                f'    def __init__(self, {", ".join(args_)}):\n'
+                f'        self.__update__({", ".join(dict_)})\n'
+                f'        self.__post_init__()\n'
+                f'    return __init__\n'
+            )
+        else:
+            init_ = (
+                'def __create_fn__():\n'
+                '    def __init__(self, dict_=None, **kwargs):\n'
+                '        self.__update__(dict_, **kwargs)\n'
+                '        self.__post_init__()\n'
+                '    return __init__\n'
+            )
+
+        ns = {}  # type: dict[str, Any]
+        exec(init_, None, ns)  # pylint: disable=exec-used # nosec
+
+        cls.__init__ = ns['__create_fn__']()
+        cls.__init__.__qualname__ = f'{cls.__name__}.__init__'
+
+    cls.__finalised__ = True
+    return final(cls)
+
+
 class Info(Mapping[str, VT], Generic[VT]):
     """Turn dictionaries into :obj:`object` like instances.
 
@@ -55,6 +146,9 @@ class Info(Mapping[str, VT], Generic[VT]):
         #: List of builtin methods.
         __builtin__: 'set[str]'
 
+    #: Flag for finalised class initialisation.
+    __finalised__ = False
+
     #: List of additional built-in names.
     __additional__: 'list[str]' = []
     #: List of names to be excluded from :obj:`dict` conversion.
@@ -72,69 +166,8 @@ def __new__(cls, *args: 'VT', **kwargs: 'VT') -> 'Self':  # pylint: disable=unus
             **kwargs: Arbitrary keyword arguments.
 
         """
-        temp = ['__map__', '__map_reverse__', '__builtin__']
-        temp.extend(cls.__additional__)
-        for obj in cls.mro():
-            temp.extend(dir(obj))
-        cls.__builtin__ = set(temp)
-        cls.__excluded__.extend(cls.__builtin__)
-
-        # NOTE: We only generate ``__init__`` method for subclasses of the
-        # ``Info`` class, rather than itself, plus that such class does not
-        # override the ``__init__`` method of the meta class.
-        if '__init__' not in cls.__dict__ and cls is not Info:
-            args_ = []  # type: list[str]
-            dict_ = []  # type: list[str]
-
-            for cls_ in cls.mro():
-                # NOTE: We skip the ``Info`` class itself, to avoid superclass
-                # type annotations being considered.
-                if cls_ is Info:
-                    break
-
-                # NOTE: We iterate in reversed order to ensure that the type
-                # annotations of the superclasses are considered first.
-                for key in reversed(cls_.__annotations__):
-                    # NOTE: We skip duplicated annotations to avoid duplicate
-                    # argument in function definition.
-                    if key in args_:
-                        continue
-
-                    args_.append(key)
-                    dict_.append(f'{key}={key}')
-
-            # NOTE: We reverse the two lists such that the order of the
-            # arguments is the same as the order of the type annotations, i.e.,
-            # from the most base class to the most derived class.
-            args_.reverse()
-            dict_.reverse()
-
-            # NOTE: We only generate typed ``__init__`` method if only the class
-            # has type annotations from any of itself and its base classes.
-            if args_:
-                # NOTE: The following code is to make the ``__init__`` method work.
-                # It is inspired from the :func:`dataclasses._create_fn` function.
-                init_ = (
-                    f'def __create_fn__():\n'
-                    f'    def __init__(self, {", ".join(args_)}):\n'
-                    f'        self.__update__({", ".join(dict_)})\n'
-                    f'        self.__post_init__()\n'
-                    f'    return __init__\n'
-                )
-            else:
-                init_ = (
-                    'def __create_fn__():\n'
-                    '    def __init__(self, dict_=None, **kwargs):\n'
-                    '        self.__update__(dict_, **kwargs)\n'
-                    '        self.__post_init__()\n'
-                    '    return __init__\n'
-                )
-
-            ns = {}  # type: dict[str, Any]
-            exec(init_, None, ns)  # pylint: disable=exec-used # nosec
-            cls.__init__ = ns['__create_fn__']()
-            cls.__init__.__qualname__ = f'{cls.__name__}.__init__'
-
+        if not cls.__finalised__:
+            cls = cast('Type[Self]', info_final(cls))
         self = super().__new__(cls)
 
         # NOTE: We define the ``__map__`` and ``__map_reverse__`` attributes

pcapkit/foundation/engines/pcapng.py

@@ -12,7 +12,7 @@
 from typing import TYPE_CHECKING, cast
 
 from pcapkit.const.pcapng.block_type import BlockType as Enum_BlockType
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 from pcapkit.foundation.engines.engine import Engine
 from pcapkit.protocols.misc.pcapng import PCAPNG as P_PCAPNG
 from pcapkit.utilities.exceptions import FormatError, stacklevel
@@ -39,6 +39,7 @@
     from pcapkit.protocols.data.misc.pcapng import UnknownBlock as Data_UnknownBlock
 
 
+@info_final
 class Context(Info):
     """Context manager for PCAP-NG file format."""
 

pcapkit/foundation/reassembly/__init__.py

@@ -28,12 +28,13 @@
 
 from typing import TYPE_CHECKING
 
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 
 if TYPE_CHECKING:
     from typing import Optional
 
 
+@info_final
 class ReassemblyManager(Info):
     """Reassembly Manager."""
 

pcapkit/foundation/reassembly/data/__init__.py

@@ -27,12 +27,13 @@
 
 from typing import TYPE_CHECKING
 
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 
 if TYPE_CHECKING:
     from typing import Optional
 
 
+@info_final
 class ReassemblyData(Info):
     """Data storage for reassembly."""
 

pcapkit/foundation/reassembly/data/ip.py

@@ -3,7 +3,7 @@
 
 from typing import TYPE_CHECKING, Generic, TypeVar
 
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 from pcapkit.utilities.compat import Tuple
 
 __all__ = [
@@ -25,6 +25,7 @@
 BufferID = Tuple[AT, AT, int, 'TransType']
 
 
+@info_final
 class Packet(Info, Generic[AT]):
     """Data model for :term:`reasm.ipv4.packet` / :term:`reasm.ipv6.packet`."""
 
@@ -49,6 +50,7 @@ class Packet(Info, Generic[AT]):
         def __init__(self, bufid: 'tuple[AT, AT, int, TransType]', num: 'int', fo: 'int', ihl: 'int', mf: 'bool', tl: 'int', header: 'bytes', payload: 'bytearray') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class DatagramID(Info, Generic[AT]):
     """Data model for :term:`reasm.ipv4.datagram` / :term:`reasm.ipv6.datagram` original packet identifier."""
 
@@ -65,6 +67,7 @@ class DatagramID(Info, Generic[AT]):
         def __init__(self, src: 'AT', dst: 'AT', id: 'int', proto: 'TransType') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class Datagram(Info, Generic[AT]):
     """Data model for :term:`reasm.ipv4.datagram` / :term:`reasm.ipv6.datagram`."""
 
@@ -91,6 +94,7 @@ def __init__(self, completed: 'Literal[False]', id: 'DatagramID[AT]', index: 'tu
         def __init__(self, completed: 'bool', id: 'DatagramID[AT]', index: 'tuple[int, ...]', header: 'bytes', payload: 'bytes | tuple[bytes, ...]', packet: 'Optional[Protocol]') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class Buffer(Info, Generic[AT]):
     """Data model for :term:`reasm.ipv4.buffer` / :term:`reasm.ipv6.buffer`."""
 

pcapkit/foundation/reassembly/data/tcp.py

@@ -3,7 +3,7 @@
 
 from typing import TYPE_CHECKING, Generic, TypeVar
 
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 from pcapkit.utilities.compat import Tuple
 
 __all__ = [
@@ -25,6 +25,7 @@
 BufferID = Tuple[IPAddress, int, IPAddress, int]
 
 
+@info_final
 class Packet(Info):
     """Data model for :term:`reasm.tcp.packet`."""
 
@@ -57,6 +58,7 @@ class Packet(Info):
         def __init__(self, bufid: 'BufferID', dsn: 'int', ack: 'int', num: 'int', syn: 'bool', fin: 'bool', rst: 'bool', len: 'int', first: 'int', last: 'int', header: 'bytes', payload: 'bytearray') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class DatagramID(Info, Generic[IPAddress]):
     """Data model for :term:`reasm.tcp.datagram` original packet identifier."""
 
@@ -71,6 +73,7 @@ class DatagramID(Info, Generic[IPAddress]):
         def __init__(self, src: 'tuple[IPAddress, int]', dst: 'tuple[IPAddress, int]', ack: 'int') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class Datagram(Info, Generic[IPAddress]):
     """Data model for :term:`reasm.tcp.datagram`."""
 
@@ -97,6 +100,7 @@ def __init__(self, completed: 'Literal[False]', id: 'DatagramID[IPAddress]', ind
         def __init__(self, completed: 'bool', id: 'DatagramID[IPAddress]', index: 'tuple[int, ...]', header: 'bytes', payload: 'bytes | tuple[bytes, ...]', packet: 'Optional[Protocol]') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class HoleDiscriptor(Info):
     """Data model for :term:`reasm.tcp.buffer` hole descriptor."""
 
@@ -109,6 +113,7 @@ class HoleDiscriptor(Info):
         def __init__(self, first: 'int', last: 'int') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class Fragment(Info):
     """Data model for :term:`reasm.tcp.buffer` ACK list fragment item."""
 
@@ -125,6 +130,7 @@ class Fragment(Info):
         def __init__(self, ind: 'list[int]', isn: 'int', len: 'int', raw: 'bytearray') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long,redefined-builtin
 
 
+@info_final
 class Buffer(Info):
     """Data model for :term:`reasm.tcp.buffer`."""
 

pcapkit/foundation/traceflow/__init__.py

@@ -27,12 +27,13 @@
 
 from typing import TYPE_CHECKING
 
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 
 if TYPE_CHECKING:
     from typing import Optional
 
 
+@info_final
 class TraceFlowManager(Info):
     """TraceFlow Manager."""
 

pcapkit/foundation/traceflow/data/__init__.py

@@ -13,12 +13,13 @@
 
 from typing import TYPE_CHECKING
 
-from pcapkit.corekit.infoclass import Info
+from pcapkit.corekit.infoclass import Info, info_final
 
 if TYPE_CHECKING:
     from typing import Optional
 
 
+@info_final
 class TraceFlowData(Info):
     """Data storage for flow tracing."""