namecheap-python-sdk 0.1.0__py3-none-any.whl

namecheap_sdk/resources/__init__.py

@@ -0,0 +1,4 @@
+from .dns import DNS, AsyncDNS, relative_name, split_domain
+from .domains import AsyncDomains, Domains
+
+__all__ = ["DNS", "AsyncDNS", "Domains", "AsyncDomains", "relative_name", "split_domain"]

namecheap_sdk/resources/dns.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import ipaddress
+import xml.etree.ElementTree as ET
+from typing import Any, Callable, Iterable, Optional, Sequence, Union
+
+from .._base import Call, Flow
+from ..errors import APIError
+from ..messages import text
+from ..models import HOST_TYPES, DNSRecord, Hosts, RecordType, RecordTypeLike, hostname, record_type
+
+RecordValues = Union[str, DNSRecord, Iterable[Union[str, DNSRecord]]]
+Change = Callable[[list[DNSRecord]], tuple[list[DNSRecord], Any]]
+
+
+def domain_name(value: str) -> str:
+    name = value.strip().lower().rstrip(".")
+    if not name:
+        raise ValueError(text("value.empty_domain"))
+    return name
+
+
+def split_domain(value: str) -> tuple[str, str]:
+    name = domain_name(value)
+    if "." not in name:
+        raise ValueError(text("value.no_tld", domain=value))
+    sld, tld = name.split(".", 1)
+    return sld, tld
+
+
+def relative_name(name: str, domain: str) -> str:
+    value = name.strip().lower()
+    if not value:
+        raise ValueError(text("value.empty_name"))
+    if value in ("@", domain, f"{domain}."):
+        return "@"
+    bare = value.rstrip(".")
+    if bare.endswith(f".{domain}"):
+        return bare[: -len(domain) - 1]
+    if value.endswith("."):
+        raise ValueError(text("value.foreign_name", name=name, domain=domain))
+    return value
+
+
+def ip_record_type(ip: str) -> RecordType:
+    return RecordType.A if ipaddress.ip_address(ip).version == 4 else RecordType.AAAA
+
+
+def email_type(records: Sequence[DNSRecord], current: Optional[str], explicit: Optional[str]) -> Optional[str]:
+    if explicit:
+        return explicit.strip().upper()
+    kinds = {record.type for record in records}
+    if "MXE" in kinds:
+        return "MXE"
+    if "MX" in kinds:
+        return "MX"
+    if current and current not in ("MX", "MXE", "NONE"):
+        return current
+    return None
+
+
+def _same(kind: str, left: str, right: str) -> bool:
+    if kind in HOST_TYPES:
+        return left.rstrip(".").lower() == right.rstrip(".").lower()
+    return left == right
+
+
+class DNS:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _command(self, name: str) -> str:
+        return self._client.settings.command(name)
+
+    def _hosts_call(self, domain: str) -> Call:
+        sld, tld = split_domain(domain)
+        return Call(self._command("get_hosts"), {"SLD": sld, "TLD": tld}, parse=Hosts.from_xml)
+
+    def _ttl(self, value: Optional[int]) -> int:
+        ttl = self._client.settings.default_ttl if value is None else int(value)
+        if not 60 <= ttl <= 60000:
+            raise ValueError(text("value.ttl_range", ttl=ttl))
+        return ttl
+
+    def _prepare(self, zone: str, records: Iterable[DNSRecord]) -> list[DNSRecord]:
+        prepared = []
+        for record in records:
+            copy = DNSRecord(record.type, relative_name(record.name, zone), record.data, record.ttl, record.priority)
+            if copy.type in HOST_TYPES:
+                copy.data = hostname(copy.data)
+            if copy.ttl is not None:
+                self._ttl(copy.ttl)
+            prepared.append(copy)
+        return prepared
+
+    def _set_call(self, domain: str, records: Sequence[DNSRecord], mail: Optional[str]) -> Call:
+        sld, tld = split_domain(domain)
+        params: dict[str, Any] = {"SLD": sld, "TLD": tld}
+        for index, record in enumerate(records, start=1):
+            params[f"HostName{index}"] = record.name
+            params[f"RecordType{index}"] = record.type
+            params[f"Address{index}"] = record.data
+            params[f"TTL{index}"] = self._ttl(record.ttl)
+            if record.type in ("MX", "MXE"):
+                params[f"MXPref{index}"] = record.priority if record.priority is not None else 10
+        if mail:
+            params["EmailType"] = mail
+
+        def parse(element: ET.Element) -> None:
+            result = element.find("DomainDNSSetHostsResult")
+            if result is not None and result.get("IsSuccess", "true").lower() == "false":
+                raise APIError(text("error.not_saved", domain=domain), command=self._command("set_hosts"))
+
+        return Call(self._command("set_hosts"), params, parse=parse, write=True)
+
+    def _rewrite(self, domain: str, change: Change, mail: Optional[str] = None) -> Flow[Any]:
+        current: Hosts = yield self._hosts_call(domain)
+        before = list(current.records)
+        records, result = change(list(before))
+        wanted_mail = email_type(records, current.email_type, mail)
+        if records == before and (mail is None or wanted_mail == current.email_type):
+            return result
+        yield self._set_call(domain, records, wanted_mail)
+        return result
+
+    def hosts(self, domain: str) -> Any:
+        return self._client._execute(self._hosts_call(domain))
+
+    def list(self, domain: str, type: Optional[RecordTypeLike] = None, name: Optional[str] = None) -> Any:
+        zone = domain_name(domain)
+        kind = record_type(type) if type is not None else None
+        label = relative_name(name, zone) if name else None
+        call = self._hosts_call(zone)
+        call.parse = lambda element: [r for r in Hosts.from_xml(element).records
+                                      if (kind is None or r.type == kind) and (label is None or r.name == label)]
+        return self._client._execute(call)
+
+    def exists(self, domain: str, type: RecordTypeLike, name: str) -> Any:
+        zone, kind = domain_name(domain), record_type(type)
+        label = relative_name(name, zone)
+        call = self._hosts_call(zone)
+        call.parse = lambda element: any(r.type == kind and r.name == label for r in Hosts.from_xml(element).records)
+        return self._client._execute(call)
+
+    def add(self, domain: str, *records: DNSRecord, email_type: Optional[str] = None) -> Any:
+        if not records:
+            raise ValueError(text("value.add_needs_records"))
+        zone = domain_name(domain)
+        new = self._prepare(zone, records)
+
+        def change(current: list[DNSRecord]) -> tuple[list[DNSRecord], list[DNSRecord]]:
+            added = [r for r in new if not any(o.type == r.type and o.name == r.name and _same(r.type, o.data, r.data)
+                                               for o in current)]
+            return current + added, added
+
+        return self._client._drive(self._rewrite(zone, change, email_type))
+
+    def replace(
+        self, domain: str, type: RecordTypeLike, name: str, values: RecordValues, *, ttl: Optional[int] = None
+    ) -> Any:
+        zone, kind = domain_name(domain), record_type(type)
+        label = relative_name(name, zone)
+        if isinstance(values, (str, DNSRecord)):
+            values = [values]
+        wanted = [v if isinstance(v, DNSRecord) else DNSRecord(kind, label, str(v), ttl) for v in values]
+        if not wanted:
+            raise ValueError(text("value.no_values"))
+        for record in wanted:
+            record.type, record.name = kind, label
+            if record.ttl is None:
+                record.ttl = ttl
+        wanted = self._prepare(zone, wanted)
+
+        def change(current: list[DNSRecord]) -> tuple[list[DNSRecord], list[DNSRecord]]:
+            old = [r for r in current if r.type == kind and r.name == label]
+            for record in wanted:
+                match = next((o for o in old if _same(kind, o.data, record.data)), None)
+                if record.ttl is None and match is not None:
+                    record.ttl = match.ttl
+                if record.priority is None and match is not None:
+                    record.priority = match.priority
+            position = next((i for i, r in enumerate(current) if r.type == kind and r.name == label), len(current))
+            kept = [r for r in current if not (r.type == kind and r.name == label)]
+            index = min(position, len(kept))
+            return kept[:index] + wanted + kept[index:], wanted
+
+        return self._client._drive(self._rewrite(zone, change))
+
+    def replace_all(self, domain: str, records: Sequence[DNSRecord], *, email_type: Optional[str] = None) -> Any:
+        zone = domain_name(domain)
+        new = self._prepare(zone, records)
+        return self._client._drive(self._rewrite(zone, lambda current: (new, None), email_type))
+
+    def delete(self, domain: str, type: RecordTypeLike, name: str, data: Optional[str] = None) -> Any:
+        zone, kind = domain_name(domain), record_type(type)
+        label = relative_name(name, zone)
+
+        def gone(record: DNSRecord) -> bool:
+            return record.type == kind and record.name == label and (data is None or _same(kind, record.data, data))
+
+        def change(current: list[DNSRecord]) -> tuple[list[DNSRecord], int]:
+            kept = [r for r in current if not gone(r)]
+            return kept, len(current) - len(kept)
+
+        return self._client._drive(self._rewrite(zone, change))
+
+    def point(self, domain: str, name: str, ip: str, *, ttl: Optional[int] = None) -> Any:
+        address = str(ipaddress.ip_address(ip))
+        return self.replace(domain, ip_record_type(address), name, [address], ttl=ttl)
+
+    def unpoint(self, domain: str, name: str, ip_version: int = 4) -> Any:
+        return self.delete(domain, RecordType.A if ip_version == 4 else RecordType.AAAA, name)
+
+    def alias(self, domain: str, name: str, target: str, *, ttl: Optional[int] = None) -> Any:
+        return self.replace(domain, RecordType.CNAME, name, [target], ttl=ttl)
+
+    def set_txt(self, domain: str, name: str, values: Union[str, Iterable[str]], *, ttl: Optional[int] = None) -> Any:
+        return self.replace(domain, RecordType.TXT, name, values, ttl=ttl)
+
+
+class AsyncDNS(DNS):
+    pass

