domainhack 0.2.0__py3-none-any.whl

domainhack/data/second_level.json

@@ -0,0 +1,28 @@
+{
+  "description": "Common registrable second-level public suffixes, Latin America first. Curated by hand: every entry is in the ICANN section of the Public Suffix List. Restricted zones (gob, gov, edu, mil...) are left out on purpose; some listed zones have eligibility rules (e.g. org.ar for non-profits).",
+  "source": "https://publicsuffix.org/list/public_suffix_list.dat",
+  "source_version": "2026-10-06_16-13-12_UTC (commit 4018bd98001399ebff682f401664d469787ed7eb)",
+  "registry_sources": {
+    "ar": "https://www.boletinoficial.gob.ar/detalleAviso/primera/255797/20220106"
+  },
+  "suffixes": [
+    "com.ar", "net.ar", "org.ar",
+    "com.mx", "net.mx", "org.mx",
+    "com.br", "net.br", "org.br",
+    "com.co", "net.co", "org.co",
+    "com.pe", "net.pe", "org.pe",
+    "com.uy", "net.uy", "org.uy",
+    "com.ve", "net.ve", "org.ve", "co.ve",
+    "com.ec", "net.ec", "org.ec",
+    "com.bo", "net.bo", "org.bo",
+    "com.py", "net.py", "org.py",
+    "com.gt", "com.sv", "com.hn", "com.ni", "com.pa", "com.do", "com.pr", "co.cr",
+    "co.uk", "org.uk", "me.uk",
+    "com.au", "net.au", "org.au",
+    "co.nz", "net.nz", "org.nz",
+    "co.jp", "ne.jp", "or.jp",
+    "co.in", "net.in", "org.in",
+    "co.za", "com.tr", "com.cn", "com.hk", "com.sg", "com.tw", "co.kr",
+    "com.es", "com.ph", "co.id", "com.my", "co.il", "com.ua", "com.pl"
+  ]
+}

domainhack/data/tld_presets.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "TLD presets for `domainhack name --tlds`. A list is used as is, in order (the order also picks the top TLDs for --variants). The string \"catalog\" means every TLD the registrar catalog supports, computed at run time. Suffixes the TLD type rejects (e.g. multi-label ones before they are supported) are skipped with a warning.",
+  "startup": ["com", "app", "io", "ai", "co", "dev", "so", "xyz"],
+  "latam": ["com.ar", "ar", "com.mx", "mx", "com.co", "co", "com.br", "cl", "pe"],
+  "classic": ["com", "net", "org"],
+  "all-supported": "catalog"
+}

