pypcapkit 0.16.3__tar.gz → 1.0.0__tar.gz

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2018-2022, Jarry Shaw
+Copyright (c) 2018-2023, Jarry Shaw
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/MANIFEST.in

@@ -1,21 +1,15 @@
 global-exclude .DS_Store
 
-global-include *.md
+global-include *.rst
 global-include *.py
 
+prune .eggs
 prune .github
 prune .venv
-prune .vscode
-
-prune archive
-prune devel
-prune doc
-prune release
+prune docs
 prune sample
-prune src
-prune test
-prune testbench
 prune temp
+prune test
 
 include README.rst
 include LICENSE

{pypcapkit-0.16.3/pypcapkit.egg-info → pypcapkit-1.0.0}/PKG-INFO

@@ -1,50 +1,54 @@
 Metadata-Version: 2.1
 Name: pypcapkit
-Version: 0.16.3
-Summary: Python multi-engine PCAP analyse kit.
-Home-page: https://github.com/JarryShaw/PyPCAPKit
-Download-URL: https://github.com/JarryShaw/PyPCAPKit/archive/v0.16.3.tar.gz
-Author: Jarry Shaw
-Author-email: jarryshaw@icloud.com
+Version: 1.0.0
+Summary: PyPCAPKit: comprehensive network packet analysis library
+Author-email: Jarry Shaw <jarryshaw@icloud.com>
 Maintainer: Jarry Shaw
-Maintainer-email: jarryshaw@icloud.com
 License: BSD 3-Clause License
-Keywords: computer-networking,pcap-analyser,pcap-parser
-Platform: any
+Project-URL: homepage, https://jarryshaw.github.io/PyPCAPKit/
+Project-URL: documentation, https://jarryshaw.github.io/PyPCAPKit/
+Project-URL: repository, https://github.com/JarryShaw/PyPCAPKit
+Project-URL: changelog, https://github.com/JarryShaw/PyPCAPKit/releases
+Keywords: network,pcap,packet
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Environment :: MacOS X
 Classifier: Environment :: Win32 (MS Windows)
 Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Telecommunications Industry
 Classifier: License :: OSI Approved :: BSD License
-Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: Implementation
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Security
 Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Networking :: Monitoring
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.6
+Requires-Python: <4,>=3.6
 Description-Content-Type: text/x-rst
-Provides-Extra: all
 Provides-Extra: cli
 Provides-Extra: DPKT
 Provides-Extra: Scapy
 Provides-Extra: PyShark
 Provides-Extra: vendor
+Provides-Extra: all
+Provides-Extra: docs
 License-File: LICENSE
 
-PyPCAPKit - Stream PCAP File Extractor
-======================================
+PyPCAPKit - Comprehensive Network Packet Analysis Library
+=========================================================
 
    For any technical and/or maintenance information,
    please kindly refer to the |docs|_.
@@ -53,9 +57,10 @@ PyPCAPKit - Stream PCAP File Extractor
 .. _docs: https://jarryshaw.github.io/PyPCAPKit/
 
 The PyPCAPKit project is an open source Python program focus
-on `PCAP`_ parsing and analysis, which works as a stream PCAP file extractor.
-With support of `DictDumper`_, it shall support multiple
-output report formats.
+on `PCAP`_ parsing and analysis, which works as a network
+packet extraction, construction and analysis library. With
+support of `DictDumper`_, it shall support multiple output
+report formats.
 
    The whole project supports **Python 3.6** or later.
 
@@ -130,10 +135,12 @@ Engine Comparison
 -----------------
 
 Due to the general overhead of ``pcapkit``, its extraction procedure takes
-around *0.0008* seconds per packet, which is already impressive but not enough
-comparing to other popular extration engines availbale on the market. Thus
-``pcapkit`` introduced alternative extractionengines to accelerate this
-procedure. By now ``pcapkit`` supports `Scapy`_, `DPKT`_, and `PyShark`_.
+around *0.96* milliseconds per packet, which is already impressive but not enough
+comparing to other popular extration engines availbale on the market, given the
+fact that ``pcapkit`` is a **comprehensive** packet processing module.
+
+Additionally, ``pcapkit`` introduced alternative extractionengines to accelerate
+this procedure. By now ``pcapkit`` supports `Scapy`_, `DPKT`_, and `PyShark`_.
 
 Test Environment
 ~~~~~~~~~~~~~~~~
@@ -141,27 +148,23 @@ Test Environment
 .. list-table::
 
    * - Operating System
