whois

python-whois (published on PyPI as python-whois, imported as whois) queries WHOIS servers directly over their native socket protocol instead of routing lookups through a third-party web API, then normalizes the raw registry text into structured Python objects. The library ships dedicated parser classes for more than 100 top-level domains, so registrar-specific field naming and formatting differences are handled internally rather than left to the caller.

Beyond domain lookups it exposes IP WHOIS support, punycode conversion for internationalized domains, and an option to fall back to the system whois binary when a native socket query is blocked or throttled. Datetime fields are parsed with python-dateutil into real datetime objects, and the whole result behaves like a Python dict, making it easy to serialize to JSON for domain-expiry monitoring, brand-protection tooling, or registration research scripts.

What You Get

• A native socket-based WHOIS client (NICClient) that queries registry servers directly, without going through a third-party web API
• Over 100 TLD-specific parser classes (WhoisCom, WhoisOrg, WhoisIo, and dozens more) that normalize each registry’s raw text into a common field set
• Automatic datetime parsing via python-dateutil for creation_date, expiration_date, and updated_date fields, plus a large table of known raw date formats
• Optional fallback to the system whois command-line binary, and IPv4/IPv6-aware domain extraction with punycode conversion for internationalized domains

Common Use Cases

• Checking domain availability or expiration dates before a purchase or renewal
• Building automated domain-expiry monitoring and renewal-reminder tools
• Extracting registrant and registrar metadata for brand-protection or abuse-investigation workflows
• Bulk domain research and TLD-format normalization inside a larger data pipeline

Under The Hood

Architecture The library is a small, layered module: whois/whois.py implements NICClient, a raw-socket client that speaks the WHOIS protocol (port 43) directly to the correct registry server for a given TLD; whois/parser.py defines a WhoisEntry base class plus over 100 TLD-specific subclasses whose load() dispatch (a long TLD-suffix if/elif chain) picks the right parser for a domain’s raw text and maps registry-specific field names onto a common schema; and whois/__init__.py exposes the public whois() function that ties socket lookup (or a system-binary fallback) and parsing together, plus IP-vs-domain detection and punycode handling. It’s a straightforward procedural-and-OO design rather than a plugin or DI-based one — the main thing that breaks if the core WhoisEntry.load() dispatch changes is TLD coverage, not the client itself.

Tech Stack Pure-Python with a minimal dependency footprint: only python-dateutil is required (per requirements.txt), used for date parsing in parser.py. Everything else — sockets, regex, ipaddress, subprocess for the CLI fallback — comes from the standard library. Packaging still uses a classic setup.py/setuptools layout rather than a pyproject.toml, and the library targets Python 3.9+ with from __future__ import annotations and modern type hints.

Code Quality Tests live under test/ (test_parser.py, test_query.py, test_nicclient.py, test_ipv6.py, test_main.py) using unittest, with sample WHOIS responses under test/samples/ used to exercise the TLD parsers. CI (GitHub Actions) runs flake8 and pytest across Python 3.9 through 3.13. There’s no static type-checker (mypy) wired into CI despite the type hints, and the field-extraction logic leans heavily on regex, so correctness for a new or changed TLD format depends on test coverage for that specific TLD.

API Design The public surface is deliberately small: whois.whois(url) returns a dict-like WhoisEntry with parsed, typed fields, and inc_raw=True exposes the original response text when a caller needs it. Getting started requires no configuration or API key — just pip install python-whois and one function call — and the command=True fallback to the system whois binary gives an escape hatch without changing the call signature. Documentation is limited to a single README example rather than a dedicated docs site, but the API itself has almost no boilerplate.