domainhack/domain/entities.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+
+import idna
+
+from domainhack.domain.label_rules import DNS_MAX_LABEL_LENGTH, label_rule_for
+
+_LDH_LABEL = re.compile(r"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$")
+_ACE_PREFIX = "xn--"
+
+
+class InvalidLabelError(ValueError):
+    """A candidate SLD is not a label the TLD's registry could hold."""
+
+
+# Most labels a public suffix may have here: "to" (1) or "com.ar" (2).
+_MAX_SUFFIX_LABELS = 2
+
+
+def _is_ascii_letters(label: str, min_length: int, max_length: int | None = None) -> bool:
+    if not (label.isascii() and label.isalpha()) or len(label) < min_length:
+        return False
+    return max_length is None or len(label) <= max_length
+
+
+@dataclass(frozen=True)
+class TLD:
+    """A public suffix a name is registered under: ``'to'``, ``'io'``, ``'com.ar'``.
+
+    Multi-label suffixes are registrable second-level zones such as
+    ``com.ar``, ``com.mx`` or ``co.uk``. Every label is ASCII letters: the
+    last one (the real top-level domain) has 2 or more, a second-level label
+    2 or 3 (``co``, ``com``, ``net``, ``org``...). At most two labels.
+    """
+
+    suffix: str
+
+    def __post_init__(self) -> None:
+        labels = self.suffix.split(".")
+        valid = (
+            len(labels) <= _MAX_SUFFIX_LABELS
+            and _is_ascii_letters(labels[-1], 2)
+            and all(_is_ascii_letters(label, 2, 3) for label in labels[:-1])
+        )
+        if not valid:
+            raise ValueError(f"Invalid TLD suffix: {self.suffix!r}")
+
+    @property
+    def labels(self) -> tuple[str, ...]:
+        """``("com", "ar")`` for ``com.ar``; ``("to",)`` for ``to``."""
+        return tuple(self.suffix.split("."))
+
+    @property
+    def top_level(self) -> str:
+        """The real top-level domain: ``"ar"`` for ``com.ar``, ``"to"`` for ``to``."""
+        return self.labels[-1]
+
+    @property
+    def is_multi_label(self) -> bool:
+        return len(self.labels) > 1
+
+    @property
+    def joined(self) -> str:
+        """The suffix without dots, as it appears at the end of a word: ``"comar"``."""
+        return self.suffix.replace(".", "")
+
+
+def _check_ldh(ascii_label: str, original: str) -> None:
+    """RFC 5891 §4.2.3.1 / RFC 1123 syntax for an ASCII label (any length)."""
+    if not _LDH_LABEL.match(ascii_label):
+        raise InvalidLabelError(
+            f"{original!r} is not a valid label (letters, digits and inner hyphens only)"
+        )
+    if ascii_label[2:4] == "--" and not ascii_label.startswith(_ACE_PREFIX):
+        raise InvalidLabelError(f"{original!r} has '--' in positions 3-4 (reserved)")
+
+
+def to_ascii_label(label: str, tld: TLD) -> str:
+    """Validate ``label`` for ``tld`` and return its ASCII (A-label) form.
+
+    Unicode labels are NFC-normalized and converted with IDNA2008 (the
+    ``idna`` package); ``xn--`` input must be a valid A-label. IDN labels are
+    only accepted when the TLD's registry supports IDN (see ``label_rules``).
+    Raises InvalidLabelError otherwise.
+    """
+    rule = label_rule_for(tld.suffix)
+    unicode_label = unicodedata.normalize("NFC", label)
+    if unicode_label.isascii():
+        ascii_label = unicode_label
+        _check_ldh(ascii_label, label)
+        is_idn = ascii_label.startswith(_ACE_PREFIX)
+        if is_idn:
+            try:
+                unicode_label = idna.ulabel(ascii_label)
+                if idna.alabel(unicode_label).decode("ascii") != ascii_label:
+                    raise idna.IDNAError("not in canonical form")
+            except (idna.IDNAError, UnicodeError) as exc:
+                raise InvalidLabelError(f"{label!r} is not a valid A-label: {exc}") from exc
+    else:
+        is_idn = True
+        if not rule.idn:
+            raise InvalidLabelError(
+                f"{label!r} is an internationalized name and .{tld.suffix} does not accept IDN"
+            )
+        try:
+            ascii_label = idna.alabel(unicode_label).decode("ascii")
+        except (idna.IDNAError, UnicodeError) as exc:
+            raise InvalidLabelError(f"{label!r} is not a valid IDN label: {exc}") from exc
+        _check_ldh(ascii_label, label)
+
+    if is_idn and not rule.idn:
+        raise InvalidLabelError(
+            f"{label!r} is an internationalized name and .{tld.suffix} does not accept IDN"
+        )
+    if not is_idn and ascii_label.startswith(rule.forbidden_prefixes):
+        raise InvalidLabelError(f".{tld.suffix} does not accept names like {label!r}")
+    if len(unicode_label) < rule.min_length:
+        raise InvalidLabelError(
+            f".{tld.suffix} requires at least {rule.min_length} characters, got {label!r}"
+        )
+    if len(ascii_label) > min(rule.max_length, DNS_MAX_LABEL_LENGTH):
+        raise InvalidLabelError(f"{label!r} is too long for .{tld.suffix}")
+    return ascii_label
+
+
+@dataclass(frozen=True)
+class DomainHack:
+    """A word that ends with a TLD suffix, split into SLD + TLD.
+
+    Example: word='plato', tld=TLD('to') -> sld='pla', fqdn='pla.to'
+
+    Naming convention for internationalized names: ``word`` and ``sld`` keep
+    what the user wrote (lowercased, NFC), ``display`` is ``sld.tld`` in that
+    form, and ``fqdn``/``ascii_sld`` are **always ASCII** (the IDNA A-label).
+    Everything that talks to a registry or keys a cache uses ``fqdn``; only
+    human-facing output uses ``display``. For ASCII names both are equal.
+
+    Construction validates the label (LDH syntax plus the TLD's rules from
+    ``label_rules``) and raises InvalidLabelError, so an invalid name can
+    never reach a registrar adapter.
+    """
+
+    word: str
+    sld: str
+    tld: TLD
+    ascii_sld: str = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "ascii_sld", to_ascii_label(self.sld, self.tld))
+
+    @property
+    def fqdn(self) -> str:
+        """The ASCII name used for every query and cache key (A-label for IDNs)."""
+        return f"{self.ascii_sld}.{self.tld.suffix}"
+
+    @property
+    def display(self) -> str:
+        """The name as the user wrote it (U-label for IDNs), for display only."""
+        return f"{self.sld}.{self.tld.suffix}"
+
+    @property
+    def is_idn(self) -> bool:
+        return self.fqdn != self.display
+
+    @staticmethod
+    def _normalize(text: str) -> str:
+        return unicodedata.normalize("NFC", text.strip().lower())
+
+    @staticmethod
+    def from_word(word: str, tld: TLD) -> DomainHack | None:
+        """Split ``word`` into SLD + ``tld``.
+
+        A multi-label suffix matches by plain concatenation, ignoring its
+        dots: ``fotocomar`` + ``com.ar`` -> ``foto.com.ar``.
+
+        Returns None when the word does not end with the TLD suffix or leaves
+        an empty SLD; raises InvalidLabelError when it does but the SLD is
+        not a valid label for that TLD.
+        """
+        lower = DomainHack._normalize(word)
+        ending = tld.joined
+        if lower.endswith(ending) and len(lower) > len(ending):
+            sld = lower[: -len(ending)]
+            return DomainHack(word=lower, sld=sld, tld=tld)
+        return None
+
+    @staticmethod
+    def from_sld(sld: str, tld: TLD) -> DomainHack:
+        """Create a DomainHack directly from an SLD (for brute-force range mode).
+
+        ``word`` is the SLD joined to the suffix without dots (``sumandacomar``
+        for ``sumanda`` + ``com.ar``), the same form ``from_word`` splits.
+
+        Raises InvalidLabelError when ``sld`` is not a valid label for ``tld``.
+        """
+        lower = DomainHack._normalize(sld)
+        return DomainHack(word=f"{lower}{tld.joined}", sld=lower, tld=tld)
+
+
+class Availability(Enum):
+    AVAILABLE = "available"
+    TAKEN = "taken"
+    ERROR = "error"
+
+
+# RFC 9083 §10.2.2 status values (RFC 8056 maps the EPP and RGP codes to
+# them) that mean the registration is on its way out: after "redemption
+# period" (about 30 days, the holder can still restore it) comes "pending
+# delete" (about 5 days, nobody can), then the name is released.
+# "pending restore" is left out on purpose: it means the holder asked to
+# restore the name during redemption, so it is most likely coming back.
+DROPPING_STATUSES: frozenset[str] = frozenset({"pending delete", "redemption period"})
+
+
+@dataclass(frozen=True)
+class DnsEvidence:
+    """What public DNS says about a name: a second opinion, never the verdict.
+
+    ``nameservers`` are the delegated NS hosts (lowercase, no trailing dot);
+    ``has_address`` is True when the name resolves to an A or AAAA record.
+    ``error`` is set when the lookup itself failed (timeout, SERVFAIL...), in
+    which case the other fields carry no information.
+    """
+
+    nameservers: tuple[str, ...] = ()
+    has_address: bool = False
+    error: str = ""
+
+    @property
+    def is_delegated(self) -> bool:
+        """True when the name has NS records, i.e. it is certainly registered."""
+        return not self.error and bool(self.nameservers)
+
+
+@dataclass(frozen=True)
+class DomainCheckResult:
+    """Result of checking a single domain's availability.
+
+    Registration details a registry may return for TAKEN names, all empty
+    when unknown:
+
+    - ``statuses``: RFC 9083 status values (lowercase words, e.g.
+      ``"client hold"``, ``"pending delete"``);
+    - ``expires_at`` / ``registered_at``: aware UTC datetimes;
+    - ``registrar``: the sponsoring registrar's name;
+    - ``nameservers``: delegated NS hosts as published by the registry.
+
+    ``dns`` is optional DNS evidence gathered after the registry check (see
+    ``DnsEvidence``); ``parked_hint`` names the parking/aftermarket service
+    the nameservers point to (e.g. ``"domainrecover"``), when recognised.
+    """
+
+    domain: DomainHack
+    availability: Availability
+    raw_title: str = ""
+    error_message: str = ""
+    statuses: tuple[str, ...] = ()
+    expires_at: datetime | None = None
+    registered_at: datetime | None = None
+    registrar: str = ""
+    nameservers: tuple[str, ...] = ()
+    parked_hint: str = ""
+    dns: DnsEvidence | None = None
+
+    @property
+    def dns_conflict(self) -> bool:
+        """AVAILABLE per the registry, yet delegated in DNS: do not trust it as free."""
+        return (
+            self.availability is Availability.AVAILABLE
+            and self.dns is not None
+            and self.dns.is_delegated
+        )
+
+    @property
+    def dropping_statuses(self) -> tuple[str, ...]:
+        """The statuses in ``DROPPING_STATUSES``, in registry order."""
+        return tuple(s for s in self.statuses if s in DROPPING_STATUSES)
+
+    @property
+    def is_dropping(self) -> bool:
+        """True for a TAKEN name in redemption or pending delete (it may soon be free)."""
+        return self.availability is Availability.TAKEN and bool(self.dropping_statuses)

