domainhack 0.2.0__py3-none-any.whl

domainhack/adapters/brand_report_render.py

@@ -0,0 +1,222 @@
+"""Render a ``BrandReport`` as text (aligned, for the terminal), Markdown or JSON.
+
+Every renderer is a pure function of the report, so output is deterministic.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from domainhack.usecases.brand_report import BrandReport, ReportEntry
+
+Renderer = Callable[[BrandReport], str]
+
+_NONE = "(none)"
+_NO_VARIANTS = "not requested (add --variants)"
+
+
+def _variants_empty(report: BrandReport) -> str:
+    return "none available" if report.variants_requested else _NO_VARIANTS
+
+
+def _hack_reading(entry: ReportEntry) -> str:
+    meaning = entry.candidate.meaning
+    return f"{entry.label}: {meaning}" if meaning else entry.label
+
+
+def _with_detail(*parts: str) -> str:
+    return " -- ".join(p for p in parts if p)
+
+
+# ── text ─────────────────────────────────────────────────
+
+
+def _align(rows: Sequence[Sequence[str]], indent: str = "  ") -> list[str]:
+    """Left-align every column but the last; trailing spaces are stripped. ``rows`` is non-empty."""
+    widths = [max(len(row[i]) for row in rows) for i in range(len(rows[0]) - 1)]
+    lines = []
+    for row in rows:
+        cells = [cell.ljust(width) for cell, width in zip(row, widths, strict=False)]
+        lines.append((indent + "  ".join([*cells, row[-1]])).rstrip())
+    return lines
+
+
+def _text_section(title: str, rows: Sequence[Sequence[str]], empty: str = _NONE) -> list[str]:
+    body = _align(rows) if rows else [f"  {empty}"]
+    return ["", title, *body]
+
+
+def render_text(report: BrandReport) -> str:
+    lines = [
+        f"Domains for {report.name!r}",
+        f"TLDs: {', '.join(t.suffix for t in report.tlds) or _NONE}",
+    ]
+    lines += _text_section("Exact name", [(e.name, e.status.value, e.detail) for e in report.exact])
+    hack_rows = [
+        (e.name, e.status.value, _with_detail(_hack_reading(e), e.detail)) for e in report.hacks
+    ]
+    hack_lines = _text_section("Domain hacks", hack_rows)
+    if not report.suffix_hack_found:
+        hack_lines.insert(2, f"  {report.no_suffix_hack_note}")
+        if not hack_rows:
+            hack_lines.pop()  # the note replaces "(none)"
+    lines += hack_lines
+    lines += _text_section(
+        "Brand variants (available)",
+        [(e.name, _with_detail(e.label, e.detail)) for e in report.variants],
+        _variants_empty(report),
+    )
+    lines += _text_section("Taken", [(e.name, e.status.value, e.detail) for e in report.taken])
+    lines += _text_section(
+        "Could not verify", [(e.name, e.status.value, e.detail) for e in report.unverifiable]
+    )
+    lines += _text_section("DNS conflicts", [(e.name, e.detail) for e in report.dns_conflicts])
+    rec_rows = [(f"{r.rank}.", r.entry.name, r.reason) for r in report.recommendations]
+    lines += _text_section("Recommendation", rec_rows, "nothing available to recommend")
+    if report.more_available:
+        lines.append(f"  (+{report.more_available} more available above)")
+    lines += [f"  - {line}" for line in report.advice]
+    if report.notes:
+        lines += ["", "Notes", *(f"  - {note}" for note in report.notes)]
+    return "\n".join(lines) + "\n"
+
+
+# ── markdown ─────────────────────────────────────────────
+
+
+def _cell(text: str) -> str:
+    return text.replace("|", "\\|") if text else ""
+
+
+def _md_table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> list[str]:
+    out = [
+        "| " + " | ".join(headers) + " |",
+        "|" + "|".join("---" for _ in headers) + "|",
+    ]
+    out += ["| " + " | ".join(_cell(c) for c in row) + " |" for row in rows]
+    return out
+
+
+def _md_section(
+    title: str, headers: Sequence[str], rows: Sequence[Sequence[str]], empty: str = "None."
+) -> list[str]:
+    body = _md_table(headers, rows) if rows else [f"_{empty}_"]
+    return ["", f"## {title}", "", *body]
+
+
+def render_markdown(report: BrandReport) -> str:
+    tlds = ", ".join(f"`.{t.suffix}`" for t in report.tlds) or "none"
+    lines = [f"# Domains for `{report.name}`", "", f"TLDs: {tlds}"]
+    status_headers = ("Domain", "Status", "Details")
+
+    def code(entry: ReportEntry) -> str:
+        return f"`{entry.name}`"
+
+    lines += _md_section(
+        "Exact name", status_headers, [(code(e), e.status.value, e.detail) for e in report.exact]
+    )
+    hack_section = _md_section(
+        "Domain hacks",
+        ("Domain", "Status", "Reads as", "Details"),
+        [(code(e), e.status.value, _hack_reading(e), e.detail) for e in report.hacks],
+    )
+    if not report.suffix_hack_found:
+        note = f"_{report.no_suffix_hack_note[0].upper()}{report.no_suffix_hack_note[1:]}._"
+        if report.hacks:
+            hack_section[3:3] = [note, ""]
+        else:
+            hack_section[-1] = note
+    lines += hack_section
+    lines += _md_section(
+        "Brand variants (available)",
+        ("Domain", "Reads as", "Details"),
+        [(code(e), e.label, e.detail) for e in report.variants],
+        _variants_empty(report).capitalize() + ".",
+    )
+    lines += _md_section(
+        "Taken", status_headers, [(code(e), e.status.value, e.detail) for e in report.taken]
+    )
+    lines += _md_section(
+        "Could not verify",
+        status_headers,
+        [(code(e), e.status.value, e.detail) for e in report.unverifiable],
+    )
+    lines += _md_section(
+        "DNS conflicts", ("Domain", "Details"), [(code(e), e.detail) for e in report.dns_conflicts]
+    )
+    lines += ["", "## Recommendation", ""]
+    if report.recommendations:
+        lines += [f"{r.rank}. **`{r.entry.name}`**: {r.reason}" for r in report.recommendations]
+    else:
+        lines.append("_Nothing available to recommend._")
+    if report.more_available:
+        lines += ["", f"_+{report.more_available} more available above._"]
+    if report.advice:
+        lines += ["", *(f"- {line}" for line in report.advice)]
+    if report.notes:
+        lines += ["", "## Notes", "", *(f"- {note}" for note in report.notes)]
+    return "\n".join(lines) + "\n"
+
+
+# ── json ─────────────────────────────────────────────────
+
+
+def _entry_json(entry: ReportEntry) -> dict[str, Any]:
+    data: dict[str, Any] = {
+        "domain": entry.name,
+        "fqdn": entry.fqdn,
+        "kind": entry.kind.value,
+        "label": entry.label,
+        "status": entry.status.value,
+        "detail": entry.detail,
+    }
+    if entry.candidate.meaning:
+        data["meaning"] = entry.candidate.meaning
+    result = entry.result
+    if result is not None and (result.registered_at or result.expires_at or result.statuses):
+        data["registered_at"] = result.registered_at.isoformat() if result.registered_at else None
+        data["expires_at"] = result.expires_at.isoformat() if result.expires_at else None
+        data["statuses"] = list(result.statuses)
+    if result is not None and result.registrar:
+        data["registrar"] = result.registrar
+    if result is not None and result.parked_hint:
+        data["parked_hint"] = result.parked_hint
+    if result is not None and result.dns is not None:
+        data["dns"] = {
+            "nameservers": list(result.dns.nameservers),
+            "has_address": result.dns.has_address,
+            "error": result.dns.error,
+        }
+    return data
+
+
+def render_json(report: BrandReport) -> str:
+    data = {
+        "name": report.name,
+        "tlds": [t.suffix for t in report.tlds],
+        "exact": [_entry_json(e) for e in report.exact],
+        "hacks": [_entry_json(e) for e in report.hacks],
+        "suffix_hack_found": report.suffix_hack_found,
+        "variants_requested": report.variants_requested,
+        "variants": [_entry_json(e) for e in report.variants],
+        "taken": [_entry_json(e) for e in report.taken],
+        "unverifiable": [_entry_json(e) for e in report.unverifiable],
+        "dns_conflicts": [_entry_json(e) for e in report.dns_conflicts],
+        "recommendations": [
+            {"rank": r.rank, "domain": r.entry.name, "score": r.score, "reason": r.reason}
+            for r in report.recommendations
+        ],
+        "more_available": report.more_available,
+        "advice": list(report.advice),
+        "notes": list(report.notes),
+    }
+    return json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+
+
+RENDERERS: dict[str, Renderer] = {
+    "text": render_text,
+    "markdown": render_markdown,
+    "json": render_json,
+}

domainhack/adapters/cached_registrar.py

@@ -0,0 +1,340 @@
+"""SQLite-backed caching decorator for any RegistrarClient."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sqlite3
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from domainhack.adapters._registration import (
+    normalize_name,
+    normalize_nameservers,
+    normalize_statuses,
+)
+from domainhack.adapters._stderr import write_stderr
+from domainhack.domain.entities import Availability, DomainCheckResult, DomainHack
+from domainhack.ports.registrar import RegistrarClient
+from domainhack.ports.result_cache import ResultCache
+
+HOUR: float = 60 * 60
+DAY: float = 24 * HOUR
+AVAILABLE_TTL_SECONDS: float = 24 * HOUR
+DROPPING_TTL_SECONDS: float = 24 * HOUR
+TAKEN_TTL_SECONDS: float = 30 * DAY
+TAKEN_MAX_TTL_SECONDS: float = 90 * DAY
+CACHE_RAW_TITLE = "cache"
+# Rows are committed in batches: every COMMIT_EVERY writes, when COMMIT_INTERVAL
+# seconds have passed since the last commit, and on close(). A killed run loses
+# at most one batch; Ctrl-C goes through close() and loses nothing.
+COMMIT_EVERY = 25
+COMMIT_INTERVAL_SECONDS = 10.0
+
+SCHEMA_VERSION = 2
+_COLUMNS = {
+    # Version 0 (before statuses/expiration were stored): fqdn, availability, checked_at.
+    # Version 1:
+    "statuses": "TEXT NOT NULL DEFAULT ''",
+    "expires_at": "REAL",
+    # Version 2:
+    "registered_at": "REAL",
+    "registrar": "TEXT NOT NULL DEFAULT ''",
+    "nameservers": "TEXT NOT NULL DEFAULT ''",
+    "parked_hint": "TEXT NOT NULL DEFAULT ''",
+}
+_DETAIL_COLUMNS = tuple(_COLUMNS)
+
+_CACHEABLE = (Availability.AVAILABLE, Availability.TAKEN)
+
+
+def default_cache_path() -> Path:
+    """Return ``$XDG_CACHE_HOME/domainhack/results.sqlite3`` (or ``~/.cache/...``)."""
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "domainhack" / "results.sqlite3"
+
+
+@dataclass(frozen=True)
+class CacheTtlPolicy:
+    """How long a cached result stays fresh, by what it says.
+
+    * AVAILABLE: ``available`` (24 h). Free names are the ones people act on,
+      and someone else can register them at any moment.
+    * TAKEN and dropping (redemption / pending delete): ``dropping`` (24 h).
+    * TAKEN with an expiration date: until that date, at least ``dropping``
+      (a name past its expiry is in its grace period and worth a daily look)
+      and at most ``taken_max`` (90 days).
+    * TAKEN otherwise: ``taken`` (30 days).
+
+    ``cap`` (``--cache-ttl``), when set, caps every one of these.
+    """
+
+    available: float = AVAILABLE_TTL_SECONDS
+    dropping: float = DROPPING_TTL_SECONDS
+    taken: float = TAKEN_TTL_SECONDS
+    taken_max: float = TAKEN_MAX_TTL_SECONDS
+    cap: float | None = None
+
+    def ttl_for(self, result: DomainCheckResult, checked_at: float) -> float:
+        """Seconds a ``result`` checked at ``checked_at`` (epoch seconds) stays fresh."""
+        if result.availability is Availability.AVAILABLE:
+            ttl = self.available
+        elif result.is_dropping:
+            ttl = self.dropping
+        elif result.expires_at is not None:
+            until_expiry = result.expires_at.timestamp() - checked_at
+            ttl = min(max(until_expiry, self.dropping), self.taken_max)
+        else:
+            ttl = self.taken
+        return ttl if self.cap is None else min(ttl, self.cap)
+
+
+class CachedRegistrarClient(RegistrarClient, ResultCache):
+    """Decorator that caches AVAILABLE/TAKEN results of an inner RegistrarClient.
+
+    Cache hits never touch the inner client, so any rate-limit delay it applies
+    is skipped. ERROR results are never cached. Results served from the cache
+    carry ``raw_title == "cache"`` plus the stored registration details
+    (``statuses``, ``expires_at``, ``registered_at``, ``registrar``,
+    ``nameservers``, ``parked_hint``). DNS evidence (``dns``) is never stored:
+    it is a fresh second opinion, gathered on every run. How long each
+    result stays fresh is set by ``ttl`` (a ``CacheTtlPolicy``); it is
+    decided when the row is read, so a smaller ``--cache-ttl`` also applies
+    to rows written by earlier runs.
+
+    The cache is an optimisation, never a reason to fail a run: if the database
+    cannot be opened, read or written (corrupt file, a directory, no
+    permission...), ``warn`` is called once and every later check goes straight
+    to the inner client. Cache files written by older versions are migrated in
+    place (missing columns are added; old rows read as "no details").
+
+    It is also a ``ResultCache``: ``lookup`` and ``store`` let a caller that
+    queries the inner client itself (the parallel check) use the cache from
+    one thread. The sqlite connection is not shared across threads, so all
+    calls must come from the same thread.
+    """
+
+    def __init__(
+        self,
+        inner: RegistrarClient,
+        path: Path | None = None,
+        ttl: CacheTtlPolicy | None = None,
+        clock: Callable[[], float] = time.time,
+        warn: Callable[[str], None] = write_stderr,
+        *,
+        commit_every: int = COMMIT_EVERY,
+        commit_interval: float = COMMIT_INTERVAL_SECONDS,
+    ) -> None:
+        self._inner = inner
+        self._path = path if path is not None else default_cache_path()
+        self._ttl = ttl if ttl is not None else CacheTtlPolicy()
+        self._clock = clock
+        self._conn: sqlite3.Connection | None = None
+        self._warn = warn
+        self._disabled = False
+        self._commit_every = max(commit_every, 1)
+        self._commit_interval = commit_interval
+        self._pending = 0
+        self._last_commit = 0.0
+
+    @property
+    def disabled(self) -> bool:
+        """True once the cache failed and the client became a pass-through."""
+        return self._disabled
+
+    @property
+    def ttl(self) -> CacheTtlPolicy:
+        return self._ttl
+
+    def _disable(self, exc: Exception) -> None:
+        self._disabled = True
+        self._close_db(commit=False)
+        self._warn(f"warning: result cache disabled ({self._path}: {exc}); continuing without it")
+
+    def _close_db(self, *, commit: bool) -> None:
+        conn, self._conn = self._conn, None
+        if conn is None:
+            return
+        try:
+            if commit and self._pending:
+                conn.commit()
+        except sqlite3.Error as exc:
+            self._warn(f"warning: could not save the result cache ({self._path}: {exc})")
+        finally:
+            self._pending = 0
+            with contextlib.suppress(sqlite3.Error):
+                conn.close()
+
+    def _db(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            conn = sqlite3.connect(self._path)
+            try:
+                _migrate(conn)
+            except BaseException:
+                conn.close()
+                raise
+            self._conn = conn
+            self._last_commit = self._clock()
+        return self._conn
+
+    def _lookup(self, domain: DomainHack) -> DomainCheckResult | None:
+        row = (
+            self._db()
+            .execute(
+                f"SELECT availability, checked_at, {', '.join(_DETAIL_COLUMNS)}"
+                " FROM results WHERE fqdn = ?",
+                (domain.fqdn,),
+            )
+            .fetchone()
+        )
+        if row is None:
+            return None
+        (
+            availability_value,
+            checked_at,
+            statuses_value,
+            expires_value,
+            registered_value,
+            registrar_value,
+            nameservers_value,
+            parked_value,
+        ) = row
+        try:
+            availability = Availability(availability_value)
+            checked = float(checked_at)
+        except (TypeError, ValueError):
+            return None
+        if availability not in _CACHEABLE:
+            return None
+        result = DomainCheckResult(
+            domain=domain,
+            availability=availability,
+            raw_title=CACHE_RAW_TITLE,
+            statuses=_load_statuses(statuses_value),
+            expires_at=_load_timestamp(expires_value),
+            registered_at=_load_timestamp(registered_value),
+            registrar=normalize_name(registrar_value) or "",
+            nameservers=normalize_nameservers(_load_json_list(nameservers_value)),
+            parked_hint=normalize_name(parked_value) or "",
+        )
+        if self._clock() - checked > self._ttl.ttl_for(result, checked):
+            return None
+        return result
+
+    def _store(self, result: DomainCheckResult) -> None:
+        db = self._db()
+        columns = ("fqdn", "availability", "checked_at", *_DETAIL_COLUMNS)
+        db.execute(
+            f"INSERT OR REPLACE INTO results ({', '.join(columns)})"
+            f" VALUES ({', '.join('?' * len(columns))})",
+            (
+                result.domain.fqdn,
+                result.availability.value,
+                self._clock(),
+                _dump_list(result.statuses),
+                _dump_timestamp(result.expires_at),
+                _dump_timestamp(result.registered_at),
+                result.registrar,
+                _dump_list(result.nameservers),
+                result.parked_hint,
+            ),
+        )
+        self._pending += 1
+        now = self._clock()
+        if self._pending >= self._commit_every or now - self._last_commit >= self._commit_interval:
+            db.commit()
+            self._pending = 0
+            self._last_commit = now
+
+    def lookup(self, domain: DomainHack) -> DomainCheckResult | None:
+        """A fresh cached result for ``domain``, or None (also when the cache failed)."""
+        if self._disabled:
+            return None
+        try:
+            return self._lookup(domain)
+        except (sqlite3.Error, OSError) as exc:
+            self._disable(exc)
+            return None
+
+    def store(self, result: DomainCheckResult) -> None:
+        """Save an AVAILABLE/TAKEN ``result``; anything else is ignored."""
+        if result.availability not in _CACHEABLE or self._disabled:
+            return
+        try:
+            self._store(result)
+        except (sqlite3.Error, OSError) as exc:
+            self._disable(exc)
+
+    def check_availability(self, domain: DomainHack) -> DomainCheckResult:
+        cached = self.lookup(domain)
+        if cached is not None:
+            return cached
+        result = self._inner.check_availability(domain)
+        self.store(result)
+        return result
+
+    def close(self) -> None:
+        try:
+            self._close_db(commit=True)
+        finally:
+            self._inner.close()
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """Create the table, or bring an older one up to ``SCHEMA_VERSION`` in place."""
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS results ("
+        " fqdn TEXT PRIMARY KEY,"
+        " availability TEXT NOT NULL,"
+        " checked_at REAL NOT NULL)"
+    )
+    present = {row[1] for row in conn.execute("PRAGMA table_info(results)")}
+    for name, declaration in _COLUMNS.items():
+        if name not in present:
+            conn.execute(f"ALTER TABLE results ADD COLUMN {name} {declaration}")
+    (version,) = conn.execute("PRAGMA user_version").fetchone()
+    if version < SCHEMA_VERSION:
+        # TAKEN rows written by an older schema lack the registration details
+        # added since, and their TTL (up to the expiry date) would hide that
+        # for months: expire them so the next run fetches the details.
+        conn.execute("UPDATE results SET checked_at = 0 WHERE availability = 'taken'")
+        conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+    conn.commit()
+
+
+def _dump_list(values: tuple[str, ...]) -> str:
+    return json.dumps(list(values)) if values else ""
+
+
+def _dump_timestamp(value: datetime | None) -> float | None:
+    return value.timestamp() if value is not None else None
+
+
+def _load_json_list(value: object) -> list[object]:
+    """A stored JSON list; ``[]`` for old rows or anything malformed."""
+    if not isinstance(value, str) or not value:
+        return []
+    try:
+        parsed = json.loads(value)
+    except ValueError:
+        return []
+    return parsed if isinstance(parsed, list) else []
+
+
+def _load_statuses(value: object) -> tuple[str, ...]:
+    """Stored statuses (a JSON list); ``()`` for old rows or anything malformed."""
+    return normalize_statuses(_load_json_list(value))
+
+
+def _load_timestamp(value: object) -> datetime | None:
+    if not isinstance(value, (int, float)):
+        return None
+    try:
+        return datetime.fromtimestamp(value, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError):
+        return None

domainhack/adapters/composite_writer.py

@@ -0,0 +1,27 @@
+from collections.abc import Sequence
+
+from domainhack.domain.entities import DomainCheckResult
+from domainhack.ports.result_writer import ResultWriter
+
+
+class CompositeResultWriter(ResultWriter):
+    """Fans out every result to several writers (e.g. console + file)."""
+
+    def __init__(self, writers: Sequence[ResultWriter]) -> None:
+        self._writers = tuple(writers)
+
+    def write_result(self, result: DomainCheckResult) -> None:
+        for writer in self._writers:
+            writer.write_result(result)
+
+    def flush(self) -> None:
+        """Flush every writer, even if one fails; re-raise the first error."""
+        first_error: Exception | None = None
+        for writer in self._writers:
+            try:
+                writer.flush()
+            except Exception as exc:
+                if first_error is None:
+                    first_error = exc
+        if first_error is not None:
+            raise first_error

domainhack/adapters/console_writer.py

@@ -0,0 +1,77 @@
+import sys
+
+from domainhack.adapters._stderr import write_stderr
+from domainhack.domain.entities import Availability, DomainCheckResult, DomainHack
+from domainhack.ports.result_writer import ResultWriter
+
+
+class ConsoleResultWriter(ResultWriter):
+    """Writes domain check results to the console.
+
+    Results (AVAILABLE, and TAKEN with ``show_taken``) go to stdout, so the
+    output can be piped; ERROR lines are diagnostics and go to stderr. TAKEN
+    names in redemption or pending delete ("dropping") are printed with their
+    status and expiry date, and ``show_dropping`` prints them even without
+    ``show_taken``. Other TAKEN names print with whatever registration
+    details are known: ``TAKEN:     sumanda.com (since 2015-11-12, expires
+    2026-11-12, parked: domainrecover)``. An AVAILABLE name that DNS shows as
+    delegated (``dns_conflict``, see ``--confirm-dns``) prints as
+    ``AVAILABLE?`` with a warning instead. The run summary is printed by the
+    CLI, from the use case's
+    ``CheckSummary``.
+    """
+
+    def __init__(
+        self, show_taken: bool = False, show_errors: bool = True, show_dropping: bool = False
+    ) -> None:
+        self._show_taken = show_taken
+        self._show_errors = show_errors
+        self._show_dropping = show_dropping
+
+    def write_result(self, result: DomainCheckResult) -> None:
+        match result.availability:
+            case Availability.AVAILABLE:
+                if result.dns_conflict:
+                    print(
+                        f"  AVAILABLE? {_name(result.domain)} -- registry says free "
+                        "but DNS has NS records"
+                    )
+                else:
+                    print(f"  AVAILABLE: {_name(result.domain)} (word: {result.domain.word!r})")
+            case Availability.TAKEN:
+                if result.is_dropping:
+                    if self._show_taken or self._show_dropping:
+                        print(f"  TAKEN ({_dropping_detail(result)}): {_name(result.domain)}")
+                elif self._show_taken:
+                    print(f"  TAKEN:     {_name(result.domain)}{_taken_detail(result)}")
+            case Availability.ERROR:
+                if self._show_errors:
+                    write_stderr(f"  ERROR:     {_name(result.domain)} -- {result.error_message}")
+
+    def flush(self) -> None:
+        sys.stdout.flush()
+
+
+def _dropping_detail(result: DomainCheckResult) -> str:
+    """``dropping: pending delete, expires 2026-11-02`` (the date only when known)."""
+    detail = f"dropping: {', '.join(result.dropping_statuses)}"
+    if result.expires_at is not None:
+        detail += f", expires {result.expires_at.date().isoformat()}"
+    return detail
+
+
+def _taken_detail(result: DomainCheckResult) -> str:
+    """`` (since 2015-11-12, expires 2026-11-12, parked: domainrecover)``, known parts only."""
+    parts = []
+    if result.registered_at is not None:
+        parts.append(f"since {result.registered_at.date().isoformat()}")
+    if result.expires_at is not None:
+        parts.append(f"expires {result.expires_at.date().isoformat()}")
+    if result.parked_hint:
+        parts.append(f"parked: {result.parked_hint}")
+    return f" ({', '.join(parts)})" if parts else ""
+
+
+def _name(domain: DomainHack) -> str:
+    """The name as written, plus the queried A-label for IDNs: ``ñandú.de (xn--and-6ma2c.de)``."""
+    return f"{domain.display} ({domain.fqdn})" if domain.is_idn else domain.fqdn