namedaemon 0.1.0__py3-none-any.whl

namedaemon/__init__.py

@@ -0,0 +1,12 @@
+"""Client and CLI for NameDaemon (https://namedaemon.com)."""
+
+__version__ = "0.1.0"
+
+from .client import (  # noqa: E402
+    DEFAULT_BASE_URL,
+    NameDaemon,
+    NameDaemonError,
+    RateLimitError,
+)
+
+__all__ = ["NameDaemon", "NameDaemonError", "RateLimitError", "DEFAULT_BASE_URL", "__version__"]

namedaemon/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

namedaemon/cli.py

@@ -0,0 +1,79 @@
+"""Command line: ``namedaemon rate example`` or ``python -m namedaemon rate example``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, List, Optional
+
+from . import __version__
+from .client import NameDaemon, NameDaemonError, RateLimitError
+
+
+def _pretty(cmd: str, r: Any) -> str:
+    if cmd == "rate":
+        line = f"{r['name']}: {r['score'] if r.get('score') is not None else 'no score'} {r.get('verdict') or ''}".strip()
+        tips = r.get("tips") or []
+        return line + ("\n- " + "\n- ".join(tips) if tips else "")
+    if cmd == "ideas":
+        return "\n".join(f"{i['domain']}.com  {i['score']}" for i in r["ideas"])
+    if cmd in ("check", "verify", "tld"):
+        return "\n".join(
+            f"{x['domain']}  {x['status']}" + (f" (drops {x['est_drop']})" if x.get("est_drop") else "")
+            for x in r["results"]
+        )
+    return json.dumps(r, indent=2)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="namedaemon", description="NameDaemon .com domain tools (https://namedaemon.com)")
+    p.add_argument("--version", action="version", version=f"namedaemon {__version__}")
+    p.add_argument("--json", action="store_true", help="print the raw JSON response")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("rate", help="brandability score for one name").add_argument("name")
+    ideas = sub.add_parser("ideas", help="two-word .com ideas around a keyword")
+    ideas.add_argument("keyword")
+    ideas.add_argument("limit", nargs="?", type=int)
+    sub.add_parser("check", help="status of up to 50 names").add_argument("names", nargs="+")
+    sub.add_parser("verify", help="live availability of up to 10 names").add_argument("names", nargs="+")
+    tld = sub.add_parser("tld", help="one label across several extensions")
+    tld.add_argument("label")
+    tld.add_argument("tlds", nargs="+")
+    sub.add_parser("tco", help="cost of ownership for an extension").add_argument("tld")
+    sub.add_parser("health", help="DNS, email and registration health").add_argument("name")
+    sub.add_parser("appraise", help="strength report (no price)").add_argument("name")
+    sub.add_parser("handles", help="username availability on social platforms").add_argument("name")
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    nd = NameDaemon()
+    try:
+        if args.cmd == "rate":
+            res = nd.rate(args.name)
+        elif args.cmd == "ideas":
+            res = nd.ideas(args.keyword, args.limit)
+        elif args.cmd == "check":
+            res = nd.check(args.names)
+        elif args.cmd == "verify":
+            res = nd.verify(args.names)
+        elif args.cmd == "tld":
+            res = nd.tld_check(args.label, args.tlds)
+        elif args.cmd == "tco":
+            res = nd.tco(args.tld)
+        elif args.cmd == "health":
+            res = nd.domain_health(args.name)
+        elif args.cmd == "appraise":
+            res = nd.appraise(args.name)
+        else:
+            res = nd.handles(args.name)
+    except RateLimitError as e:
+        print(f"Rate limit reached. Try again in about {e.retry_after} seconds.", file=sys.stderr)
+        return 1
+    except NameDaemonError as e:
+        print(f"Error{' ' + str(e.status) if e.status else ''}: {e.message}", file=sys.stderr)
+        return 1
+    print(json.dumps(res, indent=2) if args.json else _pretty(args.cmd, res))
+    return 0

namedaemon/client.py

@@ -0,0 +1,194 @@
+"""NameDaemon client for the public REST layer (https://namedaemon.com/wp-json/nd/v1).
+
+Standard library only (urllib), so it installs with no dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, Optional, Sequence, Union
+
+from . import __version__
+
+DEFAULT_BASE_URL = "https://namedaemon.com/wp-json/nd/v1"
+
+Json = Dict[str, Any]
+
+
+class NameDaemonError(Exception):
+    """Any failed request. `status` is 0 for network errors."""
+
+    def __init__(self, message: str, status: int = 0, code: str = "", body: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+
+
+class RateLimitError(NameDaemonError):
+    """HTTP 429: the shared limit was hit. `retry_after` is in seconds."""
+
+    def __init__(self, message: str, retry_after: int = 60, **kw: Any):
+        super().__init__(message, status=429, **kw)
+        self.retry_after = retry_after
+
+
+def _clean(params: Optional[Dict[str, Any]]) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for k, v in (params or {}).items():
+        if v is None or v == "":
+            continue
+        if isinstance(v, bool):
+            v = "true" if v else "false"
+        elif isinstance(v, (list, tuple)):
+            v = ",".join(str(x) for x in v)
+        out[k] = str(v)
+    return out
+
+
+class NameDaemon:
+    """Client for the public NameDaemon API.
+
+    >>> nd = NameDaemon()
+    >>> nd.rate("example")["score"]
+    95.5
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 20.0,
+        retries: int = 0,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = retries
+        self.user_agent = user_agent or f"namedaemon-py/{__version__}"
+
+    # -- transport ---------------------------------------------------------
+    def _request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None, body: Any = None) -> Json:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        query = urllib.parse.urlencode(_clean(params))
+        if query:
+            url += "?" + query
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    raw = resp.read().decode("utf-8", "replace")
+                    status = resp.status
+                    hdrs = resp.headers
+            except urllib.error.HTTPError as e:
+                raw = e.read().decode("utf-8", "replace")
+                status = e.code
+                hdrs = e.headers
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                raise NameDaemonError(f"Network error: {e}") from e
+
+            try:
+                parsed = json.loads(raw) if raw else None
+            except ValueError:
+                parsed = None
+
+            if 200 <= status < 300:
+                if parsed is None:
+                    raise NameDaemonError("Response was not JSON", status=status)
+                return parsed
+
+            message = (parsed or {}).get("message") if isinstance(parsed, dict) else None
+            code = (parsed or {}).get("code", "") if isinstance(parsed, dict) else ""
+            message = message or f"HTTP {status}"
+            if status == 429:
+                try:
+                    retry_after = int(hdrs.get("Retry-After", "")) if hdrs else 60
+                except (TypeError, ValueError):
+                    retry_after = 60
+                if retry_after <= 0:
+                    retry_after = 60
+                if attempt < self.retries:
+                    attempt += 1
+                    time.sleep(min(retry_after, 60))
+                    continue
+                raise RateLimitError(message, retry_after=retry_after, code=code, body=parsed)
+            raise NameDaemonError(message, status=status, code=code, body=parsed)
+
+    def get(self, path: str, **params: Any) -> Json:
+        """Any public GET route, e.g. ``nd.get("trend", keyword="ai")``."""
+        return self._request("GET", path, params)
+
+    def post(self, path: str, body: Any) -> Json:
+        """Any public POST route with a JSON body."""
+        return self._request("POST", path, body=body)
+
+    # -- tools -------------------------------------------------------------
+    def rate(self, name: str) -> Json:
+        """Brandability score and breakdown for one name (4-24 letters)."""
+        return self.get("rate", name=name)
+
+    def ideas(self, q: str, limit: Optional[int] = None) -> Json:
+        """Two-word .com ideas built around a keyword (3-14 letters)."""
+        return self.get("ideas", q=q, limit=limit)
+
+    def verify(self, domains: Sequence[str]) -> Json:
+        """Live availability of up to 10 names."""
+        return self.post("verify", {"domains": list(domains)})
+
+    def check(self, domains: Sequence[str], verify: int = 0) -> Json:
+        """Zone status of up to 50 names, with optional live checks (0-10)."""
+        return self.post("check", {"domains": list(domains), "verify": verify})
+
+    def tld_check(self, label: str, tlds: Union[str, Iterable[str]]) -> Json:
+        """One label across up to 12 extensions."""
+        return self.get("tld-check", label=label, tlds=tlds if isinstance(tlds, str) else list(tlds))
+
+    def tco(self, tld: Optional[str] = None, **options: Any) -> Json:
+        """Cost of ownership for an extension, or a ranking with q/scope/sort/limit."""
+        return self.get("tco", tld=tld, **options)
+
+    def hacks(self, **options: Any) -> Json:
+        """Domain hacks (e.g. hack.er). Pass word=... or keyword=... and mode=..."""
+        return self.get("hacks", **options)
+
+    def names(self, seeds: Union[str, Iterable[str]], **options: Any) -> Json:
+        """Brand-name generator: seeds plus vibe, min_len, max_len, count, variation, hide_taken."""
+        return self.get("names", seeds=seeds if isinstance(seeds, str) else list(seeds), **options)
+
+    def domain_health(self, name: str) -> Json:
+        """Registration, DNS, email and blocklist checks for a .com label."""
+        return self.get("domain-health", name=name)
+
+    def appraise(self, name: str, deep: bool = False) -> Json:
+        """Strength report for a name (no price)."""
+        return self.get("appraise", name=name, deep=True if deep else None)
+
+    def handles(self, name: str) -> Json:
+        """Username availability on social platforms."""
+        return self.get("handles", name=name)
+
+    def web3(self, name: str) -> Json:
+        """ENS and Solana name availability."""
+        return self.get("web3", name=name)
+
+    def screen(self, name: str) -> Json:
+        """Name screening: unwanted meanings in other languages."""
+        return self.get("screen", name=name)
+
+    def hosting(self, mode: Optional[str] = None, q: Optional[str] = None) -> Json:
+        """Hosting provider ranking (mode: top, provider or domain)."""
+        return self.get("hosting", mode=mode, q=q)
+
+    def trend(self, keyword: str) -> Json:
+        """Daily size history for a keyword in the .com zone."""
+        return self.get("trend", keyword=keyword)

namedaemon-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: namedaemon
+Version: 0.1.0
+Summary: Client and CLI for NameDaemon: .com domain availability, brandability scores, name ideas, TLD costs and domain health.
+Project-URL: Homepage, https://namedaemon.com
+Project-URL: Repository, https://github.com/krasenslavov/namedaemon-pypi
+Project-URL: Issues, https://github.com/krasenslavov/namedaemon-pypi/issues
+Project-URL: Changelog, https://github.com/krasenslavov/namedaemon-pypi/blob/main/CHANGELOG.md
+Author: Krasen Slavov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brand-name,dns,domain,domain-availability,domain-name,name-generator,namedaemon,rdap,tld,whois
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# namedaemon
+
+Python client and command-line tool for [NameDaemon](https://namedaemon.com), a free set of .com domain tools: availability,
+brandability scores, name ideas, extension costs, domain health and more. No API key, no dependencies.
+
+```
+pip install namedaemon
+```
+
+Needs Python 3.9 or newer.
+
+## Command line
+
+```
+namedaemon rate example
+namedaemon ideas nova 10
+namedaemon check nova novax mybrand
+namedaemon tld nova com io ai
+namedaemon tco io
+namedaemon health example
+namedaemon --json appraise example
+```
+
+`python -m namedaemon ...` works too. `--json` (before the command) prints the raw response.
+
+## Library
+
+```python
+from namedaemon import NameDaemon
+
+nd = NameDaemon()
+
+r = nd.rate("example")
+print(r["score"], r["verdict"])  # 95.5 Excellent
+
+ideas = nd.ideas("nova", limit=10)["ideas"]
+results = nd.check(["nova", "novax"])["results"]
+cost = nd.tco("io", years=5)
+health = nd.domain_health("example")
+```
+
+| Method | What it returns |
+|---|---|
+| `rate(name)` | brandability score, verdict, breakdown, tips |
+| `ideas(keyword, limit=None)` | two-word .com ideas built around a keyword |
+| `check(names, verify=0)` | zone status of up to 50 names, optional live checks |
+| `verify(names)` | live availability of up to 10 names |
+| `tld_check(label, tlds)` | one label across up to 12 extensions |
+| `tco(tld, **options)` | registration, renewal and total cost by registrar |
+| `hacks(word=...)` | domain hacks such as `hack.er` |
+| `names(seeds, vibe=..., count=...)` | brand-name generator |
+| `domain_health(name)` | registration, DNS, email and blocklist checks |
+| `appraise(name, deep=False)` | strength report (no price) |
+| `handles(name)` | username availability on social platforms |
+| `web3(name)`, `screen(name)`, `hosting()`, `trend(keyword)` | ENS/Solana names, name screening, hosting share, keyword trend |
+| `get(path, **params)`, `post(path, body)` | any other public route under `/wp-json/nd/v1/` |
+
+Every method returns the parsed JSON of the matching REST route. The package is typed (`py.typed`).
+
+### Errors and rate limits
+
+The public API is free and shared, so it limits each visitor to roughly 20 requests a minute. Heavier routes count for more.
+When the limit is hit the client raises `RateLimitError` (with `retry_after` in seconds, 60 by default); pass `retries=1` to wait
+and retry automatically. Other failures raise `NameDaemonError` with `status`, `code` and the server's `message`.
+
+```python
+from namedaemon import NameDaemon, RateLimitError
+
+nd = NameDaemon(timeout=20, retries=1)
+try:
+    nd.rate("example")
+except RateLimitError as e:
+    print(e.retry_after)
+```
+
+Please keep usage reasonable. For bulk work, see the paid plan at https://namedaemon.com.
+
+## Links
+
+- Website and free tools: https://namedaemon.com
+- Issues: https://github.com/krasenslavov/namedaemon-pypi/issues
+- JavaScript version: `npm install namedaemon`
+
+MIT license.

namedaemon-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+namedaemon/__init__.py,sha256=ym1XFq0EDBQWisq_73XNtxuxNelZ2wWWROCeBzqkuMY,301
+namedaemon/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+namedaemon/cli.py,sha256=HAoireMU0cuOTlduvz6DDMVSzznls23G_6DpQehrLEI,3500
+namedaemon/client.py,sha256=P1SfzxHvKZeTveJECw5p06pFJEkttdbdz_50U61ahEc,7654
+namedaemon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+namedaemon-0.1.0.dist-info/METADATA,sha256=TfMiQONbzyZaPLET9bGJGvnzIl46pO9NxtIu18OkhJM,3930
+namedaemon-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+namedaemon-0.1.0.dist-info/entry_points.txt,sha256=jyG_WeD02SO_j8cC1VFA5aFp6ffB7nJmZHDMcdMTxBs,51
+namedaemon-0.1.0.dist-info/licenses/LICENSE,sha256=JIVhApflbNrYfPfaWhUkCv5JDFadsz1Fbkv9O9i6-n0,1070
+namedaemon-0.1.0.dist-info/RECORD,,

namedaemon-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

namedaemon-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+namedaemon = namedaemon.cli:main

namedaemon-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krasen Slavov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.