netaddr

netaddr is a mature, dependency-free Python library for working with network addresses. It provides unified classes for IPv4 and IPv6 addresses, subnets, and ranges, plus MAC/EUI-48 and EUI-64 hardware addresses, so the same API handles arithmetic, sorting, iteration, and set operations across every address family without family-specific branching in caller code.

Beyond basic parsing, netaddr bundles offline IEEE OUI/IAB vendor-lookup tables and IANA address-block data, and understands a wide range of real-world notations — CIDR, arbitrary IP ranges, nmap-style ranges, and glob patterns, as well as Cisco, Unix, and PostgreSQL MAC address formats. It ships as a zero-dependency, pure Python 3.7+ package with an optional interactive CLI shell for ad hoc address exploration.

What You Get

• Unified IPAddress/IPNetwork/IPRange classes that share the same API across IPv4 and IPv6
• EUI and OUI/IAB classes for MAC address parsing and IEEE vendor lookups, with the registry data bundled offline
• Set-style CIDR operations — cidr_merge, cidr_exclude, spanning_cidr, and IPSet for aggregating and comparing address ranges
• Support for niche address notations: nmap ranges, glob-style ranges, and Cisco/Unix/PostgreSQL MAC formats
• A bundled interactive shell (netaddr CLI) for exploring addresses without writing a script

Common Use Cases

• Validating and normalizing user-supplied IP addresses or CIDR blocks before storing them
• Aggregating firewall or ACL rules by merging overlapping/adjacent CIDR blocks
• Looking up the hardware vendor of a MAC address from its OUI without a network call
• Generating or parsing IPv6 addresses derived from EUI-64 identifiers for network provisioning tooling

Under The Hood

Architecture netaddr’s core organizes IP and EUI/MAC address handling into layered modules: netaddr/core.py defines shared primitives (exceptions AddrFormatError/AddrConversionError/NotRegisteredError, a Subscriber/Publisher observer pattern, DictDotLookup), netaddr/strategy/{ipv4,ipv6,eui48,eui64}.py implement per-address-family low-level parsing/formatting strategies (validation, bit/word conversion, socket-based inet_aton/inet_pton with fbsocket.py as a pure-Python Windows/cygwin fallback), and netaddr/ip/init.py builds the public BaseIP/IPAddress/IPNetwork/IPRange classes atop those strategies via a pluggable _module attribute so the same class logic works across IPv4 and IPv6 by swapping strategy modules. netaddr/eui/init.py similarly builds EUI/OUI/IAB classes on top of the eui48/eui64 strategies, with static OUI/IAB registry data bundled and looked up via index files for IEEE organizational lookups. netaddr/ip/sets.py, glob.py, iana.py, and nmap.py layer higher-level range/set/CIDR operations on top of the base classes. This is a modular, layered design — shared exceptions and an observer pattern at the bottom, per-family strategy modules for encode/decode logic in the middle, and public address/network classes plus range/set utilities on top — with the main risk being that changing the core BaseIP value/module contract would ripple through every strategy module and derived operation.

Tech Stack Pure Python 3.7+, zero runtime dependencies — the library relies solely on the standard library (socket.inet_aton/inet_pton, struct, pprint), with fbsocket.py providing a hand-written pure-Python fallback of inet_pton/inet_ntop for Windows/cygwin where the stdlib implementation is unreliable. The build system is standard setuptools with a PEP 517/518 pyproject.toml and a dynamically resolved version pulled from netaddr.version, packaged for PyPI with a console-script entry point (netaddr.cli:main) for an optional interactive shell. Documentation is built with Sphinx and hosted on Read the Docs.

Code Quality The test suite spans dozens of modules covering IP, EUI, glob, IANA, nmap, and strategy-level behavior, and pytest is configured with —doctest-modules and —doctest-glob=“*.rst” so docstrings and the README/USAGE docs are themselves executed as tests — an unusually thorough documentation-as-test approach. Error handling is explicit via a small custom exception hierarchy (AddrFormatError, AddrConversionError, NotRegisteredError) rather than generic exceptions. Naming is consistent snake_case, with internal imports aliased with a leading underscore to keep the public namespace clean. There are no static type hints or mypy checking anywhere in the codebase. Ruff enforces lint/format rules, and CI runs the full test matrix with coverage uploaded to Codecov on every push and pull request.

API Design netaddr’s core value is a single, Pythonic set of classes that transparently span IPv4, IPv6, and MAC address families through a common strategy-module abstraction, so the same arithmetic, comparison, iteration, and slicing operators work regardless of address family. It bundles offline IEEE OUI/IAB registry data and IANA allocation tables so MAC-vendor and IP-block lookups work without any network call, and it supports niche format parsing — nmap ranges, glob-style ranges, and Cisco/Unix/PostgreSQL MAC notations — well beyond what the standard library’s ipaddress module covers. Getting started requires only a pip install with no configuration.