Metadata-Version: 2.4
Name: pypcapkit
Version: 1.5.0b6
Summary: PyPCAPKit: comprehensive network packet analysis library
Author-email: Jarry Shaw <jarryshaw@icloud.com>
Maintainer: Jarry Shaw
License: BSD 3-Clause License
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://jarryshaw.github.io/PyPCAPKit/changelog.html
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: Operating System :: OS Independent
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
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: <4,>=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dictdumper~=0.8.0
Requires-Dist: chardet
Requires-Dist: aenum
Requires-Dist: tbtrim>=0.2.1
Requires-Dist: bpc-f2format; python_version < "3.6"
Requires-Dist: bpc-poseur; python_version < "3.8"
Requires-Dist: bpc-walrus; python_version < "3.8"
Requires-Dist: pathlib2>=2.3.2; python_version == "3.4"
Requires-Dist: typing-extensions; python_version < "3.11"
Provides-Extra: cli
Requires-Dist: emoji; extra == "cli"
Provides-Extra: crypto
Requires-Dist: cryptography>=3.4; extra == "crypto"
Provides-Extra: ngap
Requires-Dist: pycrate; extra == "ngap"
Provides-Extra: dpkt
Requires-Dist: dpkt; extra == "dpkt"
Provides-Extra: scapy
Requires-Dist: scapy; extra == "scapy"
Provides-Extra: pyshark
Requires-Dist: pyshark; extra == "pyshark"
Provides-Extra: pypcap
Requires-Dist: pypcap; python_version < "3.12" and extra == "pypcap"
Provides-Extra: pcap-ct
Requires-Dist: pcap-ct>=1.3.0b3; python_version >= "3.10" and extra == "pcap-ct"
Requires-Dist: libpcap>=1.11.0b29; python_version >= "3.10" and extra == "pcap-ct"
Provides-Extra: pypcapfile
Requires-Dist: pypcapfile; python_version < "3.12" and extra == "pypcapfile"
Provides-Extra: vendor
Requires-Dist: requests[socks]; extra == "vendor"
Requires-Dist: beautifulsoup4[html5lib]; extra == "vendor"
Requires-Dist: pycrate; extra == "vendor"
Provides-Extra: all
Requires-Dist: emoji; extra == "all"
Requires-Dist: cryptography>=3.4; extra == "all"
Requires-Dist: dpkt; extra == "all"
Requires-Dist: scapy; extra == "all"
Requires-Dist: pyshark; extra == "all"
Requires-Dist: pypcapfile; python_version < "3.12" and extra == "all"
Requires-Dist: requests[socks]; extra == "all"
Requires-Dist: beautifulsoup4[html5lib]; extra == "all"
Provides-Extra: docs
Requires-Dist: Sphinx>=6.1.3; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinxext-opengraph; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: typing-extensions; extra == "docs"
Requires-Dist: mypy-extensions; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-xdist>=3.6.1; extra == "test"
Requires-Dist: typing-extensions; extra == "test"
Requires-Dist: requests; extra == "test"
Requires-Dist: beautifulsoup4; extra == "test"
Requires-Dist: isort; extra == "test"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file

# PyPCAPKit -- Comprehensive Network Packet Analysis Library

