pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/utilities/exceptions.py

@@ -0,0 +1,365 @@
+# -*- coding: utf-8 -*-
+"""User Defined Exceptions
+=============================
+
+.. module:: pcapkit.utilities.exceptions
+
+:mod:`pcapkit.exceptions` refined built-in exceptions.
+Make it possible to show only user error stack infomation [*]_,
+when exception raised on user's operation.
+
+.. [*] See |tbtrim|_ project for Pythonic implementation.
+
+.. |tbtrim| replace:: ``tbtrim``
+.. _tbtrim: https://github.com/gousaiyang/tbtrim
+
+"""
+import io
+import os
+import struct
+import sys
+import traceback
+from typing import TYPE_CHECKING
+
+from pcapkit.utilities.compat import ModuleNotFoundError  # pylint: disable=redefined-builtin
+from pcapkit.utilities.logging import DEVMODE, VERBOSE, logger
+
+if TYPE_CHECKING:
+    from typing import Any
+
+__all__ = [
+    'stacklevel',
+
+    'BaseError',                                                    # Exception
+    'DigitError', 'IntError', 'RealError', 'ComplexError',          # TypeError
+    'BoolError', 'BytesError', 'StringError', 'BytearrayError',     # TypeError
+    'DictError', 'ListError', 'TupleError', 'IterableError',        # TypeError
+    'IOObjError', 'ProtocolUnbound', 'CallableError',               # TypeError
+    'InfoError', 'IPError', 'EnumError', 'ComparisonError',         # TypeError
+    'RegistryError', 'FieldError',                                  # TypeError
+    'FormatError', 'UnsupportedCall',                               # AttributeError
+    'FileError', 'UnsupportedOperation',                            # IOError
+    'FileExists',                                                   # FileExistsError
+    'FileNotFound',                                                 # FileNotFoundError
+    'ProtocolNotFound',                                             # IndexError
+    'VersionError', 'IndexNotFound', 'ProtocolError',               # ValueError
+    'EndianError', 'KeyExists', 'NoDefaultValue',                   # ValueError
+    'FieldValueError', 'SchemaError', 'SeekError', 'TruncateError', # ValueError
+    'ProtocolNotImplemented', 'VendorNotImplemented',               # NotImplementedError
+    'StructError',                                                  # struct.error
+    'MissingKeyError', 'FragmentError', 'PacketError',              # KeyError
+    'ModuleNotFound',                                               # ModuleNotFoundError
+]
+
+
+def stacklevel() -> 'int':
+    """Fetch current stack level.
+
+    The function will walk through the straceback stack (:func:`traceback.extract_stack`),
+    and fetch the stack level where the path contains ``/pcapkit/``. So that it won't
+    display any disturbing internal traceback information when raising errors.
+
+    Returns:
+        Stack level until internal stacks, i.e. contains ``/pcapkit/``.
+
+    """
+    pcapkit = f'{os.path.sep}pcapkit{os.path.sep}'
+    tb = traceback.extract_stack()
+    for index, tbitem in enumerate(tb):
+        if pcapkit in tbitem[0]:
+            break
+    else:
+        index = len(tb)
+    return index-1
+
+
+##############################################################################
+# BaseError (abc of exceptions) session.
+##############################################################################
+
+
+class BaseError(Exception):
+    """Base error class of all kinds.
+
+    Important:
+
+        * Turn off system-default traceback function by set :data:`sys.tracebacklimit` to ``0``.
+        * But bugs appear in Python 3.6, so we have to set :data:`sys.tracebacklimit` to ``None``.
+
+          .. note::
+
+             This note is deprecated since Python fixed the problem above.
+
+        * In Python 2.7, :func:`trace.print_stack(limit)` dose not support negative limit.
+
+    See Also:
+        :func:`pcapkit.utilities.exceptions.stacklevel`
+
+    """
+
+    def __init__(self, *args: 'Any', quiet: 'bool' = False, **kwargs: 'Any') -> 'None':
+        # log error
+        if not quiet:
+            if DEVMODE:
+                logger.critical('%s: %s', type(self).__name__, str(self),
+                                exc_info=self if VERBOSE else False,
+                                stack_info=VERBOSE, stacklevel=-stacklevel())
+            else:
+                logger.critical("%s: %s", type(self).__name__, str(self))
+
+            # logger.error('%s: %s', type(self).__name__, str(self), exc_info=self,
+            #              stack_info=True, stacklevel=-stacklevel())
+        else:
+            logger.error('%s: %s', type(self).__name__, str(self))
+
+        if not DEVMODE:
+            sys.tracebacklimit = 0
+        super().__init__(*args, **kwargs)
+
+
+##############################################################################
+# TypeError session.
+##############################################################################
+
+
+class DigitError(BaseError, TypeError):
+    """The argument(s) must be (a) number(s)."""
+
+
+class IntError(BaseError, TypeError):
+    """The argument(s) must be integral."""
+
+
+class RealError(BaseError, TypeError):
+    """The function is not defined for real number."""
+
+
+class ComplexError(BaseError, TypeError):
+    """The function is not defined for complex instance."""
+
+
+class BytesError(BaseError, TypeError):
+    """The argument(s) must be :obj:`bytes` type."""
+
+
+class BytearrayError(BaseError, TypeError):
+    """The argument(s) must be :obj:`bytearray` type."""
+
+
+class BoolError(BaseError, TypeError):
+    """The argument(s) must be :obj:`bool` type."""
+
+
+class StringError(BaseError, TypeError):
+    """The argument(s) must be :obj:`str` type."""
+
+
+class DictError(BaseError, TypeError):
+    """The argument(s) must be :obj:`dict` type."""
+
+
+class ListError(BaseError, TypeError):
+    """The argument(s) must be :obj:`list` type."""
+
+
+class TupleError(BaseError, TypeError):
+    """The argument(s) must be :obj:`tuple` type."""
+
+
+class IterableError(BaseError, TypeError):
+    """The argument(s) must be *iterable*."""
+
+
+class CallableError(BaseError, TypeError):
+    """The argument(s) must be *callable*."""
+
+
+class ProtocolUnbound(BaseError, TypeError):
+    """Protocol slice unbound."""
+
+
+class IOObjError(BaseError, TypeError):
+    """The argument(s) must be *file-like object*."""
+
+
+class InfoError(BaseError, TypeError):
+    """The argument(s) must be :class:`~pcapkit.corekit.infoclass.Info` instance."""
+
+
+class IPError(BaseError, TypeError):
+    """The argument(s) must be *IP address*."""
+
+
+class EnumError(BaseError, TypeError):
+    """The argument(s) must be *enumeration protocol* type."""
+
+
+class ComparisonError(BaseError, TypeError):
+    """Rich comparison not supported between instances."""
+
+
+class RegistryError(BaseError, TypeError):
+    """The argument(s) must be *registry* type."""
+
+
+class FieldError(BaseError, TypeError):
+    """The argument(s) must be *field* type."""
+
+
+##############################################################################
+# AttributeError session.
+##############################################################################
+
+
+class FormatError(BaseError, AttributeError):
+    """Unknown format(s)."""
+
+
+class UnsupportedCall(BaseError, AttributeError):
+    """Unsupported function or property call."""
+
+
+##############################################################################
+# IOError session.
+##############################################################################
+
+
+class FileError(BaseError, IOError):
+    """[Errno 5] Wrong file format."""
+    # args: errno, strerror, filename, winerror, filename2
+
+
+##############################################################################
+# FileExistsError session.
+##############################################################################
+
+
+class FileExists(BaseError, FileExistsError):
+    """[Errno 17] File already exists."""
+    # args: errno, strerror, filename, winerror, filename2
+
+
+##############################################################################
+# FileNotFoundError session.
+##############################################################################
+
+
+class FileNotFound(BaseError, FileNotFoundError):
+    """[Errno 2] File not found."""
+    # args: errno, strerror, filename, winerror, filename2
+
+
+##############################################################################
+# IndexError session.
+##############################################################################
+
+
+class ProtocolNotFound(BaseError, IndexError):
+    """Protocol not found in ProtoChain."""
+
+
+##############################################################################
+# ValueError session.
+##############################################################################
+
+
+class VersionError(BaseError, ValueError):
+    """Unknown IP version."""
+
+
+class IndexNotFound(BaseError, ValueError):
+    """Protocol not in ProtoChain."""
+
+
+class ProtocolError(BaseError, ValueError):
+    """Invalid protocol format."""
+
+
+class EndianError(BaseError, ValueError):
+    """Invalid endian (byte order)."""
+
+
+class KeyExists(BaseError, ValueError):
+    """Key already exists."""
+
+
+class NoDefaultValue(BaseError, ValueError):
+    """No default value."""
+
+
+class FieldValueError(BaseError, ValueError):
+    """Invalid field value."""
+
+
+class SchemaError(BaseError, ValueError):
+    """Invalid schema."""
+
+
+class SeekError(BaseError, ValueError):
+    """Invalid seek position."""
+
+
+class TruncateError(BaseError, ValueError):
+    """Invalid truncate size."""
+
+
+##############################################################################
+# NotImplementedError session.
+##############################################################################
+
+
+class ProtocolNotImplemented(BaseError, NotImplementedError):
+    """Protocol not implemented."""
+
+
+class VendorNotImplemented(BaseError, NotImplementedError):
+    """Vendor not implemented."""
+
+
+##############################################################################
+# struct.error session.
+##############################################################################
+
+
+class StructError(BaseError, struct.error):
+    """Unpack failed."""
+
+    def __init__(self, *args: 'Any', eof: 'bool' = False, **kwargs: 'Any') -> 'None':
+        self.eof = eof
+        super().__init__(*args, **kwargs)
+
+
+##############################################################################
+# KeyError session.
+##############################################################################
+
+
+class MissingKeyError(BaseError, KeyError):
+    """Key not found."""
+
+
+class FragmentError(BaseError, KeyError):
+    """Invalid fragment dict."""
+
+
+class PacketError(BaseError, KeyError):
+    """Invalid packet dict."""
+
+
+##############################################################################
+# ModuleNotFoundError session.
+##############################################################################
+
+
+class ModuleNotFound(BaseError, ModuleNotFoundError):
+    """Module not found."""
+    # kwargs: name, path
+
+
+##############################################################################
+# io.UnsupportedOperation session.
+##############################################################################
+
+
+class UnsupportedOperation(BaseError, io.UnsupportedOperation):
+    """Unsupported operation."""

