pcapml 0.1.0__py3-none-any.whl

pcapml/__init__.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""pcapml: read pcapml-labeled network traces into pandas DataFrames.
+
+Quick start
+-----------
+>>> import pcapml
+>>> df = pcapml.read_pcapml("dataset.pcapng")
+>>> df[["timestamp", "sample_id", "label", "src_ip", "dst_ip", "proto"]].head()
+
+Group by sample:
+>>> for sample in pcapml.samples("dataset.pcapng"):
+...     print(sample.sample_id, sample.label, len(sample))
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._pcapng import Interface, Packet, iter_packets
+from .reader import (
+    COLUMNS,
+    Sample,
+    parse_comment,
+    read,
+    read_pcapml,
+    sampler,
+    samples,
+)
+
+try:
+    # Single source of truth: the version declared in pyproject.toml.
+    __version__ = version("pcapml")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "read_pcapml",
+    "read",
+    "samples",
+    "sampler",
+    "Sample",
+    "parse_comment",
+    "iter_packets",
+    "Packet",
+    "Interface",
+    "COLUMNS",
+    "__version__",
+]

pcapml/_decode.py

@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal pure-Python L3/L4 header decoding.
+
+Just enough to populate the convenience columns (addresses, protocol, ports).
+The full packet bytes are always preserved in the DataFrame for anyone who
+wants a real dissector (dpkt, scapy, ...).
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+from typing import Dict, Optional, Tuple
+
+# Selected link types (https://www.tcpdump.org/linktypes.html).
+LINKTYPE_ETHERNET = 1
+LINKTYPE_RAW = 101
+LINKTYPE_LINUX_SLL = 113
+# Some tools emit 12/14 for "raw IP"; treat them as raw too.
+_RAW_IP_LINKTYPES = frozenset({LINKTYPE_RAW, 12, 14})
+
+ETHERTYPE_IPV4 = 0x0800
+ETHERTYPE_IPV6 = 0x86DD
+_VLAN_ETHERTYPES = frozenset({0x8100, 0x88A8, 0x9100})
+
+IP_PROTO_NAMES: Dict[int, str] = {
+    1: "ICMP",
+    2: "IGMP",
+    6: "TCP",
+    17: "UDP",
+    41: "IPv6",
+    47: "GRE",
+    50: "ESP",
+    51: "AH",
+    58: "IPv6-ICMP",
+    89: "OSPF",
+    132: "SCTP",
+}
+
+# IPv6 extension headers we skip over to reach the transport header.
+_IPV6_EXT_HEADERS = frozenset({0, 43, 60})  # hop-by-hop, routing, dest-options
+
+_EMPTY: Dict[str, Optional[object]] = {
+    "src_ip": None,
+    "dst_ip": None,
+    "proto": None,
+    "src_port": None,
+    "dst_port": None,
+}
+
+
+def decode(data: bytes, link_type: int) -> Dict[str, Optional[object]]:
+    """Decode L3/L4 fields from a raw packet. Never raises; unknowns are None."""
+    try:
+        payload, ethertype = _strip_l2(data, link_type)
+        if payload is None:
+            return dict(_EMPTY)
+        if ethertype == ETHERTYPE_IPV4:
+            return _decode_ipv4(payload)
+        if ethertype == ETHERTYPE_IPV6:
+            return _decode_ipv6(payload)
+    except Exception:
+        pass
+    return dict(_EMPTY)
+
+
+def _strip_l2(data: bytes, link_type: int) -> Tuple[Optional[bytes], Optional[int]]:
+    """Return (l3_payload, ethertype), stripping any link-layer header."""
+    if link_type == LINKTYPE_ETHERNET:
+        if len(data) < 14:
+            return None, None
+        ethertype = struct.unpack_from("!H", data, 12)[0]
+        off = 14
+        while ethertype in _VLAN_ETHERTYPES and len(data) >= off + 4:
+            ethertype = struct.unpack_from("!H", data, off + 2)[0]
+            off += 4
+        return data[off:], ethertype
+
+    if link_type == LINKTYPE_LINUX_SLL:
+        if len(data) < 16:
+            return None, None
+        return data[16:], struct.unpack_from("!H", data, 14)[0]
+
+    if link_type in _RAW_IP_LINKTYPES or link_type == 0:
+        return _raw_ip(data)
+
+    return None, None
+
+
+def _raw_ip(data: bytes) -> Tuple[Optional[bytes], Optional[int]]:
+    """Infer IPv4 vs IPv6 from the version nibble of a raw IP packet."""
+    if not data:
+        return None, None
+    version = data[0] >> 4
+    if version == 4:
+        return data, ETHERTYPE_IPV4
+    if version == 6:
+        return data, ETHERTYPE_IPV6
+    return None, None
+
+
+def _ip_str(raw: bytes, family: int) -> Optional[str]:
+    try:
+        return socket.inet_ntop(family, raw)
+    except (OSError, ValueError):
+        return None
+
+
+def _ports(payload: bytes, off: int, proto: int) -> Tuple[Optional[int], Optional[int]]:
+    if proto in (6, 17, 132) and len(payload) >= off + 4:  # TCP / UDP / SCTP
+        src, dst = struct.unpack_from("!HH", payload, off)
+        return src, dst
+    return None, None
+
+
+def _result(src_ip, dst_ip, proto, src_port, dst_port) -> Dict[str, Optional[object]]:
+    return {
+        "src_ip": src_ip,
+        "dst_ip": dst_ip,
+        "proto": IP_PROTO_NAMES.get(proto, str(proto)) if proto is not None else None,
+        "src_port": src_port,
+        "dst_port": dst_port,
+    }
+
+
+def _decode_ipv4(p: bytes) -> Dict[str, Optional[object]]:
+    if len(p) < 20:
+        return dict(_EMPTY)
+    ihl = (p[0] & 0x0F) * 4
+    proto = p[9]
+    src_ip = _ip_str(p[12:16], socket.AF_INET)
+    dst_ip = _ip_str(p[16:20], socket.AF_INET)
+    src_port, dst_port = _ports(p, ihl, proto)
+    return _result(src_ip, dst_ip, proto, src_port, dst_port)
+
+
+def _decode_ipv6(p: bytes) -> Dict[str, Optional[object]]:
+    if len(p) < 40:
+        return dict(_EMPTY)
+    next_hdr = p[6]
+    src_ip = _ip_str(p[8:24], socket.AF_INET6)
+    dst_ip = _ip_str(p[24:40], socket.AF_INET6)
+
+    off = 40
+    # Walk extension headers (each is 8-byte aligned via hdr_ext_len) to the
+    # transport header. Fragment headers (44) are a fixed 8 bytes.
+    while next_hdr in _IPV6_EXT_HEADERS or next_hdr == 44:
+        if off + 2 > len(p):
+            return _result(src_ip, dst_ip, None, None, None)
+        ext_next = p[off]
+        ext_len = 8 if next_hdr == 44 else (p[off + 1] + 1) * 8
+        next_hdr = ext_next
+        off += ext_len
+
+    src_port, dst_port = _ports(p, off, next_hdr)
+    return _result(src_ip, dst_ip, next_hdr, src_port, dst_port)

