New distribution [0.15.2]

 * added register interface to protocols for extensibility
 * revised pcapkit.foundation.analysis, now supports extensibility through register function
 * minor bugfix in traceflow for consistency in format and output

Author: JarryShaw

doc/sphinx/source/conf.py

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

pcapkit/__main__.py

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

pcapkit/foundation/analysis.py

@@ -7,6 +7,7 @@
 corresponding modules and functions to extract the attributes.
 
 """
+import importlib
 import os
 
 from pcapkit.protocols.raw import Raw
@@ -21,6 +22,13 @@
 
 __all__ = ['analyse']
 
+#: List of protocols supported by the analyser.
+ANALYSE_PROTO = [
+    ('pcapkit.protocols.application.ftp', 'FTP'),
+    ('pcapkit.protocols.application.httpv1', 'HTTPv1'),
+    ('pcapkit.protocols.application.httpv2', 'HTTPv2'),
+]
+
 
 def analyse(file, length=None, *, termination=False):
     """Analyse application layer packets.
@@ -44,23 +52,22 @@ def analyse(file, length=None, *, termination=False):
 
         and :class:`~pcapkit.protocols.raw.Raw` as the fallback result.
 
+    See Also:
+        The analysis processes order is defined by :data:`~pcapkit.foundation.analysis.ANALYSE_PROTO`.
+
     """
     seekset = file.tell()
     if not termination:
-        # FTP analysis
-        flag, ftp = _analyse_ftp(file, length, seekset=seekset)
-        if flag:
-            return ftp
+        for (module, name) in ANALYSE_PROTO:
+            try:
+                protocol = getattr(importlib.import_module(module), name)
+            except (ImportError, AttributeError):
+                continue
 
-        # HTTP/1.* analysis
-        flag, http = _analyse_httpv1(file, length, seekset=seekset)
-        if flag:
-            return http
-
-        # HTTP/2 analysis
-        flag, http = _analyse_httpv2(file, length, seekset=seekset)
-        if flag:
-            return http
+            packet = _analyse(protocol, file, length, seekset=seekset)
+            if packet is None:
+                continue
+            return packet
 
         # backup file offset
         file.seek(seekset, os.SEEK_SET)
@@ -70,75 +77,46 @@ def analyse(file, length=None, *, termination=False):
 
 
 @seekset_ng
-def _analyse_httpv1(file, length=None, *, seekset=os.SEEK_SET):  # pylint: disable=unused-argument
-    """Analyse HTTP/1.* packet.
+def _analyse(protocol, file, length=None, *, seekset=os.SEEK_SET):  # pylint: disable=unused-argument
+    """Analyse packet.
 
     Args:
+        protocol (Protocol): target protocol class
         file (io.BytesIO): source data stream
         length (Optional[int]): packet length
 
     Keyword Args:
         seekset (int): original file offset
 
     Returns:
-        Tuple[bool, Optional[HTTPv1]]: If the packet is HTTP/1.*,
-        returns :data:`True` and parsed HTTP/1.* packet; otherwise
-        returns :data:`False` and :data:`None`.
+        Optional[Protocol]: If the packet is parsed successfully,
+        returns the parsed  packet; otherwise returns :data:`None`.
 
     """
     try:
-        from pcapkit.protocols.application.httpv1 import HTTPv1
-        http = HTTPv1(file, length)
+        packet = protocol(file, length)
     except ProtocolError:
-        return False, None
-    return True, http
+        packet = None
+    return packet
 
 
-@seekset_ng
-def _analyse_httpv2(file, length, *, seekset=os.SEEK_SET):  # pylint: disable=unused-argument
-    """Analyse HTTP/2 packet.
+def register(module, class_, *, index=None):
+    """Register a new protocol class.
 
-    Args:
-        file (io.BytesIO): source data stream
-        length (Optional[int]): packet length
+    Arguments:
+        module (str): module name
+        class_ (str): class name
 
-    Keyword Args:
-        seekset (int): original file offset
-
-    Returns:
-        Tuple[bool, Optional[HTTPv1]]: If the packet is HTTP/2,
-        returns :data:`True` and parsed HTTP/2 packet; otherwise
-        returns :data:`False` and :data:`None`.
-
-    """
-    try:
-        from pcapkit.protocols.application.httpv2 import HTTPv2
-        http = HTTPv2(file, length)
-    except ProtocolError:
-        return False, None
-    return True, http
+    Keyword Arguments:
+        index (Optional[int]): Index of the protocol class
+            when inserted to :data:`~pcapkit.foundation.analysis.ANALYSE_PROTO`.
 
-
-@seekset_ng
-def _analyse_ftp(file, length, *, seekset=os.SEEK_SET):  # pylint: disable=unused-argument
-    """Analyse FTP packet.
-
-    Args:
-        file (io.BytesIO): source data stream
-        length (Optional[int]): packet length
-
-    Keyword Args:
-        seekset (int): original file offset
-
-    Returns:
-        Tuple[bool, Optional[HTTPv1]]: If the packet is FTP,
-        returns :data:`True` and parsed FTP packet; otherwise
-        returns :data:`False` and :data:`None`.
+    Notes:
+        The full qualified class name of the new protocol class
+        should be as ``{module}.{class_}``.
 
     """
-    try:
-        from pcapkit.protocols.application.ftp import FTP
-        ftp = FTP(file, length)
-    except ProtocolError:
-        return False, None
-    return True, ftp
+    if index is None:
+        ANALYSE_PROTO.append((module, class_))
+    else:
+        ANALYSE_PROTO.insert(index, (module, class_))

pcapkit/foundation/traceflow.py

@@ -126,6 +126,9 @@ def make_fout(fout='./tmp', fmt='pcap'):
             FileExists: If ``fout`` exists and ``fmt`` is **NOT** :data:`None`.
 
         """