pcapkit/utilities/logging.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+"""Logging System
+====================
+
+.. module:: pcapkit.utilities.logging
+
+:mod:`pcapkit.utilities.logging` contains naïve integration
+of the Python logging system, i.e. a :class:`logging.Logger`
+instance as :data:`~pcapkit.utilities.logging.logger`.
+
+"""
+import logging
+import os
+import sys
+
+__all__ = ['logger']
+
+###############################################################################
+# Dev Mode
+###############################################################################
+
+# boolean mappings
+BOOLEAN_STATES = {'1': True, '0': False,
+                  'yes': True, 'no': False,
+                  'true': True, 'false': False,
+                  'on': True, 'off': False}
+
+#: bool: Development mode flag.
+DEVMODE = BOOLEAN_STATES.get(os.environ.get('PCAPKIT_DEVMODE', 'false').casefold(), False)
+#: bool: Verbose output flag.
+VERBOSE = BOOLEAN_STATES.get(os.environ.get('PCAPKIT_VERBOSE', 'false').casefold(), False)
+
+###############################################################################
+# Sphinx Mode
+###############################################################################
+
+#: bool: This is a workaround for :data:`typing.TYPE_CHECKING` in Sphinx.
+SPHINX_TYPE_CHECKING = BOOLEAN_STATES.get(os.environ.get('PCAPKIT_SPHINX', 'false').casefold(), False)
+
+###############################################################################
+# Logger Setup
+###############################################################################
+
+#: logging.Logger: :class:`~logging.Logger` instance named after ``pcapkit``.
+logger = logging.getLogger('pcapkit')
+
+formatter = logging.Formatter(fmt='[%(levelname)s] %(asctime)s - %(message)s',
+                              datefmt='%m/%d/%Y %I:%M:%S %p')
+handler = logging.StreamHandler(sys.stderr)
+if DEVMODE:
+    logger.setLevel(logging.DEBUG)
+else:
+    logger.setLevel(logging.INFO)
+handler.setFormatter(formatter)
+logger.addHandler(handler)