domainhack/domain/label_rules.py

@@ -0,0 +1,96 @@
+"""Per-TLD registration rules for the label left of the TLD (the SLD).
+
+These rules decide whether a candidate is worth querying at all. A query for
+a name the registry would never accept can only produce noise, and worse, a
+"not found" answer that reads as AVAILABLE. When unsure, an entry is left at
+the RFC defaults below and ``idn`` stays False: skipping a candidate costs
+less than reporting a false AVAILABLE.
+
+Lengths are counted in characters of the name as the user sees it (the
+U-label for IDNs); the DNS limit of 63 octets is checked on the ASCII form.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+DNS_MAX_LABEL_LENGTH = 63
+
+
+@dataclass(frozen=True)
+class LabelRule:
+    """What a registry accepts as the label under one TLD.
+
+    ``min_length``: fewest characters in the (Unicode) label.
+    ``max_length``: most characters in the ASCII (A-label) form.
+    ``idn``: True if the registry registers internationalized names. When
+    False, non-ASCII candidates (and ``xn--`` A-labels) are skipped instead
+    of being converted, since the registry would never hold them.
+    ``forbidden_prefixes``: ASCII prefixes the registry refuses for non-IDN
+    labels (e.g. ``.it`` refuses names starting with ``xn``).
+    """
+
+    min_length: int = 1
+    max_length: int = DNS_MAX_LABEL_LENGTH
+    idn: bool = False
+    forbidden_prefixes: tuple[str, ...] = ()
+
+
+# RFC 1035 / RFC 5891 defaults: 1-63 LDH characters, no IDN assumed.
+DEFAULT_LABEL_RULE = LabelRule()
+
+# Conservative entries for the TLDs in the registrar catalog. Only facts
+# backed by the cited source are encoded; every other catalog TLD
+# (io, sh, ac, me, so, ws, am, gg, im, ma, mx, pe, st, fm, re, tv, ly, is, in,
+# ar, ai, ...) uses DEFAULT_LABEL_RULE until a registry source is checked.
+TLD_LABEL_RULES: Mapping[str, LabelRule] = {
+    # nic.it, "How to register": "A .it domain name can be composed of a
+    # minimum of 3 characters and a maximum of 63 ... It should not begin and
+    # end with the symbol '-' or start with the character sequence 'xn'", and
+    # non-ASCII characters from the Technical Guidelines charset are allowed.
+    # https://www.nic.it/en/find-your-it/how-register
+    "it": LabelRule(min_length=3, idn=True, forbidden_prefixes=("xn",)),
+    # SWITCH FAQ: "Domain names under .ch and .li can also contain non-ASCII
+    # characters such as umlauts and accents"; a name "must be at least three
+    # characters long". https://www.nic.ch/faqs/idn/
+    "ch": LabelRule(min_length=3, idn=True),
+    "li": LabelRule(min_length=3, idn=True),
+    # DENIC: IDN domains with umlauts, accents and 93 additional characters
+    # (IDNA2008). https://www.denic.de/en/know-how/idn-domains/
+    "de": LabelRule(idn=True),
+    # Registries with a Latin IDN table published in the IANA Repository of
+    # IDN Practices, https://www.iana.org/domains/idn-tables
+    # (at_latn_1.0, be_latn_1.1, co_es_3.0 et al., la_latn_1.0, nu_und-latn_2).
+    "at": LabelRule(idn=True),
+    "be": LabelRule(idn=True),
+    "co": LabelRule(idn=True),
+    "la": LabelRule(idn=True),
+    "nu": LabelRule(idn=True),
+    # 101domain .to page: ".to Domain Names must have minimum of 2 and a
+    # maximum of 61 characters", "use the English character set" (languages
+    # supported: none). https://www.101domain.com/to-information-help.htm
+    # min_length stays 1 on purpose: 1-character names exist (a.to is
+    # registered), other registrar sources say 2 or 3, and Tonic's RDAP answers
+    # 200 (TAKEN) for registry-held names, so a short query cannot produce a
+    # false AVAILABLE.
+    "to": LabelRule(max_length=61, idn=False),
+    # NIC Argentina, second-level zones (com.ar, net.ar, org.ar...): the
+    # Reglamento approved by Resolución DNRDI 43/2019, Art. 13, as amended by
+    # Resolución SLYT 2/2022: a name has "UNO (1) y CINCUENTA (50)" characters,
+    # not counting the zone (1-3 character names are registered after NIC.ar
+    # reviews them, so a short query is still worth an answer).
+    # https://www.boletinoficial.gob.ar/detalleAviso/primera/255797/20220106
+    # Valid characters are "las letras de los alfabetos español y portugués
+    # (incluidas la 'ñ' y la 'ç'), las vocales acentuadas y con diéresis, los
+    # números y el guión" (Resolución 110/2016, Art. 9).
+    # https://www.boletinoficial.gob.ar/detalleAviso/primera/148316/20160720
+    # Other second-level suffixes (com.mx, co.uk...) use DEFAULT_LABEL_RULE
+    # until their registry's rules are checked.
+    **dict.fromkeys(("com.ar", "net.ar", "org.ar"), LabelRule(max_length=50, idn=True)),
+}
+
+
+def label_rule_for(suffix: str) -> LabelRule:
+    """The rule for ``suffix`` (case-insensitive), or the RFC default."""
+    return TLD_LABEL_RULES.get(suffix.lower().lstrip("."), DEFAULT_LABEL_RULE)

domainhack/domain/parking.py

@@ -0,0 +1,81 @@
+"""Recognise parking and aftermarket services from a domain's nameservers.
+
+A taken name delegated to a parking or "for sale" service is usually not in
+use: the owner monetises it with ads or waits for a buyer. Knowing that is
+what turns "taken" into "taken, but maybe buyable". This module is pure (no
+I/O): give it NS host names, from the registry or from DNS, and it names the
+service.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+# NS domain -> short provider name. A nameserver matches when it equals the
+# domain or is a subdomain of it ("ns1.sedoparking.com" -> "sedo").
+#
+# Curated 2026-10-06 from:
+# - the live RDAP record of sumanda.com (NS1/NS2.DOMAINRECOVER.COM);
+# - APNIC blog, "The prevalence of domain parking" (2023-11-08), which
+#   identifies Afternic by ns*.afternic.com:
+#   https://blog.apnic.net/2023/11/08/the-prevalence-of-domain-parking/
+# - GoDaddy CashParking setup docs (ns01/ns02.cashparking.com):
+#   https://www.godaddy.com/domains/cashparking
+# - Bodis setup docs (ns1/ns2.bodis.com). Bodis closed on 2026-01-31, but
+#   registries still list domains delegated to it:
+#   https://domaininvesting.com/bodis-to-cease-operating-on-january-31/
+# - Nameserver history on dns.coffee for ns1/ns2 of sedoparking.com,
+#   parkingcrew.net, dan.com, hugedomains.com, namebrightdns.com,
+#   undeveloped.com and above.com, e.g. https://dns.coffee/domains/filmeja.com
+# Every host was also checked to resolve (dig) on 2026-10-06, except
+# ns1.bodis.com (service closed).
+#
+# namebrightdns.com is NameBright's general DNS, but names left on it are
+# overwhelmingly the DropCatch/TurnCommerce aftermarket portfolio. Plain
+# registrar DNS (domaincontrol.com, registrar-servers.com...) is deliberately
+# absent: it hosts live sites as often as parked pages.
+PARKING_NAMESERVERS: Mapping[str, str] = {
+    "domainrecover.com": "domainrecover",
+    "sedoparking.com": "sedo",
+    "parkingcrew.net": "parkingcrew",
+    "bodis.com": "bodis",
+    "afternic.com": "afternic",
+    "dan.com": "dan.com",
+    "hugedomains.com": "hugedomains",
+    "cashparking.com": "godaddy-parked",
+    "namebrightdns.com": "namebright",
+    "undeveloped.com": "undeveloped",
+    "above.com": "above",
+    "uniregistrymarket.link": "uniregistry",
+    "parklogic.com": "parklogic",
+}
+
+
+def _provider_for(host: str) -> str:
+    labels = host.split(".")
+    # Try every suffix, longest first: "a.b.dan.com" -> "b.dan.com", "dan.com", "com".
+    for start in range(len(labels)):
+        provider = PARKING_NAMESERVERS.get(".".join(labels[start:]))
+        if provider is not None:
+            return provider
+    return ""
+
+
+def parking_hint_for(nameservers: Iterable[str]) -> str:
+    """The parking/aftermarket provider the nameservers point to, or ``""``.
+
+    Names are compared case-insensitively and a trailing dot is ignored, so
+    registry (``NS1.DOMAINRECOVER.COM``) and DNS (``ns1.domainrecover.com.``)
+    spellings both work. The first nameserver that matches decides;
+    anything that is not a string is skipped.
+    """
+    for nameserver in nameservers:
+        if not isinstance(nameserver, str):
+            continue
+        host = nameserver.strip().rstrip(".").lower()
+        if not host:
+            continue
+        provider = _provider_for(host)
+        if provider:
+            return provider
+    return ""