-     - macOS Monterey
-   * - Processor Name
-     - Intel Core i7
-   * - Processor Speed
-     - 2.6 GHz
-   * - Total Number of Cores
-     - 6
+     - macOS Ventura 13.4 Beta (22F5037d)
+   * - Chip
+     - Apple M2 Pro
    * - Memory
      - 16 GB
 
 Test Results
 ~~~~~~~~~~~~
 
-============= =================================
-Engine        Performance (seconds per packet)
-============= =================================
-``dpkt``      0.00006832083066304525
-``scapy``     0.0002489296595255534
-``pcapkit``   0.0008274253209431966
-``pyshark``   0.039607704480489093
-============= =================================
+============= ===========================
+Engine        Performance (ms per packet)
+============= ===========================
+``dpkt``      0.048088_922256
+``scapy``     0.127444_444444
+``pcapkit``   0.964180_847514
+``pyshark``   23.665003_003003
+============= ===========================
 
 ------------
 Installation

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/README.rst

@@ -1,5 +1,5 @@
-PyPCAPKit - Stream PCAP File Extractor
-======================================
+PyPCAPKit - Comprehensive Network Packet Analysis Library
+=========================================================
 
    For any technical and/or maintenance information,
    please kindly refer to the |docs|_.
@@ -8,9 +8,10 @@ PyPCAPKit - Stream PCAP File Extractor
 .. _docs: https://jarryshaw.github.io/PyPCAPKit/
 
 The PyPCAPKit project is an open source Python program focus
-on `PCAP`_ parsing and analysis, which works as a stream PCAP file extractor.
-With support of `DictDumper`_, it shall support multiple
-output report formats.
+on `PCAP`_ parsing and analysis, which works as a network
+packet extraction, construction and analysis library. With
+support of `DictDumper`_, it shall support multiple output
+report formats.
 
    The whole project supports **Python 3.6** or later.
 
@@ -85,10 +86,12 @@ Engine Comparison
 -----------------
 
 Due to the general overhead of ``pcapkit``, its extraction procedure takes
-around *0.0008* seconds per packet, which is already impressive but not enough
-comparing to other popular extration engines availbale on the market. Thus
-``pcapkit`` introduced alternative extractionengines to accelerate this
-procedure. By now ``pcapkit`` supports `Scapy`_, `DPKT`_, and `PyShark`_.
+around *0.96* milliseconds per packet, which is already impressive but not enough
+comparing to other popular extration engines availbale on the market, given the
+fact that ``pcapkit`` is a **comprehensive** packet processing module.
+
+Additionally, ``pcapkit`` introduced alternative extractionengines to accelerate
+this procedure. By now ``pcapkit`` supports `Scapy`_, `DPKT`_, and `PyShark`_.
 
 Test Environment
 ~~~~~~~~~~~~~~~~
@@ -96,27 +99,23 @@ Test Environment
 .. list-table::
 
    * - Operating System
-     - macOS Monterey
-   * - Processor Name
-     - Intel Core i7
-   * - Processor Speed
-     - 2.6 GHz
-   * - Total Number of Cores
-     - 6
+     - macOS Ventura 13.4 Beta (22F5037d)
+   * - Chip
+     - Apple M2 Pro
    * - Memory
      - 16 GB
 
 Test Results
 ~~~~~~~~~~~~
 
-============= =================================
-Engine        Performance (seconds per packet)
-============= =================================
-``dpkt``      0.00006832083066304525
-``scapy``     0.0002489296595255534
-``pcapkit``   0.0008274253209431966
-``pyshark``   0.039607704480489093
-============= =================================
+============= ===========================
+Engine        Performance (ms per packet)
+============= ===========================
+``dpkt``      0.048088_922256
+``scapy``     0.127444_444444
+``pcapkit``   0.964180_847514
+``pyshark``   23.665003_003003
+============= ===========================
 
 ------------
 Installation

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/pcapkit/__init__.py

