pattrie 0.5.1

Fast IP prefix lookup library with Rust backend

Pattrie

Fast IP prefix trie for Python with a Rust backend. Supports longest-prefix match (LPM) lookups on IPv4 and IPv6 networks.

Built with PyO3 and the prefix-trie crate. Inspired by pytricia.

Installation

pip install pattrie

Usage

import pattrie

t = pattrie.Pattrie()
t["10.0.0.0/8"] = "rfc1918"
t["10.1.0.0/16"] = "internal"

t["10.1.2.3"]          # "internal"      (LPM)
t["10.2.0.1"]          # "rfc1918"       (LPM)
"10.1.2.3" in t        # True
t.get_key("10.1.2.3")  # "10.1.0.0/16"
t.get("192.0.2.1")     # None

Keys can be strings, ipaddress.IPv4Address, IPv4Network, IPv6Address, or IPv6Network. Keys may also be raw address bytes — a bytes/bytearray/memoryview of length 4 (IPv4) or 16 (IPv6), or a (bytes, prefixlen) tuple — useful for packet processing where the address is already in bytes.

IPv6

import socket
import pattrie

t = pattrie.Pattrie(128, socket.AF_INET6)
t["2001:db8::/32"] = "documentation"
t["fe80::/10"] = "link-local"

t["fe80::1"]  # "link-local"

Concurrent reads with freeze()

After freeze(), read operations release the GIL, allowing true parallel lookups from multiple threads:

t = pattrie.Pattrie()
# ... populate ...
t.freeze()  # trie becomes read-only; reads release the GIL

# Safe to call from many threads simultaneously
value = t["10.1.2.3"]

t.thaw()    # restore mutability

API

class Pattrie:
    def __init__(self, maxbits: int = 32, family: int = socket.AF_INET) -> None: ...

    # Insert
    def insert(self, prefix: str | IPv4Network | IPv6Network, value: object) -> None: ...
    def insert(self, addr: str | IPv4Address | IPv6Address, prefixlen: int, value: object) -> None: ...
    def __setitem__(self, key: str | IPv4Network | IPv6Network, value: object) -> None: ...

    # Lookup (LPM)
    def __getitem__(self, key: str | IPv4Address | IPv6Address | IPv4Network | IPv6Network) -> object: ...
    def get(self, key, default=None) -> object: ...
    def get_key(self, key) -> str | None: ...
    def __contains__(self, key) -> bool: ...

    # Exact match
    def has_key(self, key: str | IPv4Network | IPv6Network) -> bool: ...

    # Set-style (value-less)
    def add(self, key: str | IPv4Network | IPv6Network) -> None: ...
    def discard(self, key: str | IPv4Network | IPv6Network) -> None: ...

    # Delete
    def __delitem__(self, key: str | IPv4Network | IPv6Network) -> None: ...
    def delete(self, key: str | IPv4Network | IPv6Network) -> None: ...

    # Iteration
    def __iter__(self) -> Iterator[str]: ...
    def keys(self) -> list[str]: ...
    def __len__(self) -> int: ...

    # Concurrency
    def freeze(self) -> None: ...
    def thaw(self) -> None: ...

Performance

See benches/README.md for methodology and numbers.

License

MIT — see LICENSE.