> For any technical and/or maintenance information, please kindly refer to the
> **[Official Documentation](https://jarryshaw.github.io/PyPCAPKit/)**.

The PyPCAPKit project is an open source Python program focused on network packet
parsing and analysis, which works as a comprehensive
[PCAP](https://en.wikipedia.org/wiki/Pcap) file extraction, construction and
analysis library, with [DictDumper](https://github.com/JarryShaw/DictDumper) as
its formatted output dumper.

Unlike popular PCAP file extractors such as [Scapy](https://scapy.net),
[DPKT](https://dpkt.readthedocs.io) and [PyShark](https://kiminewt.github.io/pyshark),
`pcapkit` is designed to be much more comprehensive: it reports more detailed
information about each packet, and offers a more *Pythonic* interface to work
with it. When that depth is not what you need, the same interface will also drive
six third-party extraction engines instead.

The whole project supports **Python 3.6** or later.

## Installation

```shell
pip install pypcapkit
```

Or from a clone, for the latest version and for development:

```shell
git clone https://github.com/JarryShaw/PyPCAPKit.git
cd PyPCAPKit
pip install -e .
```

The extraction engines and plug-ins are optional extras:

```shell
pip install pypcapkit[DPKT]         # or Scapy, PyShark, PyPCAPFile, PyPCAP, PCAP_CT
pip install pypcapkit[crypto]       # ESP payload decryption
pip install pypcapkit[cli]          # command line interface
pip install pypcapkit[all]          # every pure-Python extra
```

Four of the engines need something beyond a `pip install` -- a `tshark` binary, a
C compiler, `libpcap` headers, or an older interpreter -- and `all` deliberately
excludes both `pypcap` and `pcap-ct`, which must never be installed together.
The [installation guide](https://jarryshaw.github.io/PyPCAPKit/#installation)
covers every constraint and the reason for it, and `pcapkit` enforces each one in
code: asking for an engine that cannot run in the current environment warns with
the actual cause and falls back to `pcapkit`'s own parser.

## Usage

```python
>>> import pcapkit
>>> extraction = pcapkit.extract('in.pcap', nofile=True)
>>> len(extraction.frame)
6
>>> frame = extraction.frame[0]
>>> str(frame.protochain)
'Ethernet:IPv6:IPv6_ICMP'
>>> frame.info.time
datetime.datetime(2017, 11, 19, 15, 49, 5, 471719, tzinfo=datetime.timezone.utc)
>>> frame.payload.payload.src
IPv6Address('fe80::a6:87f9:2793:16ee')
```

The output above is from `examples/captures/in.pcap`, which is committed, so it
is reproducible from a clone.

Reassembly, TCP flow tracing and a different engine are all keyword arguments on
the same call:

```python
>>> scapy = pcapkit.extract('in.pcap', nofile=True, engine='scapy')
>>> reasm = pcapkit.extract('in.pcap', nofile=True, reassembly=True, ipv6=True)
>>> flows = pcapkit.extract('in.pcap', nofile=True, trace=True, tcp=True)
>>> len(flows.trace)
3
```

More worked examples, including the command line interface, are in
[How to ...](https://jarryshaw.github.io/PyPCAPKit/demo.html).

## Documentation

The [official documentation](https://jarryshaw.github.io/PyPCAPKit/) is the
reference for everything below. The pages worth knowing by name:

| Page | What is in it |
|---|---|
| [API reference](https://jarryshaw.github.io/PyPCAPKit/pcapkit/index.html) | Every module, protocol and constant |
| [Module structure](https://jarryshaw.github.io/PyPCAPKit/#module-structure) | What each of the eight subpackages is for |
| [Engine comparison](https://jarryshaw.github.io/PyPCAPKit/#engine-comparison) | Which engines exist, which Python versions they run on, and measured speed per packet |
| [Engine support](https://jarryshaw.github.io/PyPCAPKit/pcapkit/foundation/engines/index.html) | What each engine does *not* support, and how the gap is surfaced |
| [Installation](https://jarryshaw.github.io/PyPCAPKit/#installation) | Extras, engine prerequisites and the local development setup |
| [Testing](https://jarryshaw.github.io/PyPCAPKit/contributing/testing.html) | Running the suite, and the sample captures it needs |
| [How to ...](https://jarryshaw.github.io/PyPCAPKit/demo.html) | Worked examples, library and CLI |
| [Extensions](https://jarryshaw.github.io/PyPCAPKit/ext.html) | Registering your own protocols, engines and dumpers |

Release history is in [CHANGELOG.md](CHANGELOG.md), and contribution guidelines
are in [CONTRIBUTING.md](CONTRIBUTING.md).