pcapkit/utilities/warnings.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+"""User Defined Warnings
+===========================
+
+.. module:: pcapkit.utilities.warnings
+
+:mod:`pcapkit.warnings` refined built-in warnings.
+
+"""
+import warnings
+from typing import TYPE_CHECKING
+
+from pcapkit.utilities.exceptions import stacklevel as stacklevel_calculator
+from pcapkit.utilities.logging import DEVMODE, VERBOSE, logger
+
+if TYPE_CHECKING:
+    from typing import Any, Optional, Type, Union
+
+__all__ = [
+    'warn',
+
+    # UserWarning
+    'BaseWarning',
+    # ImportWarning
+    'FormatWarning', 'EngineWarning', 'InvalidVendorWarning',
+    # RuntimeWarning
+    'FileWarning', 'LayerWarning', 'ProtocolWarning', 'AttributeWarning',
+    'DevModeWarning', 'VendorRequestWarning', 'VendorRuntimeWarning',
+    'UnknownFieldWarning', 'RegistryWarning', 'SchemaWarning', 'InfoWarning',
+    'SeekWarning', 'ExtractionWarning',
+    # ResourceWarning
+    'DPKTWarning', 'ScapyWarning', 'PySharkWarning', 'EmojiWarning',
+    'VendorWarning',
+    # DeprecationWarning
+    'DeprecatedFormatWarning',
+]
+
+
+def warn(message: 'Union[str, Warning]', category: 'Type[Warning]',
+         stacklevel: 'Optional[int]' = None) -> 'None':
+    """Wrapper function of :func:`warnings.warn`.
+
+    Args:
+        message: Warning message.
+        category: Warning category.
+        stacklevel: Warning stack level.
+
+    """
+    if stacklevel is None:
+        stacklevel = stacklevel_calculator()
+
+    logger.warning(message, exc_info=VERBOSE, stack_info=VERBOSE,
+                   stacklevel=stacklevel)
+    warnings.warn(message, category, stacklevel)
+
+
+##############################################################################
+# BaseWarning (abc of warnings) session.
+##############################################################################
+
+
+class BaseWarning(UserWarning):
+    """Base warning class of all kinds."""
+
+    def __init__(self, *args: 'Any', **kwargs: 'Any') -> 'None':  # pylint: disable=useless-super-delegation
+        # log warning
+        if DEVMODE:
+            if VERBOSE:
+                logger.warning(str(self), exc_info=self, stack_info=True,
+                            stacklevel=stacklevel_calculator())
+            else:
+                logger.warning(str(self))
+        else:
+            warnings.simplefilter('ignore', type(self))
+
+        # warnings.simplefilter('default')
+        super().__init__(*args, **kwargs)
+
+
+##############################################################################
+# ImportWarning session.
+##############################################################################
+
+
+class FormatWarning(BaseWarning, ImportWarning):
+    """Warning on unknown format(s)."""
+
+
+class EngineWarning(BaseWarning, ImportWarning):
+    """Unsupported extraction engine."""
+
+
+class InvalidVendorWarning(BaseWarning, ImportWarning):
+    """Vendor CLI invalid updater."""
+
+
+##############################################################################
+# RuntimeWarning session.
+##############################################################################
+
+
+class FileWarning(BaseWarning, RuntimeWarning):
+    """Warning on file(s)."""
+
+
+class LayerWarning(BaseWarning, RuntimeWarning):
+    """Unrecognised layer."""
+
+
+class ProtocolWarning(BaseWarning, RuntimeWarning):
+    """Unrecognised protocol."""
+
+
+class AttributeWarning(BaseWarning, RuntimeWarning):
+    """Unsupported attribute."""
+
+
+class DevModeWarning(BaseWarning, RuntimeWarning):
+    """Run in development mode."""
+
+
+class VendorRequestWarning(BaseWarning, RuntimeWarning):
+    """Vendor request connection failed."""
+
+
+class VendorRuntimeWarning(BaseWarning, RuntimeWarning):
+    """Vendor failed during runtime."""
+
+
+class UnknownFieldWarning(BaseWarning, RuntimeWarning):
+    """Unknown field."""
+
+
+class RegistryWarning(BaseWarning, RuntimeWarning):
+    """Registry warning."""
+
+
+class SchemaWarning(BaseWarning, RuntimeWarning):
+    """Schema warning."""
+
+
+class InfoWarning(BaseWarning, RuntimeWarning):
+    """Info class warning."""
+
+
+class SeekWarning(BaseWarning, RuntimeWarning):
+    """Seek operation warning."""
+
+
+class ExtractionWarning(BaseWarning, RuntimeWarning):
+    """Extraction warning."""
+
+
+##############################################################################
+# ResourceWarning session.
+##############################################################################
+
+
+class DPKTWarning(BaseWarning, ResourceWarning):
+    """Warnings on DPKT usage."""
+
+
+class ScapyWarning(BaseWarning, ResourceWarning):
+    """Warnings on Scapy usage."""
+
+
+class PySharkWarning(BaseWarning, ResourceWarning):
+    """Warnings on PyShark usage."""
+
+
+class EmojiWarning(BaseWarning, ResourceWarning):
+    """Warnings on Emoji usage."""
+
+
+class VendorWarning(BaseWarning, ResourceWarning):
+    """Warnings on vendor usage."""
+
+
+##############################################################################
+# DeprecationWarning session.
+##############################################################################
+
+
+class DeprecatedFormatWarning(BaseWarning, DeprecationWarning):
+    """Warning on deprecated formats."""