domainhack 0.2.0__py3-none-any.whl

domainhack/cli/name_cmd.py

@@ -0,0 +1,222 @@
+"""``domainhack name NAME``: find a domain for a brand name, in one command.
+
+Checks the exact name under each requested TLD, domain hacks (the name split
+at a TLD it ends with, or the name plus a word that ends in one) and, with
+``--variants``, brand variants; then prints a report with a recommendation.
+Checking reuses ``CheckDomainsUseCase`` and the ``check`` wiring in
+``cli.app`` (registrar catalog and router, parallel lanes, cache, circuit
+breaker, progress bar).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from domainhack.adapters.brand_data import DEFAULT_PRESET, load_hack_words, load_tld_presets
+from domainhack.adapters.brand_report_render import RENDERERS
+from domainhack.adapters.cached_registrar import CachedRegistrarClient
+from domainhack.adapters.dns_resolver import DnsPythonLookup
+from domainhack.adapters.iana_tlds import IanaTldList
+from domainhack.adapters.registrar_catalog import supported_tlds
+from domainhack.adapters.registry_sources import describe_unsupported, unsupported_message
+from domainhack.cli import app
+from domainhack.domain.entities import DomainCheckResult
+from domainhack.ports.dns_lookup import DnsLookup
+from domainhack.ports.known_tlds import KnownTlds
+from domainhack.ports.result_writer import ResultWriter
+from domainhack.usecases.brand_candidates import BrandCandidates, resolve_tld_spec
+from domainhack.usecases.brand_report import build_brand_report
+from domainhack.usecases.check_domains import CheckDomainsUseCase
+from domainhack.usecases.confirm_dns import ConfirmWithDns
+
+REPORT_FORMATS = tuple(RENDERERS)
+
+
+@dataclass(frozen=True)
+class NameServices:
+    """What ``name`` needs besides the registrar catalog (tests pass fakes).
+
+    ``dns`` is optional: without it, results are not confirmed against DNS.
+    ``supported_tlds`` lists the catalog's TLDs for the ``all-supported`` preset.
+    """
+
+    known_tlds: KnownTlds
+    dns: DnsLookup | None = None
+    supported_tlds: Callable[[], Iterable[str]] = supported_tlds
+
+
+def _default_services() -> NameServices:
+    """Production wiring for ``name``: the known-TLD list and the DNS lookup."""
+    return NameServices(known_tlds=IanaTldList(), dns=DnsPythonLookup())
+
+
+def _confirm_with_dns(
+    lookup: DnsLookup, results: Sequence[DomainCheckResult]
+) -> list[DomainCheckResult]:
+    return ConfirmWithDns(lookup).apply(results)
+
+
+class _Collector(ResultWriter):
+    def __init__(self) -> None:
+        self.results: list[DomainCheckResult] = []
+
+    def write_result(self, result: DomainCheckResult) -> None:
+        self.results.append(result)
+
+
+def _brand_name(value: str) -> str:
+    name = value.strip().lower()
+    if not name or any(c.isspace() for c in name):
+        raise argparse.ArgumentTypeError(f"not a single name: {value!r}")
+    if "." in name:
+        raise argparse.ArgumentTypeError(
+            f"give the name without a TLD (e.g. {name.split('.')[0]!r}), got {value!r}"
+        )
+    return name
+
+
+def register(sub: argparse._SubParsersAction[argparse.ArgumentParser], *, epilog: str) -> None:
+    """Add the ``name`` subcommand to the CLI's subparsers."""
+    presets = ", ".join(load_tld_presets())
+    parser = sub.add_parser(
+        "name",
+        help="Find a domain for a brand name (exact, hacks, variants) and recommend one",
+        description="Check NAME under a set of TLDs, look for domain hacks that spell it "
+        "(sumanda -> sumandastud.io) and, with --variants, brand variants "
+        "(getsumanda.com); then print a report with a recommendation.",
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("name", type=_brand_name, help="The name, without a TLD (e.g. sumanda)")
+    parser.add_argument(
+        "--tlds",
+        default=DEFAULT_PRESET,
+        metavar="PRESET|TLD[,...]",
+        help=f"Presets ({presets}) and TLDs, mixed: startup,com.ar,la (default: {DEFAULT_PRESET})",
+    )
+    parser.add_argument(
+        "--variants",
+        action="store_true",
+        help="Also check get-/use-/try-/hola-/my- NAME and NAME -hq/-app/-labs/-studio, "
+        "under .com and the first 3 other TLDs",
+    )
+    parser.add_argument(
+        "--format",
+        choices=REPORT_FORMATS,
+        default="text",
+        help="Report format on stdout (default: text)",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Also save the raw results to FILE (.csv, .json or .jsonl)",
+    )
+    parser.add_argument(
+        "--confirm-dns",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Confirm results against public DNS (default: on when a DNS resolver is available)",
+    )
+    app.add_run_options(parser)
+
+
+def cmd_name(
+    args: argparse.Namespace,
+    *,
+    catalog: app.RegistrarCatalog | None = None,
+    services: NameServices | None = None,
+) -> int:
+    services = services if services is not None else _default_services()
+    notes: list[str] = []
+    selection = resolve_tld_spec(args.tlds, load_tld_presets(), services.supported_tlds)
+    for suffix in selection.rejected:
+        notes.append(f".{suffix} skipped: not a TLD this version can check")
+        app._stderr(f"warning: .{suffix} is not a TLD this version can check; skipping")
+    if not selection.tlds:
+        app._stderr(f"error: no valid TLD in --tlds {args.tlds!r}")
+        return app.EXIT_USAGE
+    output: Path | None = args.output
+    fmt = app._resolve_output_format(output, None) if output is not None else None
+
+    confirm = args.confirm_dns if args.confirm_dns is not None else services.dns is not None
+    if confirm and services.dns is None:
+        app._stderr("warning: no DNS resolver available; results are not confirmed in DNS")
+        confirm = False
+
+    generator = BrandCandidates(
+        args.name,
+        selection.tlds,
+        services.known_tlds,
+        variants=args.variants,
+        hack_words=load_hack_words(),
+    )
+    candidates = generator.execute()
+    if not candidates:
+        app._stderr(f"error: {args.name!r} is not a valid domain name label")
+        return app.EXIT_USAGE
+    if generator.skipped:
+        notes.append(f"skipped {generator.skipped} invalid candidates")
+    for suffix in generator.unusable_suffixes:
+        notes.append(f"hack under .{suffix} skipped: not a TLD this version can check")
+
+    router = app._build_router(args, catalog)
+    try:
+        unsupported = {c.domain.tld for c in candidates if not router.supports(c.domain.tld)}
+        domains = [c.domain for c in candidates if c.domain.tld not in unsupported]
+        requested = [t.suffix for t in selection.tlds if t in unsupported]
+        for message in describe_unsupported(requested):
+            app._stderr(f"warning: {message}; skipping")
+        if not domains:
+            raise app.NoSupportedTLDError(
+                f"no registrar supports any candidate TLD for {args.name!r}"
+            )
+        file_writer = app.build_file_writer(output, fmt) if output and fmt else None
+    except BaseException:
+        router.close()
+        raise
+
+    collector = _Collector()
+    with app._build_registrar(args, router) as registrar:
+        cache = registrar if isinstance(registrar, CachedRegistrarClient) else None
+        use_case = CheckDomainsUseCase(
+            router,
+            collector,
+            app._build_progress(args),
+            cache=cache,
+            parallel=args.parallel,
+            lane_key=app._lane_key(args, router),
+        )
+        summary = use_case.execute(domains, total=len(domains))
+
+    order = {c.domain.fqdn: i for i, c in enumerate(candidates)}
+    results = sorted(collector.results, key=lambda r: order[r.domain.fqdn])
+    try:
+        if confirm and services.dns is not None and not summary.interrupted:
+            results = _confirm_with_dns(services.dns, results)
+    finally:
+        if file_writer is not None:
+            for result in results:
+                file_writer.write_result(result)
+            file_writer.flush()
+
+    if summary.interrupted:
+        notes.append("run interrupted: some names were not checked")
+    report = build_brand_report(
+        generator.name,
+        candidates,
+        results,
+        tlds=selection.tlds,
+        suffix_hack_found=generator.suffix_hack_found,
+        variants_requested=args.variants,
+        unsupported=unsupported,
+        notes=notes,
+        unsupported_reasons={t: unsupported_message(t.suffix) for t in unsupported},
+    )
+    sys.stdout.write(RENDERERS[args.format](report))
+    app._warn_skipped(generator.skipped)
+    return app._report(summary)

domainhack/cli/tlds_cmd.py

@@ -0,0 +1,96 @@
+"""``domainhack tlds``: which TLDs this version can check, how, and why not.
+
+Offline: it reads the bundled IANA TLD list, RDAP bootstrap snapshot and
+registry data, so the answer is the same on every machine.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from collections import Counter
+from collections.abc import Sequence
+
+from domainhack.adapters.iana_tlds import IanaTldList
+from domainhack.adapters.rdap_bootstrap import RdapBootstrap
+from domainhack.adapters.registrar_catalog import Backend, describe_backend
+
+EXIT_OK = 0
+EXIT_USAGE = 2
+
+
+def register(sub: argparse._SubParsersAction[argparse.ArgumentParser], *, epilog: str) -> None:
+    """Add the ``tlds`` subcommand to the CLI's subparsers."""
+    parser = sub.add_parser(
+        "tlds",
+        help="Show which TLDs can be checked, and how (RDAP or WHOIS) or why not",
+        description="List TLDs with the backend used to check them. Without arguments: "
+        "a coverage summary plus every country-code TLD. Offline.",
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "only", nargs="*", metavar="TLD", help="Only these TLDs (e.g. cl es com.ar)"
+    )
+    parser.add_argument(
+        "--unsupported", action="store_true", help="Only TLDs that cannot be checked, with why"
+    )
+    parser.add_argument(
+        "--all", action="store_true", help="Include generic TLDs (com, app...), not only ccTLDs"
+    )
+    parser.add_argument("--json", action="store_true", help="Machine-readable output")
+
+
+def _offline_bootstrap() -> RdapBootstrap:
+    def no_fetch() -> bytes:
+        raise OSError("offline")
+
+    return RdapBootstrap(fetcher=no_fetch, warn=lambda _message: None)
+
+
+def cmd_tlds(args: argparse.Namespace, bootstrap: RdapBootstrap | None = None) -> int:
+    rdap = bootstrap if bootstrap is not None else _offline_bootstrap()
+    known = IanaTldList()
+    if args.only:
+        suffixes = [s.lower().lstrip(".") for s in args.only]
+        unknown = [s for s in suffixes if not known.is_known(s)]
+        if unknown:
+            print(f"domainhack tlds: error: not a known TLD: {', '.join(unknown)}", file=sys.stderr)
+            return EXIT_USAGE
+    else:
+        suffixes = sorted(
+            t
+            for t in known.top_level_domains
+            if not t.startswith("xn--") and (args.all or len(t) == 2)
+        )
+    every = [describe_backend(s, rdap) for s in suffixes]
+    shown = [b for b in every if b.kind == "unsupported"] if args.unsupported else every
+    if args.json:
+        print(json.dumps([dataclasses.asdict(b) for b in shown], indent=2))
+        sys.stdout.flush()  # surface a closed pipe (| head) to main's handler
+        return EXIT_OK
+    if not args.only:
+        print(_summary(every))
+        print()
+    _print_table(shown)
+    sys.stdout.flush()  # surface a closed pipe (| head) to main's handler
+    return EXIT_OK
+
+
+def _summary(backends: Sequence[Backend]) -> str:
+    counts = Counter(b.kind for b in backends)
+    supported = len(backends) - counts["unsupported"]
+    parts = [
+        f"{counts[k]} {k}" for k in ("rdap", "whois", "whois-fallback", "unsupported") if counts[k]
+    ]
+    return f"{supported} of {len(backends)} TLDs can be checked ({', '.join(parts)})"
+
+
+def _print_table(backends: Sequence[Backend]) -> None:
+    width_tld = max((len(b.tld) for b in backends), default=3) + 1
+    width_kind = max((len(b.kind) for b in backends), default=4)
+    width_host = max((len(b.host) for b in backends), default=4)
+    for b in backends:
+        print(f"  .{b.tld:<{width_tld}} {b.kind:<{width_kind}}  {b.host:<{width_host}}  {b.detail}")

domainhack/data/hack_words.json

@@ -0,0 +1,20 @@
+{
+  "_comment": "Words appended to a name to form a domain hack: name + word must end in a known TLD (sumanda + studio -> sumandastud.io). A word whose ending is not a known TLD is simply never used. Each word maps to the short meaning shown in the report.",
+  "studio": "a creative or production studio",
+  "radio": "a radio show or podcast",
+  "audio": "audio, music or sound",
+  "folio": "a portfolio",
+  "portfolio": "a portfolio of work",
+  "demo": "a demo or showcase",
+  "labs": "a lab or experiments",
+  "online": "an online presence",
+  "games": "games",
+  "apps": "apps",
+  "tech": "technology",
+  "design": "design",
+  "team": "the team",
+  "store": "a store or shop",
+  "house": "a house, home or venue",
+  "news": "news or a newsletter",
+  "zone": "a zone or community space"
+}