diff --git a/docs/source/demo.rst b/docs/source/demo.rst index c7fb9580f..395a4f8ff 100644 --- a/docs/source/demo.rst +++ b/docs/source/demo.rst @@ -4,8 +4,7 @@ How to ... Basic Samples ------------- -:mod:`pcapkit` is quite easy to use, with simply three verbs as -its main interface. Several scenarios are shown as below. +:mod:`pcapkit` is built around three verbs. A few common scenarios: 1. extract a PCAP file and dump the result to a specific file (with no reassembly) @@ -50,7 +49,7 @@ its main interface. Several scenarios are shown as below. CLI Samples ----------- -The CLI (command line interface) of :mod:`pcapkit` has two different access. +:mod:`pcapkit`'s CLI (command line interface) can be reached two ways. * through console scripts @@ -70,14 +69,14 @@ Here are some usage samples: .. code-block:: shell $ pcapkit-cli in --auto-extension --format plist --verbose - 🚨Loading file 'in.pcap' + 🚨 Loading file 'in.pcap' Frame 1: Ethernet:IPv6:IPv6_ICMP Frame 2: Ethernet:IPv6:IPv6_ICMP Frame 3: Ethernet:IPv4:TCP Frame 4: Ethernet:IPv4:TCP Frame 5: Ethernet:IPv4:TCP Frame 6: Ethernet:IPv4:UDP:Raw - 🍺Report file stored in 'out.plist' + 🍺 Report file stored in 'out.plist' 2. export to a JSON file @@ -91,27 +90,27 @@ Here are some usage samples: .. code-block:: shell $ pcapkit-cli in --auto-extension --output out.json --format json --verbose - 🚨Loading file 'in.pcap' + 🚨 Loading file 'in.pcap' Frame 1: Ethernet:IPv6:IPv6_ICMP Frame 2: Ethernet:IPv6:IPv6_ICMP Frame 3: Ethernet:IPv4:TCP Frame 4: Ethernet:IPv4:TCP Frame 5: Ethernet:IPv4:TCP Frame 6: Ethernet:IPv4:UDP:Raw - 🍺Report file stored in 'out.json' + 🍺 Report file stored in 'out.json' 3. export to a text tree view file (without extension autocorrect) .. code-block:: shell $ pcapkit-cli in.pcap --output out.txt --format tree --verbose - 🚨Loading file 'in.pcap' + 🚨 Loading file 'in.pcap' Frame 1: Ethernet:IPv6:IPv6_ICMP Frame 2: Ethernet:IPv6:IPv6_ICMP Frame 3: Ethernet:IPv4:TCP Frame 4: Ethernet:IPv4:TCP Frame 5: Ethernet:IPv4:TCP Frame 6: Ethernet:IPv4:UDP:Raw - 🍺Report file stored in 'out.txt' + 🍺 Report file stored in 'out.txt' .. _Xcode: https://developer.apple.com/xcode diff --git a/docs/source/index.rst b/docs/source/index.rst index 91b1fb0a9..aa09a3795 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -48,8 +48,8 @@ About .. note:: - There is a project called |jspcapy|_ works on :mod:`pcapkit`, which is a - command line tool for PCAP extraction. + There is a project called |jspcapy|_ that works on :mod:`pcapkit`, which is + a command line tool for PCAP extraction. .. |jspcapy| replace:: ``jspcapy`` .. _jspcapy: https://github.com/JarryShaw/jspcapy @@ -59,11 +59,10 @@ About The |jspcapy|_ project is deprecated and has been merged into the :mod:`PyPCAPKit ` project as its CLI support. -Unlike popular PCAP file extractors, such as :mod:`Scapy `, -:mod:`dpkt `, `PyShark`_, and etc, :mod:`pcapkit` is -designed to be much more comprehensive, which means it is able to provide -more detailed information about the packet, as well as a more *Pythonic* -interface for users to interact with. +Unlike popular PCAP extractors such as :mod:`Scapy `, +:mod:`dpkt ` and `PyShark`_, :mod:`pcapkit` aims to be more +comprehensive: more detailed packet information, and a more *Pythonic* +interface. ---------------- Module Structure @@ -80,7 +79,7 @@ In :mod:`pcapkit`, all files can be described as following eight parts. Synthesises file I/O and protocol analysis, coordinates information exchange in all network layers, as well as - provides the foundamental functions for :mod:`pcapkit`. + provides the fundamental functions for :mod:`pcapkit`. - Protocols (:mod:`pcapkit.protocols`) @@ -114,17 +113,16 @@ In :mod:`pcapkit`, all files can be described as following eight parts. Engine Comparison ----------------- -Due to the general overhead of :mod:`pcapkit`, its extraction procedure takes -around *0.2* milliseconds per packet, which is already impressive but not enough -comparing to other popular extraction engines available on the market, given the -fact that :mod:`pcapkit` is a **comprehensive** packet processing module. +Being a **comprehensive** packet processor costs speed: :mod:`pcapkit`'s own +engine takes about *0.2* milliseconds per packet, slower than most of the +third-party engines below. -Additionally, :mod:`pcapkit` introduced alternative extraction engines to -accelerate this procedure. By now :mod:`pcapkit` supports `Scapy`_, `DPKT`_, -`PyShark`_, `PyPCAP`_, `pcap-ct`_ and `PyPCAPFile`_, selected through -``engine='scapy'``, ``'dpkt'``, ``'pyshark'``, ``'pypcap'``, ``'pcap_ct'`` and -``'pypcapfile'`` respectively; ``engine='default'`` (also spelled ``'pcapkit'``) -is :mod:`pcapkit`'s own parser and the only one with no third-party requirement. +:mod:`pcapkit` also supports alternative extraction engines for speed: +`Scapy`_, `DPKT`_, `PyShark`_, `PyPCAP`_, `pcap-ct`_ and `PyPCAPFile`_, +selected through ``engine='scapy'``, ``'dpkt'``, ``'pyshark'``, ``'pypcap'``, +``'pcap_ct'`` and ``'pypcapfile'`` respectively; ``engine='default'`` (also +spelled ``'pcapkit'``) is :mod:`pcapkit`'s own parser and the only one with no +third-party requirement. `PyPCAP`_ and `pcap-ct`_ are two independent distributions of the same :manpage:`libpcap(3)` interface and both install a top-level :mod:`pcap` module, @@ -175,9 +173,9 @@ Engine 3.10 3.11 3.12 3.13 3.14 3.15 [*]_ ``pypcap`` and ``pypcapfile`` stop at 3.11, and ``pyshark`` at 3.13, for the reasons under `Engine prerequisites`_. **Python 3.11 is the last version on which -every engine can run** -- and even there ``pypcap`` and ``pcap_ct`` are mutually -exclusive, since both provide the :mod:`pcap` module, so no single environment ever -has all seven at once. +every engine can run** -- and even there ``pypcap`` and ``pcap_ct`` remain +mutually exclusive for the reason given above, so no single environment ever has +all seven at once. Test Environment ---------------- @@ -255,13 +253,13 @@ Installation 3.8 and 3.9 are end-of-life and best-effort. Individual *engines* also stop earlier than the library does; see `Engine prerequisites`_. -Simply run the following to install the current version from PyPI: +Run the following to install the current version from PyPI: .. code-block:: shell pip install pypcapkit -Or install the latest version from the gi repository: +Or install the latest version from the git repository: .. code-block:: shell