New distribution [0.15.3]

 * bugfix for #55 (ARP parsing issue)
 * added logging interation (as `pcapkit` logger)

Author: JarryShaw

.vscode/settings.json

@@ -178,6 +178,7 @@
         "nofile",
         "noindex",
         "nonr",
+        "nosec",
         "nrec",
         "nsec",
         "nseq",

Pipfile

@@ -29,9 +29,10 @@ beautifulsoup4 = {extras = ["html5lib"],version = "*"}
 requests = {extras = ["socks"],version = "*"}
 ipython = "*"
 autopep8 = "*"
+bandit = "*"
+mypy = "*"
 pylint = "*"
 sphinx = "*"
-sphinxcontrib-napoleon = "*"
 doc8 = "*"
 rstcheck = "*"
 

Pipfile.lock

@@ -22,7 +22,7 @@
 author = 'Jarry Shaw'
 
 # The full version, including alpha/beta/rc tags
-release = '0.15.2'
+release = '0.15.3'
 
 
 # -- General configuration ---------------------------------------------------

doc/sphinx/source/conf.py

@@ -14,5 +14,6 @@ several user-refined exceptions and validations.
 
    decorators
    exceptions
+   logging
    validations
    warnings

doc/sphinx/source/utilities/index.rst

@@ -0,0 +1,8 @@
+Logging System
+==============
+
+: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`.
+
+.. autodata:: pcapkit.utilities.logging.logger

doc/sphinx/source/utilities/logging.rst

@@ -15,7 +15,7 @@
 from pcapkit.interface import JSON, PLIST, TREE
 
 #: version number
-__version__ = '0.15.2'
+__version__ = '0.15.3'
 
 
 def get_parser():

pcapkit/__main__.py

@@ -386,7 +386,7 @@ def __repr__(self):
             ProtoChain(<class 'pcapkit.protocols.link.ethernet.Ethernet'>, ...)
 
         """
-        return f"ProtoChain({', '.join(self.__proto__.data)})"
+        return f"ProtoChain({', '.join(map(lambda p: p.__name__, self.__proto__.data))})"
 
     def __str__(self):
         """Returns formatted hex representation of source data stream.
@@ -412,3 +412,15 @@ def __contains__(self, name):
 
         """
         return (name in self.__proto__) or (name in self.__alias__)
+
+    def __getitem__(self, index):
+        """Subscription (``getitem``) support.
+
+        Args:
+            index (int): Indexing key.
+
+        Returns:
+            str: Protocol alias at such index.
+
+        """
+        return self.__alias__[index]

pcapkit/corekit/protochain.py

@@ -31,6 +31,7 @@
 from pcapkit.utilities.compat import pathlib
 from pcapkit.utilities.exceptions import (CallableError, FileNotFound, FormatError, IterableError,
                                           UnsupportedCall, stacklevel)
+from pcapkit.utilities.logging import logger
 from pcapkit.utilities.warnings import (AttributeWarning, DPKTWarning, EngineWarning, FormatWarning,
                                         LayerWarning, ProtocolWarning)
 
@@ -889,6 +890,7 @@ def _default_read_frame(self, *, frame=None, mpkit=None):
             self._frnum += 1
 
         # verbose output
+        logger.info(f'Frame {self._frnum:>3d}: {frame.protochain}')  # pylint: disable=logging-fstring-interpolation
         if self._flag_v:
             if self._vfunc is NotImplemented:
                 print(f' - Frame {self._frnum:>3d}: {frame.protochain}')
@@ -1000,6 +1002,7 @@ def _scapy_read_frame(self):
         # verbose output
         self._frnum += 1
         self._proto = packet2chain(packet)
+        logger.info(f'Frame {self._frnum:>3d}: {self._proto}')  # pylint: disable=logging-fstring-interpolation
         if self._flag_v:
             if self._vfunc is NotImplemented:
                 print(f' - Frame {self._frnum:>3d}: {self._proto}')
@@ -1116,6 +1119,7 @@ def _dpkt_read_frame(self):
         # verbose output
         self._frnum += 1
         self._proto = packet2chain(packet)
+        logger.info(f'Frame {self._frnum:>3d}: {self._proto}')  # pylint: disable=logging-fstring-interpolation
         if self._flag_v:
             if self._vfunc is NotImplemented:
                 print(f' - Frame {self._frnum:>3d}: {self._proto}')
@@ -1230,6 +1234,7 @@ def _pyshark_read_frame(self):
         # verbose output
         self._frnum = int(packet.number)
         self._proto = packet.frame_info.protocols
+        logger.info(f'Frame {self._frnum:>3d}: {self._proto}')  # pylint: disable=logging-fstring-interpolation
         if self._flag_v:
             if self._vfunc is NotImplemented:
                 print(f' - Frame {self._frnum:>3d}: {self._proto}')

pcapkit/foundation/extraction.py

@@ -163,7 +163,7 @@ def read(self, length=None, **kwargs):  # pylint: disable=unused-argument
             self._name = 'Address Resolution Protocol'
 
         _htype = HRD.get(_hwty)
-        if re.match(r'.*Ethernet.*', _htype, re.IGNORECASE):
+        if re.match(r'.*Ethernet.*', _htype.name, re.IGNORECASE):
             _ptype = ETHERTYPE.get(_ptty)
         else:
             _ptype = f'Unknown [{_ptty}]'

pcapkit/protocols/link/arp.py

@@ -32,6 +32,7 @@
 from pcapkit.utilities.decorators import beholder, seekset
 from pcapkit.utilities.exceptions import (ProtocolNotFound, ProtocolNotImplemented, ProtocolUnbound,
                                           StructError)
+from pcapkit.utilities.logging import logger
 
 __all__ = ['Protocol']
 
@@ -122,7 +123,7 @@ def protocol(self):
         :rtype: Optional[str]
         """
         with contextlib.suppress(IndexError):
-            return self._protos[1]
+            return self._protos[0]
 
     # protocol chain of current instance
     @property
@@ -266,6 +267,8 @@ def __init__(self, file=None, length=None, **kwargs):
             **kwargs: Arbitrary keyword arguments.
 
         """
+        logger.debug(type(self).__name__)
+
         #: bool: If the object is initiated  after parsing errors.
         self._onerror = kwargs.pop('_error', False)
         #: str: Parse packet until such layer.

pcapkit/protocols/protocol.py

@@ -12,7 +12,9 @@
 from pcapkit.utilities.compat import *  # pylint: disable=redefined-builtin
 from pcapkit.utilities.decorators import *
 from pcapkit.utilities.exceptions import *
+from pcapkit.utilities.logging import *
 from pcapkit.utilities.validations import *
 from pcapkit.utilities.warnings import *
 
-__all__ = ['seekset_ng', 'beholder_ng']
+__all__ = ['logger', 'warn', 'stacklevel',
+           'seekset_ng', 'beholder_ng']

pcapkit/utilities/__init__.py

@@ -12,6 +12,8 @@
 import os
 import traceback
 
+from pcapkit.utilities.logging import logger
+
 ###############################################################################
 # from pcapkit.foundation.analysis import analyse
 # from pcapkit.protocols.raw import Raw
@@ -109,11 +111,14 @@ def behold(self, proto, length, *args, **kwargs):
         seek_cur = self._file.tell()
         try:
             return func(proto, length, *args, **kwargs)
-        except Exception:
+        except Exception as exc:
             from pcapkit.protocols.raw import Raw  # pylint: disable=import-outside-toplevel
             error = traceback.format_exc(limit=1).strip().split(os.linesep)[-1]
             # error = traceback.format_exc()
 
+            # log error
+            logger.error(error, exc_info=exc)
+
             self._file.seek(seek_cur, os.SEEK_SET)
             next_ = Raw(io.BytesIO(self._read_fileng(length)), length, error=error)
             return next_
@@ -145,12 +150,15 @@ def behold(file, length, *args, **kwargs):
         seek_cur = file.tell()
         try:
             return func(file, length, *args, **kwargs)
-        except Exception:
+        except Exception as exc:
             # from pcapkit.foundation.analysis import analyse
             from pcapkit.protocols.raw import Raw  # pylint: disable=import-outside-toplevel
             error = traceback.format_exc(limit=1).strip().split(os.linesep)[-1]
             # error = traceback.format_exc()
 
+            # log error
+            logger.error(error, exc_info=exc)
+
             file.seek(seek_cur, os.SEEK_SET)
 
             # raw = Raw(file, length, error=str(error))