@@ -3,6 +3,8 @@
 """Stream PCAP File Extractor
 ================================
 
+.. module:: pcapkit
+
 :mod:`pcapkit` is an independent open source library, using only
 `DictDumper`_ as its formatted output dumper.
 
@@ -74,7 +76,7 @@ from pcapkit.utilities.warnings import DevModeWarning
 if DEVMODE:
     warnings.showwarning('development mode enabled', DevModeWarning,
                          filename=__file__, lineno=0,
-                         line=f"PCAPKIT_DEVMODE={os.environ['PCAPKIT_DEVMODE']}")
+                         line=f"PCAPKIT_DEVMODE={os.environ.get('PCAPKIT_DEVMODE', '1')}")
 else:
     ROOT = os.path.dirname(os.path.realpath(__file__))
     tbtrim.set_trim_rule(lambda filename: ROOT in os.path.realpath(filename),
@@ -106,5 +108,9 @@ __all__ = [
 
     'TCP', 'UDP',                                           # Transport Layer
 
-    'FTP', 'HTTP',                                          # Application Layer
+    'FTP', 'FTP_DATA',                                      # Application Layer
+    'HTTP',
 ]
+
+#: version number
+__version__ = '1.0.0'

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/pcapkit/__main__.py

@@ -2,6 +2,8 @@
 """Command Line Tool
 =======================
 
+.. module:: pcapkit.__main__
+
 .. important::
 
    This module requires ``emoji`` package to be installed.
@@ -17,6 +19,9 @@ import argparse
 import sys
 from typing import TYPE_CHECKING
 
+from pcapkit import __version__
+from pcapkit.foundation.extraction import Extractor
+from pcapkit.interface import JSON, PLIST, TREE
 from pcapkit.utilities.compat import ModuleNotFoundError  # pylint: disable=redefined-builtin
 from pcapkit.utilities.exceptions import stacklevel
 from pcapkit.utilities.warnings import EmojiWarning, warn
@@ -27,15 +32,11 @@ except ModuleNotFoundError:
     warn("dependency package 'emoji' not found",
          EmojiWarning, stacklevel=stacklevel())
 
-from pcapkit.foundation.extraction import Extractor
-from pcapkit.interface import JSON, PLIST, TREE
+__all__ = ['main']
 
 if TYPE_CHECKING:
     from argparse import ArgumentParser
 
-#: version number
-__version__ = '0.16.3'
-
 
 def get_parser() -> 'ArgumentParser':
     """CLI argument parser."""
@@ -103,7 +104,7 @@ def main() -> 'int':
                           files=args.files, format=fmt,
                           layer=args.layer, protocol=args.protocol,
                           engine=args.engine, extension=args.auto_extension,
-                          verbose=args.verbose)
+                          verbose=args.verbose)  # type: ignore[var-annotated]
 
     if args.verbose:
         try:

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/pcapkit/all.py