pcapml/_pcapng.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pure-Python streaming reader for the pcapng blocks pcapml emits.
+
+This module knows nothing about pcapml labels; it just yields packets with the
+raw per-packet comment string. Higher layers parse the comment. Only the block
+types pcapml writes are interpreted (SHB, IDB, EPB); anything else is skipped.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import BinaryIO, Iterator, List, Optional, Union
+
+# Block type codes.
+SECTION_HEADER = 0x0A0D0D0A
+INTERFACE_DESC = 0x00000001
+ENHANCED_PACKET = 0x00000006
+BYTE_ORDER_MAGIC = 0x1A2B3C4D
+
+# Option codes.
+OPT_END = 0
+OPT_COMMENT = 1
+IDB_OPT_TSRESOL = 9
+
+# The 4 bytes of the Section Header Block type are byte-order independent, which
+# is exactly how a reader bootstraps endianness for the rest of the section.
+_SHB_MAGIC_BYTES = b"\x0a\x0d\x0d\x0a"
+
+
+@dataclass
+class Interface:
+    """An Interface Description Block: link type and timestamp resolution."""
+
+    link_type: int
+    snap_len: int
+    ts_resol: float = 1e-6  # seconds per timestamp tick (pcapng default: microsec)
+
+
+@dataclass
+class Packet:
+    """One Enhanced Packet Block with its pcapml comment."""
+
+    interface_id: int
+    ts_ticks: int
+    cap_len: int
+    orig_len: int
+    data: bytes
+    comment: str
+    link_type: int
+    ts_resol: float
+
+    @property
+    def timestamp(self) -> float:
+        """Capture time as POSIX seconds (float)."""
+        return self.ts_ticks * self.ts_resol
+
+    @property
+    def ts_nanos(self) -> int:
+        """Capture time as integer nanoseconds (loss-free for ns/us/ms resolutions)."""
+        return int(round(self.ts_ticks * self.ts_resol * 1e9))
+
+
+def _read_exact(f: BinaryIO, n: int) -> Optional[bytes]:
+    """Read exactly n bytes or return None at a clean EOF."""
+    chunks = []
+    remaining = n
+    while remaining > 0:
+        chunk = f.read(remaining)
+        if not chunk:
+            return None
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def _ts_resol_from_byte(v: int) -> float:
+    """Decode an if_tsresol option byte into seconds-per-tick."""
+    if v & 0x80:
+        return 2.0 ** -(v & 0x7F)
+    return 10.0 ** -v
+
+
+def _iter_options(body: bytes, off: int, le: str):
+    """Yield (code, value_bytes) for the options region starting at off."""
+    n = len(body)
+    while off + 4 <= n:
+        code, length = struct.unpack_from(le + "HH", body, off)
+        if code == OPT_END:
+            break
+        start = off + 4
+        end = start + length
+        if end > n:
+            break
+        yield code, body[start:end]
+        off = end + ((4 - length % 4) % 4)  # options are padded to 32 bits
+
+
+def iter_packets(source: Union[str, BinaryIO]) -> Iterator[Packet]:
+    """Yield :class:`Packet` for every Enhanced Packet Block in a pcapng stream.
+
+    ``source`` may be a filesystem path or an already-open binary file object.
+    """
+    if isinstance(source, str):
+        with open(source, "rb") as f:
+            yield from _iter_packets(f)
+    else:
+        yield from _iter_packets(source)
+
+
+def _iter_packets(f: BinaryIO) -> Iterator[Packet]:
+    le = "<"
+    interfaces: List[Interface] = []
+
+    while True:
+        type_bytes = _read_exact(f, 4)
+        if type_bytes is None:
+            return
+
+        if type_bytes == _SHB_MAGIC_BYTES:
+            # Section Header Block: re-establish endianness and reset interfaces.
+            len_bytes = _read_exact(f, 4)
+            magic_bytes = _read_exact(f, 4)
+            if len_bytes is None or magic_bytes is None:
+                return
+            le = "<" if struct.unpack("<I", magic_bytes)[0] == BYTE_ORDER_MAGIC else ">"
+            block_len = struct.unpack(le + "I", len_bytes)[0]
+            # 12 bytes already consumed (type + length + magic).
+            if _read_exact(f, block_len - 12) is None:
+                return
+            interfaces = []
+            continue
+
+        len_bytes = _read_exact(f, 4)
+        if len_bytes is None:
+            return
+        block_type = struct.unpack(le + "I", type_bytes)[0]
+        block_len = struct.unpack(le + "I", len_bytes)[0]
+        if block_len < 12:
+            return  # corrupt: length must cover type+length+trailer
+        rest = _read_exact(f, block_len - 8)
+        if rest is None:
+            return
+        body = rest[:-4]  # drop the trailing redundant block length
+
+        if block_type == INTERFACE_DESC:
+            interfaces.append(_parse_idb(body, le))
+        elif block_type == ENHANCED_PACKET:
+            pkt = _parse_epb(body, le, interfaces)
+            if pkt is not None:
+                yield pkt
+        # Other block types (SPB, NRB, ISB, ...) carry no pcapml labels: skip.
+
+
+def _parse_idb(body: bytes, le: str) -> Interface:
+    link_type, _reserved, snap_len = struct.unpack_from(le + "HHI", body, 0)
+    ts_resol = 1e-6
+    for code, val in _iter_options(body, 8, le):
+        if code == IDB_OPT_TSRESOL and val:
+            ts_resol = _ts_resol_from_byte(val[0])
+    return Interface(link_type=link_type, snap_len=snap_len, ts_resol=ts_resol)
+
+
+def _parse_epb(body: bytes, le: str, interfaces: List[Interface]) -> Optional[Packet]:
+    if len(body) < 20:
+        return None
+    iface_id, ts_high, ts_low, cap_len, orig_len = struct.unpack_from(le + "IIIII", body, 0)
+    data = body[20 : 20 + cap_len]
+    if len(data) < cap_len:
+        return None
+
+    opt_off = 20 + cap_len + ((4 - cap_len % 4) % 4)
+    comment = ""
+    for code, val in _iter_options(body, opt_off, le):
+        if code == OPT_COMMENT:
+            comment = val.rstrip(b"\x00").decode("utf-8", "replace")
+            break
+
+    if 0 <= iface_id < len(interfaces):
+        iface = interfaces[iface_id]
+    else:
+        iface = Interface(link_type=0, snap_len=0)
+
+    return Packet(
+        interface_id=iface_id,
+        ts_ticks=(ts_high << 32) | ts_low,
+        cap_len=cap_len,
+        orig_len=orig_len,
+        data=data,
+        comment=comment,
+        link_type=iface.link_type,
+        ts_resol=iface.ts_resol,
+    )