domainhack/ports/dns_lookup.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+from domainhack.domain.entities import DnsEvidence
+
+
+class DnsLookup(ABC):
+    """Port: public DNS evidence for a fully qualified (ASCII) domain name."""
+
+    @abstractmethod
+    def lookup(self, fqdn: str) -> DnsEvidence:
+        """Never raises for DNS failures: they are reported in ``DnsEvidence.error``."""

domainhack/ports/known_tlds.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+
+
+class KnownTlds(ABC):
+    """Port: the set of public suffixes a name can be registered under.
+
+    Suffixes are lowercase, without a leading dot, and may have several
+    labels (``"to"``, ``"com.ar"``, ``"co.uk"``).
+    """
+
+    @abstractmethod
+    def is_known(self, suffix: str) -> bool: ...
+
+    @abstractmethod
+    def suffixes_of(self, name: str) -> list[str]:
+        """Known suffixes that ``name`` ends with and that leave a non-empty SLD.
+
+        Only plain concatenation is considered: ``"plato"`` -> ``["to"]``;
+        dots in multi-label suffixes are ignored, so ``"fotocomar"`` yields
+        ``"com.ar"`` (``foto.com.ar``). Longest suffix first.
+        """

domainhack/ports/progress.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+
+from domainhack.domain.entities import DomainCheckResult
+
+
+class ProgressReporter(ABC):
+    """Port: reports progress while domains are being checked."""
+
+    @abstractmethod
+    def start(self, total: int | None) -> None:
+        """Begin reporting. ``total`` is the expected number of checks, or None if unknown."""
+
+    @abstractmethod
+    def advance(self, result: DomainCheckResult) -> None:
+        """Record that one more domain has been checked."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Finish reporting and release any resources."""
+
+
+class NullProgressReporter(ProgressReporter):
+    """Null object: reports nothing. Default when no progress output is wanted."""
+
+    def start(self, total: int | None) -> None:
+        pass
+
+    def advance(self, result: DomainCheckResult) -> None:
+        pass
+
+    def close(self) -> None:
+        pass