@@ -3,6 +3,8 @@
 """Library Index
 ===================
 
+.. module:: pcapkit.all
+
 :mod:`pcapkit` has defined various and numerous functions
 and classes, which have different features and purposes.
 To make a simple index for this library, :mod:`pcapkit.all`
@@ -52,9 +54,19 @@ __all__ = [
     'Info',                                                 # Info Class
     'ProtoChain',                                           # ProtoChain
     'VersionInfo',                                          # Version
+    'NumberField', 'Int32Field', 'UInt32Field',             # numeric protocol fields
+    'Int16Field', 'UInt16Field', 'Int64Field', 'UInt64Field',
+    'Int8Field', 'UInt8Field', 'EnumField',
+    'BytesField', 'StringField', 'BitField',                # text protocol fields
+    'PaddingField',
+    'ConditionalField', 'PayloadField', 'SchemaField',      # misc protocol fields
+    'ForwardMatchField', 'NoValueField',
+    'IPv4AddressField', 'IPv6AddressField',                 # IP address protocol fields
+    'IPv4InterfaceField', 'IPv6InterfaceField',
+    'ListField', 'OptionField',                             # container protocol fields
 
     # pcapkit.dumpkit
-    'PCAPIO',                                                 # PCAP Dumper
+    'PCAPIO',                                               # PCAP Dumper
     'NotImplementedIO',                                     # Simulated I/O
 
     # pcapkit.foundation
@@ -67,11 +79,16 @@ __all__ = [
 
     # pcapkit.foundation.registry
     'register_protocol',
-    'register_linktype', 'register_pcap',
+    'register_linktype', 'register_pcap', 'register_pcapng',
     'register_ethertype', 'register_transtype',
     'register_port', 'register_tcp_port', 'register_udp_port',
-    'register_output', 'register_extractor', 'register_traceflow',
+    'register_output',
+    'register_extractor_dumper', 'register_extractor_engine',
+    'register_traceflow',
+    'register_pcapng_block', 'register_pcapng_option', 'register_pcapng_secrets',
+    'register_pcapng_record',
     'register_hopopt', 'register_ipv6_opts', 'register_ipv6_route',
+    'register_ipv4', 'register_hip',
     'register_tcp', 'register_mptcp',
     'register_http',
 
@@ -92,11 +109,15 @@ __all__ = [
     'HIP', 'HOPOPT', 'IPv6_Frag', 'IPv6_Opts', 'IPv6_Route', 'MH',
                                                             # IPv6 Extension Header
     'TCP', 'UDP',                                           # Transport Layer
-    'FTP', 'HTTP',                                          # Application Layer
+    'FTP', 'FTP_DATA',                                      # Application Layer
+    'HTTP',
+    'Schema', 'schema',                                     # Protocol Schema
+    'Data', 'data',                                         # Protocol Data
 
     # pcapkit.toolkit
     'ipv4_reassembly', 'ipv6_reassembly', 'tcp_reassembly', 'tcp_traceflow',
-                                                            # default engine
+    'pcapng_ipv4_reassembly', 'pcapng_ipv6_reassembly', 'pcapng_tcp_reassembly', 'pcapng_tcp_traceflow',
+    'pcapng_block2frame',                                   # default engine
     'dpkt_ipv6_hdr_len', 'dpkt_packet2chain', 'dpkt_packet2dict',
     'dpkt_ipv4_reassembly', 'dpkt_ipv6_reassembly', 'dpkt_tcp_reassembly', 'dpkt_tcp_traceflow',
                                                             # DPKT engine

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/pcapkit/const/__init__.py

@@ -11,6 +11,9 @@ automatically generated from the :mod:`pcapkit.vendor` module.
 # IANA registration
 from pcapkit.const.reg import *
 
+# Miscellanous
+from pcapkit.const.pcapng import *
+
 # per protocol
 from pcapkit.const.arp import *
 from pcapkit.const.ftp import *
@@ -36,26 +39,42 @@ __all__ = [
     'HIP_Certificate', 'HIP_Cipher', 'HIP_DITypes', 'HIP_ECDSACurve', 'HIP_ECDSALowCurve',
     'HIP_ESPTransformSuite', 'HIP_Group', 'HIP_HIAlgorithm', 'HIP_HITSuite', 'HIP_NATTraversal',
     'HIP_NotifyMessage', 'HIP_Packet', 'HIP_Parameter', 'HIP_Registration', 'HIP_RegistrationFailure',
-    'HIP_Suite', 'HIP_Transport',
+    'HIP_Suite', 'HIP_Transport', 'HIP_EdDSACurve',
     # HTTP
-    'HTTP_ErrorCode', 'HTTP_Frame', 'HTTP_Setting',
+    'HTTP_ErrorCode', 'HTTP_Frame', 'HTTP_Method', 'HTTP_Setting', 'HTTP_Status',
     # IPv4
     'IPv4_ClassificationLevel', 'IPv4_OptionClass', 'IPv4_OptionNumber', 'IPv4_ProtectionAuthority',
     'IPv4_QSFunction', 'IPv4_RouterAlert', 'IPv4_ToSDelay', 'IPv4_ToSECN', 'IPv4_ToSPrecedence',
     'IPv4_ToSReliability', 'IPv4_ToSThroughput', 'IPv4_TSFlag',
     # IPv6
     'IPv6_ExtensionHeader', 'IPv6_Option', 'IPv6_QSFunction', 'IPv6_RouterAlert', 'IPv6_Routing',
-    'IPv6_SeedID', 'IPv6_SMFDPDMode', 'IPv6_TaggerID',
+    'IPv6_SeedID', 'IPv6_SMFDPDMode', 'IPv6_TaggerID', 'IPv6_OptionAction',
     # IPX
     'IPX_Packet', 'IPX_Socket',
     # L2TP
     'L2TP_Type',
     # MH
-    'MH_Packet',
+    'MH_Packet', 'MH_Option', 'MH_DNSStatusCode', 'MH_ACKStatusCode',
+    'MH_MNIDSubtype', 'MH_StatusCode', 'MH_EnumeratingAlgorithm',
+    'MH_AuthSubtype', 'MH_HandoffType', 'MH_AccessType',
+    'MH_BindingUpdateFlag', 'MH_BindingACKFlag', 'MH_DSMIPv6HomeAddress',
+    'MH_BindingRevocation', 'MH_RevocationTrigger', 'MH_RevocationStatusCode',
+    'MH_HomeAddressReply', 'MH_DHCPSupportMode', 'MH_HandoverInitiateFlag',
+    'MH_HandoverACKFlag', 'MH_HandoverACKStatus', 'MH_HandoverACKStatus',
+    'MH_FlowIDStatus', 'MH_FlowIDSuboption', 'MH_TrafficSelector',
+    'MH_MNGroupID', 'MH_DSMIP6TLSPacket', 'MH_ANISuboption', 'MH_OperatorID',
+    'MH_UpdateNotificationReason', 'MH_UpdateNotificationACKStatus',
+    'MH_FlowBindingType', 'MH_FlowBindingIndicationTrigger',
+    'MH_FlowBindingACKStatus', 'MH_FlowBindingAction', 'MH_QoSAttribute',
+    'MH_LMAControlledMAGSuboption',
     # OSPF
     'OSPF_Authentication', 'OSPF_Packet',
     # TCP
     'TCP_Checksum', 'TCP_Option',
     # VLAN
     'VLAN_PriorityLevel',
+    # PCAPNG
+    'PCAPNG_BlockType', 'PCAPNG_OptionType', 'PCAPNG_HashAlgorithm',
+    'PCAPNG_VerdictType', 'PCAPNG_RecordType', 'PCAPNG_SecretsType',
+    'PCAPNG_FilterType',
 ]

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/pcapkit/const/arp/hardware.py

@@ -3,6 +3,8 @@
 """Hardware Types
 ====================
 