pcapml/reader.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: Apache-2.0
+"""High-level pcapml reader: pcapng -> pandas DataFrame and per-sample grouping."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterator, List, Optional, Tuple, Union
+
+import pandas as pd
+
+from . import _decode
+from ._pcapng import Packet, iter_packets
+
+# Column order for the per-packet DataFrame.
+COLUMNS = [
+    "timestamp",
+    "sample_id",
+    "label",
+    "direction",
+    "dst",
+    "src_ip",
+    "dst_ip",
+    "proto",
+    "src_port",
+    "dst_port",
+    "length",
+    "raw",
+]
+
+# Comment keys already surfaced as dedicated core columns. Any *other* key found
+# in a comment is promoted to its own column, named after the key.
+_CORE_KEYS = frozenset({"s", "proc", "label", "dir", "d", "dst"})
+
+
+def parse_comment(comment: str) -> Tuple[Optional[str], Optional[str], Optional[str], Optional[str], Dict[str, str]]:
+    """Parse a pcapml EPB comment into (sample_id, label, direction, dst, metadata).
+
+    Handles both the keyed form (``s=0,proc=curl,dir=lan2wan,dst=example.com``)
+    and the legacy positional form (``<sample_id>,<label>``). ``metadata`` holds
+    every ``key=value`` pair found, verbatim.
+    """
+    meta: Dict[str, str] = {}
+    positional: List[str] = []
+    if comment:
+        for field in comment.split(","):
+            key, sep, value = field.partition("=")
+            if sep:
+                meta[key] = value
+            else:
+                positional.append(field)
+
+    sample_id = meta.get("s")
+    if sample_id is None and positional:
+        sample_id = positional[0]
+
+    label = meta.get("proc") or meta.get("label")
+    if label is None and len(positional) > 1:
+        label = positional[1]
+
+    direction = meta.get("dir") or meta.get("d")
+    dst = meta.get("dst")
+
+    return sample_id, label, direction, dst, meta
+
+
+def _row(pkt: Packet) -> dict:
+    sample_id, label, direction, dst, meta = parse_comment(pkt.comment)
+    decoded = _decode.decode(pkt.data, pkt.link_type)
+    row = {
+        "timestamp": pkt.ts_nanos,
+        "sample_id": sample_id,
+        "label": label,
+        "direction": direction,
+        "dst": dst,
+        "src_ip": decoded["src_ip"],
+        "dst_ip": decoded["dst_ip"],
+        "proto": decoded["proto"],
+        "src_port": decoded["src_port"],
+        "dst_port": decoded["dst_port"],
+        "length": pkt.orig_len,
+        "raw": pkt.data,
+    }
+    # Promote any non-core comment key to its own column. If a key would clash
+    # with a built-in column, prefix it with "meta_" rather than clobbering.
+    for key, value in meta.items():
+        if key in _CORE_KEYS:
+            continue
+        col = key if key not in row else "meta_" + key
+        row[col] = value
+    return row
+
+
+def _finalize(df: pd.DataFrame) -> pd.DataFrame:
+    """Apply consistent dtypes to a freshly built packet DataFrame.
+
+    Core columns get fixed dtypes and a stable order; any extra columns
+    (promoted from arbitrary comment keys) follow, typed as strings.
+    """
+    if df.empty:
+        df = pd.DataFrame({c: pd.Series(dtype="object") for c in COLUMNS})
+    for col in COLUMNS:
+        if col not in df.columns:
+            df[col] = pd.NA
+    extra_cols = [c for c in df.columns if c not in COLUMNS]
+    df = df[COLUMNS + extra_cols]
+
+    df["timestamp"] = pd.to_datetime(df["timestamp"], unit="ns", utc=True)
+    for col in ("sample_id", "label", "direction", "dst", "src_ip", "dst_ip", "proto"):
+        df[col] = df[col].astype("string")
+    for col in ("src_port", "dst_port", "length"):
+        df[col] = df[col].astype("Int64")
+    for col in extra_cols:
+        df[col] = df[col].astype("string")
+    return df
+
+
+def read_pcapml(source: Union[str], include_raw: bool = True) -> pd.DataFrame:
+    """Read a pcapml-labeled pcapng file into a pandas DataFrame, one row per packet.
+
+    Parameters
+    ----------
+    source:
+        Path to a ``.pcapng`` file produced by pcapml.
+    include_raw:
+        Keep the full packet bytes in the ``raw`` column (default ``True``).
+        Set ``False`` to drop it and save memory.
+    """
+    df = _finalize(pd.DataFrame([_row(p) for p in iter_packets(source)]))
+    if not include_raw:
+        df = df.drop(columns=["raw"])
+    return df
+
+
+# Backwards/ergonomic alias.
+read = read_pcapml
+
+
+@dataclass
+class Sample:
+    """All packets that share one sample ID, plus that sample's metadata."""
+
+    sample_id: Optional[str]
+    label: Optional[str]
+    metadata: Dict[str, str]
+    df: pd.DataFrame
+
+    # Aliases matching the README's sampler() examples.
+    @property
+    def sid(self) -> Optional[str]:
+        return self.sample_id
+
+    @property
+    def packets(self) -> pd.DataFrame:
+        return self.df
+
+    def __len__(self) -> int:
+        return len(self.df)
+
+
+def samples(source: Union[str]) -> Iterator[Sample]:
+    """Iterate over samples, grouping consecutive packets by sample ID.
+
+    pcapml writes (and its ``sort`` subcommand guarantees) that packets of a
+    sample are contiguous, so grouping is streaming and order-preserving.
+    """
+    current_id: Optional[str] = None
+    rows: List[dict] = []
+    meta: Dict[str, str] = {}
+    label: Optional[str] = None
+    have_group = False
+
+    for pkt in iter_packets(source):
+        sample_id, lbl, _direction, _dst, pkt_meta = parse_comment(pkt.comment)
+        if not have_group:
+            current_id, label, meta, have_group = sample_id, lbl, pkt_meta, True
+        elif sample_id != current_id:
+            yield Sample(current_id, label, meta, _finalize(pd.DataFrame(rows)))
+            rows = []
+            current_id, label, meta = sample_id, lbl, pkt_meta
+        rows.append(_row(pkt))
+
+    if have_group:
+        yield Sample(current_id, label, meta, _finalize(pd.DataFrame(rows)))
+
+
+# README-compatible alias.
+sampler = samples

