tld

tld is a Python library for extracting the top-level domain (TLD) from a URL, using the authoritative Public Suffix List as its data source. Unlike naive last-dot-splitting, it correctly handles multi-part public suffixes such as co.uk or com.au, and can return the result either as a plain string or as a structured object exposing the subdomain, domain, TLD, fully-qualified domain (fld), and parsed URL components separately.

It supports both silent failure and exception-raising modes for malformed or unknown TLDs, and includes helpers for updating the bundled Public Suffix List data and registering custom/private TLDs.

What You Get

• get_tld() for extracting just the TLD string from a URL, with fail_silently support for graceful handling of unknown/invalid domains
• Structured result objects (as_object=True) exposing subdomain, domain, TLD, fully-qualified domain name, and the parsed URL separately
• Multi-part public-suffix awareness (e.g. co.uk, com.au) sourced from the official Public Suffix List rather than naive dot-splitting
• Utilities for updating the bundled TLD data set and registering additional custom or private TLDs
• A documented, tested exception hierarchy for distinguishing invalid hostnames, unknown TLDs, and other parse failures

Common Use Cases

• Grouping or deduplicating analytics/log data by registrable domain (e.g. treating www.example.co.uk and shop.example.co.uk as the same site)
• Validating that a user-submitted URL or email domain has a real, publicly recognized TLD before accepting it in a form
• Building domain-reputation or security tooling that needs to correctly separate subdomain from domain across multi-part suffixes
• Normalizing scraped or crawled URLs down to their registrable domain for site-level aggregation

Under The Hood

Architecture The library centers on src/tld/base.py (the core get_tld/parsing logic), src/tld/trie.py (a trie built from the Public Suffix List for efficient longest-match suffix lookup), src/tld/result.py (the structured result object), src/tld/registry.py and conf.py (loading and registering the TLD data set, including custom/private suffixes), and src/tld/exceptions.py for the typed error hierarchy — a layout that keeps suffix-matching, configuration, and result-formatting concerns separate.

Tech Stack It’s a dependency-light, pure-Python 3.9+ library with no required third-party runtime dependencies, using setup.cfg/pyproject.toml for packaging and tox for multi-version testing; it ships its own bundled snapshot of Mozilla’s Public Suffix List data as package data, refreshable via included update utilities.

Code Quality The project has a dedicated src/tld/tests/ suite (with its own res/ test-data fixtures) plus a repo-root conftest.py/runtests.py, GitHub Actions test/build workflows, and Coveralls coverage reporting; a benchmarks/ directory and jupyter/ example notebook indicate attention to both performance and documented usage, though GitHub activity has been low over the past year relative to the project’s age.

API Design The two-mode API (get_tld() returning a string vs. as_object=True returning a rich result) keeps the common case a one-liner while still exposing the full subdomain/domain/tld/fld breakdown when needed, and fail_silently gives callers an explicit choice between exception-based and value-based error handling.