+.. module:: pcapkit.const.arp.hardware
+
 This module contains the constant enumeration for **Hardware Types**,
 which is automatically generated from :class:`pcapkit.vendor.arp.hardware.Hardware`.
 
@@ -132,6 +134,9 @@ class Hardware(IntEnum):
     #: HFI [Tseng-Hui Lin]
     HFI = 37
 
+    #: Unified Bus (UB) [Luoqing Zhou]
+    Unified_Bus = 38
+
     #: HW_EXP2 [:rfc:`5494`]
     HW_EXP2 = 256
 
@@ -149,11 +154,12 @@ class Hardware(IntEnum):
             key: Key to get enum item.
             default: Default value if not found.
 
+        :meta private:
         """
         if isinstance(key, int):
             return Hardware(key)
         if key not in Hardware._member_map_:  # pylint: disable=no-member
-            extend_enum(Hardware, key, default)
+            return extend_enum(Hardware, key, default)
         return Hardware[key]  # type: ignore[misc]
 
     @classmethod
@@ -166,12 +172,10 @@ class Hardware(IntEnum):
         """
         if not (isinstance(value, int) and 0 <= value <= 65535):
             raise ValueError('%r is not a valid %s' % (value, cls.__name__))
-        if 38 <= value <= 255:
+        if 39 <= value <= 255:
             #: Unassigned
-            extend_enum(cls, 'Unassigned_%d' % value, value)
-            return cls(value)
+            return extend_enum(cls, 'Unassigned_%d' % value, value)
         if 258 <= value <= 65534:
             #: Unassigned
-            extend_enum(cls, 'Unassigned_%d' % value, value)
-            return cls(value)
+            return extend_enum(cls, 'Unassigned_%d' % value, value)
         return super()._missing_(value)

{pypcapkit-0.16.3 → pypcapkit-1.0.0}/pcapkit/const/arp/operation.py

@@ -3,6 +3,8 @@
 """Operation Codes
 =====================
 
+.. module:: pcapkit.const.arp.operation
+
 This module contains the constant enumeration for **Operation Codes**,
 which is automatically generated from :class:`pcapkit.vendor.arp.operation.Operation`.
 
@@ -105,11 +107,12 @@ class Operation(IntEnum):
             key: Key to get enum item.
             default: Default value if not found.
 
+        :meta private:
         """
         if isinstance(key, int):
             return Operation(key)
         if key not in Operation._member_map_:  # pylint: disable=no-member
-            extend_enum(Operation, key, default)
+            return extend_enum(Operation, key, default)
         return Operation[key]  # type: ignore[misc]
 
     @classmethod
@@ -124,6 +127,5 @@ class Operation(IntEnum):
             raise ValueError('%r is not a valid %s' % (value, cls.__name__))
         if 26 <= value <= 65534:
             #: Unassigned
-            extend_enum(cls, 'Unassigned_%d' % value, value)
-            return cls(value)
+            return extend_enum(cls, 'Unassigned_%d' % value, value)
         return super()._missing_(value)