pcapml-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pcapml
+Version: 0.1.0
+Summary: Read pcapml-labeled network traces (pcapng) into pandas DataFrames. Pure Python.
+Author-email: Paul Schmitt <paul.schmitt@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/nprint/pcapml
+Project-URL: Repository, https://github.com/nprint/pcapml
+Keywords: pcap,pcapng,network,traffic,machine-learning,pandas,dataset
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# pcapml (Python)
+
+Read [pcapml](https://github.com/nprint/pcapml)-labeled network traces into
+[pandas](https://pandas.pydata.org/) DataFrames. **Pure Python** — no native
+extensions, no libpcap, no Go binary required. The only dependency is pandas.
+
+pcapml stores ground-truth labels as per-packet comments inside standard
+pcapng files. This package parses those files directly so you can go from a
+labeled capture to a tidy DataFrame in one line.
+
+## Install
+
+```bash
+pip install pcapml
+```
+
+Or from this repository:
+
+```bash
+pip install ./python
+```
+
+## Quick start
+
+```python
+import pcapml
+
+df = pcapml.read_pcapml("dataset.pcapng")
+print(df.head())
+```
+
+```
+                          timestamp sample_id label direction         dst        src_ip        dst_ip proto  src_port  dst_port  length
+2026-03-19 22:25:24.189764096+00:00         0  curl   lan2wan example.com 192.168.1.188 104.18.26.120   TCP     47954        80      60
+2026-03-19 22:25:24.195076864+00:00         0  curl   wan2lan example.com 104.18.26.120 192.168.1.188   TCP        80     47954      60
+...
+```
+
+### Columns
+
+| Column | Dtype | Description |
+|--------|-------|-------------|
+| `timestamp` | `datetime64[ns, UTC]` | Packet capture time |
+| `sample_id` | `string` | pcapml sample ID (kept as string — IDs can exceed 2⁶⁴) |
+| `label` | `string` | Sample label / process name |
+| `direction` | `string` | Direction tag if present (`lan2wan`, `wan2lan`, `e`, `i`, …) |
+| `dst` | `string` | Resolved destination domain, if any |
+| `src_ip`, `dst_ip` | `string` | L3 addresses (IPv4 or IPv6) |
+| `proto` | `string` | `TCP`, `UDP`, `ICMP`, … (or the numeric value) |
+| `src_port`, `dst_port` | `Int64` | L4 ports (nullable) |
+| `length` | `Int64` | Original on-wire packet length |
+| `raw` | `bytes` | Full captured packet bytes |
+
+**Arbitrary comment keys** are promoted automatically. The columns above are the
+fixed core schema; any other `key=value` pair in a comment becomes its own
+column named after the key (sparse keys fill with `<NA>`). For example a comment
+`s=0,proc=curl,dst=youtube.com,asn=15169` yields an extra `asn` column. If a key
+collides with a core column name it is prefixed (`meta_<key>`) instead of
+overwriting it.
+
+Pass `include_raw=False` to drop the `raw` column and save memory:
+
+```python
+df = pcapml.read_pcapml("dataset.pcapng", include_raw=False)
+```
+
+The header decoding (IPv4/IPv6 + TCP/UDP) is intentionally lightweight. The
+`raw` bytes are always available if you want a full dissector such as
+[dpkt](https://github.com/kbandla/dpkt) or [scapy](https://scapy.net/):
+
+```python
+import dpkt
+df["eth"] = df["raw"].apply(dpkt.ethernet.Ethernet)  # for Ethernet linktype
+```
+
+## Iterating by sample
+
+For ML workflows it's often handier to work one sample at a time. `samples()`
+groups consecutive packets by sample ID (pcapml writes each sample's packets
+contiguously; use `pcapml sort` first if yours aren't):
+
+```python
+for sample in pcapml.samples("dataset.pcapng"):
+    print(sample.sample_id, sample.label, len(sample))
+    sample.df          # a DataFrame of just this sample's packets
+    sample.metadata    # dict of every key=value pair from the comment
+```
+
+`Sample` also exposes `.sid` and `.packets` aliases.
+
+## Label formats
+
+Both pcapml comment encodings are supported transparently:
+
+- **Keyed** (eBPF / gateway capture): `s=0,proc=curl,dir=lan2wan,dst=example.com`
+- **Legacy positional**: `18205618432581910911,windows-10`
+
+## Lower-level access
+
+If you don't want pandas in the loop, iterate raw packets directly:
+
+```python
+from pcapml import iter_packets, parse_comment
+
+for pkt in iter_packets("dataset.pcapng"):
+    sid, label, direction, dst, meta = parse_comment(pkt.comment)
+    pkt.timestamp   # POSIX seconds (float)
+    pkt.data        # raw bytes
+    pkt.link_type   # pcapng linktype (1 = Ethernet, 101 = RAW IPv4)
+```
+
+## License
+
+Apache-2.0.

pcapml-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pcapml/__init__.py,sha256=Sz_cR0ZqNZJf5ri-OoLj5hoEIcZaZDY0jOBhfziVrhc,1069
+pcapml/_decode.py,sha256=i4W-BZ6quqWAz2S4UedAKO37TLPycY3DlLqFpQzHrkY,4789
+pcapml/_pcapng.py,sha256=mmLVAuHV6e4Z2REUQn0EiQOsEGbbjWEFV6utQ3afZJw,6080
+pcapml/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pcapml/reader.py,sha256=oqOn0GR_-3aXJE-jqhkS1LhkfE2Ifi03Aks0oamXiZ8,5825
+pcapml-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pcapml-0.1.0.dist-info/METADATA,sha256=t9K7q-RxmeNO-SCKbvlH4iM5bzBLBz_k9e_MFzdpGPk,4799
+pcapml-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pcapml-0.1.0.dist-info/top_level.txt,sha256=V_WXwO6v1GJSMHkTAAXUEssN8gts_yfeeZfymQxkTq0,7
+pcapml-0.1.0.dist-info/RECORD,,

pcapml-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pcapml-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pcapml-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pcapml