namecheap_sdk/resources/domains.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import Any, AsyncIterator, Iterable, Iterator, Optional
+
+from .._base import Call, Flow
+from ..messages import text
+from ..models import Availability, Domain, DomainInfo, Nameservers, Tld, flag, number
+from .dns import domain_name, split_domain
+
+
+def _page(element: ET.Element) -> tuple[list[Domain], int]:
+    rows = [Domain.from_xml(row) for row in element.iter("Domain")]
+    total = number(element.findtext("Paging/TotalItems")) or 0
+    return rows, total
+
+
+def _updated(tag: str, attribute: str) -> Any:
+    def parse(element: ET.Element) -> bool:
+        node = element.find(tag)
+        return flag(node.get(attribute)) if node is not None else True
+
+    return parse
+
+
+class _DomainsBase:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def _command(self, name: str) -> str:
+        return self._client.settings.command(name)
+
+    def _run(self, call: Call) -> Any:
+        return self._client._execute(call)
+
+    def _page_call(self, page: int, list_type: str, search: Optional[str], sort_by: Optional[str]) -> Call:
+        params = {"ListType": list_type.upper(), "SearchTerm": search, "SortBy": sort_by.upper() if sort_by else None,
+                  "Page": page, "PageSize": self._client.settings.page_size}
+        return Call(self._command("list_domains"), params, parse=_page)
+
+    def list(self, *, list_type: str = "ALL", search: Optional[str] = None, sort_by: Optional[str] = None) -> Any:
+        size = self._client.settings.page_size
+
+        def flow() -> Flow[list[Domain]]:
+            found: list[Domain] = []
+            page = 1
+            while True:
+                rows, total = yield self._page_call(page, list_type, search, sort_by)
+                found.extend(rows)
+                if not rows or page * size >= total:
+                    return found
+                page += 1
+
+        return self._client._drive(flow())
+
+    def get(self, domain: str) -> Any:
+        return self._run(Call(self._command("domain_info"), {"DomainName": domain_name(domain)},
+                              parse=DomainInfo.from_xml))
+
+    def available(self, domain: str) -> Any:
+        call = Call(self._command("check"), {"DomainList": domain_name(domain)},
+                    parse=lambda element: Availability.from_xml(next(element.iter("DomainCheckResult"))))
+        return self._run(call)
+
+    def available_many(self, domains: Iterable[str]) -> Any:
+        names = [domain_name(d) for d in domains]
+        if not names:
+            raise ValueError(text("value.no_domains"))
+        parse = lambda element: [Availability.from_xml(row) for row in element.iter("DomainCheckResult")]
+        return self._run(Call(self._command("check"), {"DomainList": names}, parse=parse))
+
+    def tlds(self) -> Any:
+        parse = lambda element: [Tld.from_xml(row) for row in element.iter("Tld")]
+        return self._run(Call(self._command("tlds"), parse=parse))
+
+    def nameservers(self, domain: str) -> Any:
+        sld, tld = split_domain(domain)
+        return self._run(Call(self._command("get_nameservers"), {"SLD": sld, "TLD": tld}, parse=Nameservers.from_xml))
+
+    def set_nameservers(self, domain: str, servers: Iterable[str]) -> Any:
+        names = [server.strip().rstrip(".") for server in servers if server.strip()]
+        if len(names) < 2:
+            raise ValueError(text("value.nameserver_count", count=len(names)))
+        sld, tld = split_domain(domain)
+        call = Call(self._command("set_custom_nameservers"), {"SLD": sld, "TLD": tld, "NameServers": names},
+                    parse=_updated("DomainDNSSetCustomResult", "Updated"))
+        return self._run(call)
+
+    def use_default_nameservers(self, domain: str) -> Any:
+        sld, tld = split_domain(domain)
+        call = Call(self._command("set_default_nameservers"), {"SLD": sld, "TLD": tld},
+                    parse=_updated("DomainDNSSetDefaultResult", "Updated"))
+        return self._run(call)
+
+    def is_locked(self, domain: str) -> Any:
+        call = Call(self._command("get_lock"), {"DomainName": domain_name(domain)},
+                    parse=_updated("DomainGetRegistrarLockResult", "RegistrarLockStatus"))
+        return self._run(call)
+
+    def lock(self, domain: str) -> Any:
+        return self._set_lock(domain, "LOCK")
+
+    def unlock(self, domain: str) -> Any:
+        return self._set_lock(domain, "UNLOCK")
+
+    def _set_lock(self, domain: str, action: str) -> Any:
+        call = Call(self._command("set_lock"), {"DomainName": domain_name(domain), "LockAction": action},
+                    parse=_updated("DomainSetRegistrarLockResult", "IsSuccess"))
+        return self._run(call)
+
+
+class Domains(_DomainsBase):
+    def iter(self, *, list_type: str = "ALL", search: Optional[str] = None,
+             sort_by: Optional[str] = None) -> Iterator[Domain]:
+        size = self._client.settings.page_size
+        page = 1
+        while True:
+            rows, total = self._client._execute(self._page_call(page, list_type, search, sort_by))
+            yield from rows
+            if not rows or page * size >= total:
+                return
+            page += 1
+
+
+class AsyncDomains(_DomainsBase):
+    async def iter(self, *, list_type: str = "ALL", search: Optional[str] = None,
+                   sort_by: Optional[str] = None) -> AsyncIterator[Domain]:
+        size = self._client.settings.page_size
+        page = 1
+        while True:
+            rows, total = await self._client._execute(self._page_call(page, list_type, search, sort_by))
+            for row in rows:
+                yield row
+            if not rows or page * size >= total:
+                return
+            page += 1