domainhack/ports/registrar.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from domainhack.domain.entities import DomainCheckResult, DomainHack
+
+
+class RegistrarClient(ABC):
+    """Port: checks domain availability against a registrar."""
+
+    @abstractmethod
+    def check_availability(self, domain: DomainHack) -> DomainCheckResult: ...
+
+    def close(self) -> None:  # noqa: B027
+        """Release resources. Override if needed."""
+
+    def __enter__(self) -> RegistrarClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        self.close()

domainhack/ports/result_cache.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+from domainhack.domain.entities import DomainCheckResult, DomainHack
+
+
+class ResultCache(ABC):
+    """Port: remembers check results between runs.
+
+    ``CheckDomainsUseCase`` calls it from a single thread (the one running
+    ``execute``), so implementations need not be thread-safe.
+    """
+
+    @abstractmethod
+    def lookup(self, domain: DomainHack) -> DomainCheckResult | None:
+        """A fresh cached result for ``domain``, or None to check it live."""
+
+    @abstractmethod
+    def store(self, result: DomainCheckResult) -> None:
+        """Remember a live result (implementations decide which ones are worth keeping)."""

domainhack/ports/result_writer.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+from domainhack.domain.entities import DomainCheckResult
+
+
+class ResultWriter(ABC):
+    """Port: handles output of domain check results."""
+
+    @abstractmethod
+    def write_result(self, result: DomainCheckResult) -> None: ...
+
+    def flush(self) -> None:  # noqa: B027
+        """Finalize output. Default: no-op."""

domainhack/ports/word_source.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+
+
+class WordSource(ABC):
+    """Port: provides an iterable of candidate words."""
+
+    @abstractmethod
+    def words(self) -> Iterator[str]: ...