+        if fout is None:
+            fout = './tmp'
+
         if fmt == 'pcap':       # output PCAP file
             from pcapkit.dumpkit import PCAP as output
         elif fmt == 'plist':    # output PLIST file

pcapkit/protocols/internet/internet.py

@@ -61,6 +61,26 @@ def layer(self):
         """
         return self.__layer__
 
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    @classmethod
+    def register(cls, code, module, class_):
+        """Register a new protocol class.
+
+        Arguments:
+            code (int): protocol code as in :class:`~pcapkit.const.reg.transtype.TransType`
+            module (str): module name
+            class_ (str): class name
+
+        Notes:
+            The full qualified class name of the new protocol class
+            should be as ``{module}.{class_}``.
+
+        """
+        cls.__proto__[code] = (module, class_)
+
     ##########################################################################
     # Utilities.
     ##########################################################################
@@ -168,7 +188,10 @@ def _import_next_layer(self, proto, length=None, *, version=4, extension=False):
             from pcapkit.protocols.raw import Raw as protocol  # pylint: disable=import-outside-toplevel
         else:
             module, name = self.__proto__[proto]
-            protocol = getattr(importlib.import_module(module), name)
+            try:
+                protocol = getattr(importlib.import_module(module), name)
+            except (ImportError, AttributeError):
+                from pcapkit.protocols.raw import Raw as protocol  # pylint: disable=import-outside-toplevel
 
         next_ = protocol(self._file, length, version=version, extension=extension,
                          error=self._onerror, layer=self._exlayer, protocol=self._exproto)

pcapkit/protocols/link/link.py

@@ -53,6 +53,26 @@ def layer(self):
         """
         return self.__layer__
 
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    @classmethod
+    def register(cls, code, module, class_):
+        """Register a new protocol class.
+
+        Arguments:
+            code (int): protocol code as in :class:`~pcapkit.const.reg.ethertype.EtherType`
+            module (str): module name
+            class_ (str): class name
+
+        Notes:
+            The full qualified class name of the new protocol class
+            should be as ``{module}.{class_}``.
+
+        """
+        cls.__proto__[code] = (module, class_)
+
     ##########################################################################
     # Utilities.
     ##########################################################################
@@ -110,7 +130,10 @@ def _import_next_layer(self, proto, length=None):
             from pcapkit.protocols.raw import Raw as protocol  # pylint: disable=import-outside-toplevel
         else:
             module, name = self.__proto__[proto]
-            protocol = getattr(importlib.import_module(module), name)
+            try:
+                protocol = getattr(importlib.import_module(module), name)
+            except (ImportError, AttributeError):
+                from pcapkit.protocols.raw import Raw as protocol  # pylint: disable=import-outside-toplevel
 
         next_ = protocol(self._file, length, error=self._onerror,
                          layer=self._exlayer, protocol=self._exproto)

pcapkit/protocols/pcap/frame.py

@@ -79,6 +79,22 @@ def length(self):
     # Methods.
     ##########################################################################
 
+    @classmethod
+    def register(cls, code, module, class_):
+        """Register a new protocol class.
+
+        Arguments:
+            code (int): protocol code as in :class:`~pcapkit.const.reg.linktype.LinkType`
+            module (str): module name
+            class_ (str): class name
+
+        Notes:
+            The full qualified class name of the new protocol class
+            should be as ``{module}.{class_}``.
+
+        """
+        cls.__proto__[code] = (module, class_)
+
     def index(self, name):
         """Call :meth:`ProtoChain.index <pcapkit.corekit.protochain.ProtoChain.index>`.
 
@@ -411,7 +427,11 @@ def _import_next_layer(self, proto, length, error=False):  # pylint: disable=arg
 
         """
         module, name = self.__proto__[int(proto)]
-        protocol = getattr(importlib.import_module(module), name)
+        try:
+            protocol = getattr(importlib.import_module(module), name)
+        except (ImportError, AttributeError):
+            from pcapkit.protocols.raw import Raw as protocol  # pylint: disable=import-outside-toplevel
+
         next_ = protocol(self._file, length, error=error,
                          layer=self._exlayer, protocol=self._exproto)
         return next_

pcapkit/utilities/decorators.py

@@ -63,18 +63,20 @@ def seekset_ng(func):
     Note:
         The decorated function should have following signature::
 
-            func(file, *args, seekset=os.SEEK_SET, **kw)
+            func(protocol, file, *args, seekset=os.SEEK_SET, **kw)
+
+        c.f. :func:`pcapkit.foundation.analysis._analyse`.
 
     See Also:
         :mod:`pcapkit.foundation.analysis`
 
     :meta decorator:
     """
     @functools.wraps(func)
-    def seekcur(file, *args, seekset=os.SEEK_SET, **kw):  # pylint: disable=redefined-outer-name
+    def seekcur(protocol, file, *args, seekset=os.SEEK_SET, **kw):  # pylint: disable=redefined-outer-name
         # seek_cur = file.tell()
         file.seek(seekset, os.SEEK_SET)
-        return_ = func(file, *args, seekset=seekset, **kw)
+        return_ = func(protocol, file, *args, seekset=seekset, **kw)
         # file.seek(seek_cur, os.SEEK_SET)
         return return_
     return seekcur

pcapkit/vendor/__main__.py

@@ -11,7 +11,7 @@
 from pcapkit.vendor import __all__ as vendor_all
 
 #: version string
-__version__ = '0.15.1.post1'
+__version__ = '0.15.2'
 
 
 def get_parser():

setup.py

@@ -4,7 +4,7 @@
 import sys
 
 # version string
-__version__ = '0.15.1.post1'
+__version__ = '0.15.2'
 
 # README
 with open('README.md', encoding='utf-8') as file: