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

namecheap_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,354 @@
+Metadata-Version: 2.5
+Name: namecheap-python-sdk
+Version: 0.1.0
+Summary: A typed Python client for the Namecheap Domains and DNS API, sync and async.
+Project-URL: Homepage, https://theqiyas.cc
+Project-URL: Source, https://github.com/qiyascc/namecheap-python-sdk
+Project-URL: Issues, https://github.com/qiyascc/namecheap-python-sdk/issues
+Project-URL: Changelog, https://github.com/qiyascc/namecheap-python-sdk/blob/main/CHANGELOG.md
+Author-email: qiyascc <qiyasturk@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,dns,domains,namecheap,sdk,subdomain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: goodconf>=7.1
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: goodconf[toml]>=7.1; extra == 'dev'
+Requires-Dist: goodconf[yaml]>=7.1; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: toml
+Requires-Dist: goodconf[toml]>=7.1; extra == 'toml'
+Provides-Extra: yaml
+Requires-Dist: goodconf[yaml]>=7.1; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# namecheap-python-sdk
+
+A small, typed Python client for the Namecheap Domains and DNS API. It works with both sync and async code, turns Namecheap's XML into plain dataclasses, and makes the "replace everything" DNS API safe to use one record at a time.
+
+```python
+from namecheap_sdk import Namecheap
+
+with Namecheap("api_user", "API_KEY", client_ip="203.0.113.5") as nc:
+    nc.dns.point("example.com", "shop", "203.0.113.10")
+```
+
+That call makes `shop.example.com` resolve to `203.0.113.10` and leaves every other record of the domain as it was.
+
+## Install
+
+```bash
+pip install namecheap-python-sdk
+```
+
+Requires Python 3.10 or newer. Dependencies: [httpx](https://www.python-httpx.org/), [goodconf](https://github.com/lincolnloop/goodconf), pydantic and PyYAML. XML is parsed with the standard library.
+
+The import name is `namecheap_sdk`, so it does not clash with older `namecheap` packages.
+
+## Before you start
+
+1. Enable API access under Profile, Tools, Business & Dev Tools, Namecheap API Access. Namecheap only opens the production API to accounts that meet its requirements, so check that page if every call fails.
+2. Whitelist the IPv4 address of the machine that makes the calls on the same page. Every request carries that address as `ClientIp`, and calls from any other address are rejected with `AuthenticationError`.
+3. Try things in the sandbox first. It is a separate site, [sandbox.namecheap.com](https://www.sandbox.namecheap.com), with its own account, key and whitelist.
+
+## Configuration
+
+Settings are loaded with [goodconf](https://github.com/lincolnloop/goodconf), so you can configure the client from code, from environment variables or from a config file. Values passed in code win over the environment, and the environment wins over the file.
+
+```python
+nc = Namecheap("api_user", "API_KEY", client_ip="203.0.113.5")
+nc = Namecheap("api_user", "API_KEY", client_ip="203.0.113.5", environment="sandbox")
+```
+
+```bash
+export NAMECHEAP_API_USER=api_user
+export NAMECHEAP_API_KEY=...
+export NAMECHEAP_CLIENT_IP=203.0.113.5
+```
+
+```toml
+api_user = "api_user"
+api_key = "..."
+client_ip = "203.0.113.5"
+environment = "production"
+```
+
+With no arguments, the client looks for `namecheap.toml`, `namecheap.yaml`, `namecheap.yml` or `namecheap.json` in the working directory. To load a file from somewhere else, set `NAMECHEAP_CONFIG=/path/to/file`, or pass `config_file=` to the client. YAML files need the `yaml` extra, and TOML files on Python 3.10 need the `toml` extra:
+
+```bash
+pip install "namecheap-python-sdk[yaml]"
+```
+
+| Setting | Env variable | Default |
+| --- | --- | --- |
+| `api_user` | `NAMECHEAP_API_USER` | |
+| `api_key` | `NAMECHEAP_API_KEY` | |
+| `username` | `NAMECHEAP_USERNAME` | same as `api_user` |
+| `client_ip` | `NAMECHEAP_CLIENT_IP` | |
+| `environment` | `NAMECHEAP_ENVIRONMENT` | `production` |
+| `base_url` | `NAMECHEAP_BASE_URL` | taken from `environment` |
+| `production_url` | `NAMECHEAP_PRODUCTION_URL` | `https://api.namecheap.com/xml.response` |
+| `sandbox_url` | `NAMECHEAP_SANDBOX_URL` | `https://api.sandbox.namecheap.com/xml.response` |
+| `commands.*` | `NAMECHEAP_COMMANDS__<NAME>` | see below |
+| `timeout` | `NAMECHEAP_TIMEOUT` | `30` |
+| `max_retries` | `NAMECHEAP_MAX_RETRIES` | `3` |
+| `max_retry_wait` | `NAMECHEAP_MAX_RETRY_WAIT` | `60` |
+| `backoff_base` | `NAMECHEAP_BACKOFF_BASE` | `1` |
+| `backoff_cap` | `NAMECHEAP_BACKOFF_CAP` | `16` |
+| `page_size` | `NAMECHEAP_PAGE_SIZE` | `100` (the API allows 10 to 100) |
+| `default_ttl` | `NAMECHEAP_DEFAULT_TTL` | `1800` |
+| `user_agent` | `NAMECHEAP_USER_AGENT` | `namecheap-python-sdk/{version}` |
+
+`username` is the account the commands run on. It only differs from `api_user` when a reseller acts for a customer.
+
+### Commands
+
+Namecheap has one URL and picks the action from a `Command` parameter. The command names are part of the settings, so nothing is pinned in the code:
+
+| Name | Default |
+| --- | --- |
+| `get_hosts` | `namecheap.domains.dns.getHosts` |
+| `set_hosts` | `namecheap.domains.dns.setHosts` |
+| `get_nameservers` | `namecheap.domains.dns.getList` |
+| `set_custom_nameservers` | `namecheap.domains.dns.setCustom` |
+| `set_default_nameservers` | `namecheap.domains.dns.setDefault` |
+| `list_domains` | `namecheap.domains.getList` |
+| `domain_info` | `namecheap.domains.getInfo` |
+| `check` | `namecheap.domains.check` |
+| `tlds` | `namecheap.domains.getTldList` |
+| `get_lock` | `namecheap.domains.getRegistrarLock` |
+| `set_lock` | `namecheap.domains.setRegistrarLock` |
+| `balances` | `namecheap.users.getBalances` |
+
+## DNS
+
+These methods work while the domain uses Namecheap's own name servers (BasicDNS or PremiumDNS). Record names are relative to the domain and the apex is `@`. You can also pass a full name like `www.example.com`, it is turned into `www` for you.
+
+```python
+from namecheap_sdk import Namecheap, DNSRecord
+
+nc = Namecheap()
+
+nc.dns.list("example.com")
+nc.dns.list("example.com", "A")
+nc.dns.list("example.com", "A", "www")
+nc.dns.exists("example.com", "A", "shop")
+
+hosts = nc.dns.hosts("example.com")
+hosts.records, hosts.email_type, hosts.using_our_dns
+```
+
+Each record is a `DNSRecord`:
+
+```python
+DNSRecord(type='A', name='www', data='203.0.113.10', ttl=1800, priority=None, id=12, active=True)
+```
+
+### How changes are saved
+
+Namecheap's `setHosts` replaces the whole zone: any record left out of the call is deleted. So every change here reads the current records first, applies your change, and writes the full list back. If nothing actually changes, nothing is written. The mail setting (`EmailType`) is kept as it was, set to `MX` when the zone has MX records, or set to whatever you pass as `email_type=`.
+
+Two programs editing the same domain at the same moment can still overwrite each other, because the API has no locking. Keep DNS changes for one domain in one place.
+
+### Creating and changing records
+
+```python
+nc.dns.add(
+    "example.com",
+    DNSRecord.a("api", "203.0.113.20"),
+    DNSRecord.txt("@", "google-site-verification=abc"),
+    DNSRecord.mx("@", "mail.example.com", priority=10),
+    DNSRecord.caa("@", "letsencrypt.org"),
+)
+
+nc.dns.replace("example.com", "A", "www", ["203.0.113.10", "203.0.113.11"], ttl=600)
+
+nc.dns.delete("example.com", "A", "old")
+nc.dns.delete("example.com", "A", "www", data="203.0.113.11")
+
+nc.dns.replace_all("example.com", [DNSRecord.a("@", "203.0.113.10"), DNSRecord.cname("www", "example.com")])
+```
+
+`add` keeps everything and adds records that are not there yet. `replace` swaps every record with that type and name and keeps them in the same place in the zone. `delete` returns how many records it removed. `replace_all` writes exactly the list you pass.
+
+Namecheap also has its own redirect records, which other providers do not:
+
+```python
+nc.dns.add("example.com", DNSRecord.url("old", "https://example.com/new"))
+nc.dns.add("example.com", DNSRecord.url("tmp", "https://example.com", permanent=False))
+nc.dns.add("example.com", DNSRecord.frame("promo", "https://landing.example.net"))
+```
+
+TTL must be between 60 and 60000 seconds. Host names in `CNAME`, `ALIAS`, `NS` and `MX` records get their trailing dot, and `DNSRecord.caa("@", "letsencrypt.org")` becomes `0 issue "letsencrypt.org"`.
+
+### Shortcuts
+
+```python
+nc.dns.point("example.com", "shop", "203.0.113.10")
+nc.dns.point("example.com", "shop", "2001:db8::10")
+nc.dns.alias("example.com", "docs", "example.github.io")
+nc.dns.set_txt("example.com", "_acme-challenge", "token-value", ttl=60)
+nc.dns.unpoint("example.com", "shop")
+```
+
+`point` picks `A` or `AAAA` from the address you pass.
+
+### Example: one subdomain per customer
+
+```python
+from namecheap_sdk import Namecheap
+
+SERVER_IP = "203.0.113.10"
+
+def create_customer_site(slug: str) -> str:
+    with Namecheap() as nc:
+        if nc.dns.exists("example.com", "A", slug):
+            raise ValueError(f"{slug}.example.com is already taken")
+        nc.dns.point("example.com", slug, SERVER_IP, ttl=300)
+    return f"{slug}.example.com"
+```
+
+## Domains
+
+```python
+for domain in nc.domains.iter():
+    print(domain.name, domain.expires, domain.auto_renew)
+
+nc.domains.list(list_type="EXPIRING", sort_by="EXPIREDATE")
+nc.domains.list(search="shop")
+
+info = nc.domains.get("example.com")
+info.status, info.expires, info.whois_guard
+
+check = nc.domains.available("my-new-idea.com")
+if check.available and check.premium:
+    print(check.registration_price)
+
+nc.domains.available_many(["one.com", "two.net"])
+nc.domains.tlds()
+
+nc.domains.nameservers("example.com").servers
+nc.domains.set_nameservers("example.com", ["ns1.example.net", "ns2.example.net"])
+nc.domains.use_default_nameservers("example.com")
+
+nc.domains.is_locked("example.com")
+nc.domains.lock("example.com")
+nc.domains.unlock("example.com")
+
+nc.balances()
+```
+
+`use_default_nameservers` switches the domain back to Namecheap BasicDNS, which the DNS methods need.
+
+## Async
+
+`AsyncNamecheap` has the same methods. Await them.
+
+```python
+import asyncio
+from namecheap_sdk import AsyncNamecheap
+
+async def main():
+    async with AsyncNamecheap() as nc:
+        records = await nc.dns.list("example.com", "A")
+        await nc.dns.point("example.com", "shop", "203.0.113.10")
+        async for domain in nc.domains.iter():
+            print(domain.name)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Namecheap answers HTTP 200 even when a call fails and puts the error in the XML. The client turns those answers into exceptions. All of them inherit from `NamecheapError`.
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | wrong user or key, missing credentials, or a `ClientIp` that is not whitelisted |
+| `NotFoundError` | the domain is not found or not in this account (2019166, 2016166) |
+| `PermissionDeniedError` | the domain cannot be edited through the API (2030166) |
+| `ValidationError` | a parameter was rejected, for example too many records |
+| `RateLimitError` | Namecheap says there are too many requests |
+| `ServerError` | 5xx answers and errors from Namecheap's upstream registry |
+| `APIError` | any other error in the XML |
+| `APIConnectionError` / `APITimeoutError` | the request never got an answer |
+
+Errors carry Namecheap's error `number`, the full `errors` list, the `command` that failed and the raw `response`.
+
+```python
+from namecheap_sdk import NotFoundError
+
+try:
+    nc.dns.list("not-mine.com")
+except NotFoundError as exc:
+    print(exc.number, exc.message)
+```
+
+## Retries and timeouts
+
+Namecheap does not publish its limits in the API docs, and its support has quoted around 20 calls per minute, 700 per hour and 8,000 per day for a key. Too many calls come back as an error, which the client waits on and retries with exponential backoff, together with server errors and dropped connections. Every command this SDK sends can be repeated safely, because `setHosts` writes the full list each time.
+
+```python
+nc = Namecheap(timeout=10, max_retries=5)
+```
+
+Set `max_retries=0` to turn retries off. To use proxies or a custom transport, pass your own `httpx.Client` or `httpx.AsyncClient` as `http_client=`.
+
+## Messages
+
+Every error and validation message the SDK produces is stored in `namecheap_sdk/messages.yaml`, so none of them are hardcoded. You can replace some or all of them, for example to translate them:
+
+```yaml
+value:
+  empty_name: Record adı boş ola bilməz
+error:
+  timeout: "Sorğu vaxtı bitdi: {error}"
+```
+
+```python
+from namecheap_sdk import messages
+
+messages.use("messages.az.yaml")
+messages.use({"value.empty_name": "Record adı boş ola bilməz"})
+```
+
+Unknown keys raise `KeyError`, which catches typos early. Call `messages.reset()` to go back to the defaults.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The tests use `httpx.MockTransport`, so they never touch the real API.
+
+## Links
+
+- Source code: [github.com/qiyascc/namecheap-python-sdk](https://github.com/qiyascc/namecheap-python-sdk)
+- PyPI: [pypi.org/project/namecheap-python-sdk](https://pypi.org/project/namecheap-python-sdk/)
+- Author: [Qiyas Sadıqov](https://theqiyas.cc), more projects at [theqiyas.cc](https://theqiyas.cc)
+
+## License
+
+MIT

namecheap_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+namecheap_sdk/__init__.py,sha256=FUeNxbTX815BiMAnV8LlzCP5-xCdfa0W4j5lif27-ks,1032
+namecheap_sdk/_base.py,sha256=8YsVg6p2XZNAgLYyhy5SolrBbJDEIr6JVIVGrnagi1w,8054
+namecheap_sdk/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+namecheap_sdk/client.py,sha256=myETszCtvSdBfWN6TBFzWdwuMv2sExV6elYyarG7goI,954
+namecheap_sdk/config.py,sha256=zTqEr1fB3lnYIZGPyuSjNES8vQmy0LtTKNuNtkrjF_U,4400
+namecheap_sdk/errors.py,sha256=FmExbqjtwwuM5l3aFlUVVktP-dgSsLgFLgKv5L19giQ,4122
+namecheap_sdk/messages.py,sha256=Us_YoaNd64bApY58c9gbphy22V8IZ9SKmJOepMGo5WU,1635
+namecheap_sdk/messages.yaml,sha256=bCnfRsu6vhC6yZUT7mDi7Snk29NjAQzNwPrLp-9c7Ks,2286
+namecheap_sdk/models.py,sha256=9C9P_lRJCrI2gtZmVytlizuISM6OJLzENC6tDoPhNKo,10989
+namecheap_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+namecheap_sdk/resources/__init__.py,sha256=3Y8wYjChPxnydAf1oJfSz6Yrkn6jPZaSdJG_EB_8LDg,194
+namecheap_sdk/resources/dns.py,sha256=4kP_I45I7uJJ16Xxlw1D34DJDBB8SVwv2MTYCJJHXLs,9650
+namecheap_sdk/resources/domains.py,sha256=VLNBQoa8GXyp3ZzEIeZIuG0yWNa6mqpQX-kDlrzclR0,5738
+namecheap_python_sdk-0.1.0.dist-info/METADATA,sha256=vWiuSbakzkBrMb6FQ8tmJOrvz2kBk1Kv4VTySzA6rxk,13851
+namecheap_python_sdk-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+namecheap_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=ENVL-_Eh4n1SumZuLuTjO2K0OOL_eXh4pkeme35b02I,1064
+namecheap_python_sdk-0.1.0.dist-info/RECORD,,

namecheap_python_sdk-0.1.0.dist-info/WHEEL

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

namecheap_python_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qiyascc
+
+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.

namecheap_sdk/__init__.py

@@ -0,0 +1,47 @@
+from . import messages
+from ._version import __version__
+from .client import AsyncNamecheap, Namecheap
+from .config import Settings, load_settings
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APIErrorDetail,
+    APITimeoutError,
+    AuthenticationError,
+    NamecheapError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import Availability, Balances, DNSRecord, Domain, DomainInfo, Hosts, Nameservers, RecordType, Tld
+
+__all__ = [
+    "__version__",
+    "Namecheap",
+    "AsyncNamecheap",
+    "Settings",
+    "load_settings",
+    "messages",
+    "Availability",
+    "Balances",
+    "DNSRecord",
+    "Domain",
+    "DomainInfo",
+    "Hosts",
+    "Nameservers",
+    "RecordType",
+    "Tld",
+    "NamecheapError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIError",
+    "APIErrorDetail",
+    "ValidationError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

namecheap_sdk/_base.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from typing import Any, Callable, Generator, Mapping, Optional, TypeVar
+
+import httpx
+
+from .config import Settings, load_settings
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APIErrorDetail,
+    APITimeoutError,
+    RateLimitError,
+    ServerError,
+    from_details,
+    from_status,
+)
+from .messages import text
+
+T = TypeVar("T")
+
+def parse_xml(content: str) -> ET.Element:
+    try:
+        root = ET.fromstring(content)
+    except ET.ParseError as exc:
+        raise ServerError(text("error.bad_xml", error=exc)) from exc
+    for element in root.iter():
+        if isinstance(element.tag, str) and "}" in element.tag:
+            element.tag = element.tag.split("}", 1)[1]
+    return root
+
+
+@dataclass
+class Call:
+    command: str
+    params: Optional[Mapping[str, Any]] = None
+    parse: Callable[[ET.Element], Any] = lambda element: element
+    write: bool = False
+
+    def clean_params(self) -> dict[str, str]:
+        cleaned: dict[str, str] = {}
+        for key, value in (self.params or {}).items():
+            if value is None:
+                continue
+            if isinstance(value, bool):
+                cleaned[key] = "true" if value else "false"
+            elif isinstance(value, (list, tuple, set, frozenset)):
+                cleaned[key] = ",".join(str(v) for v in value)
+            else:
+                cleaned[key] = str(value)
+        return cleaned
+
+
+Flow = Generator[Call, Any, T]
+
+
+class BaseClient:
+    def __init__(
+        self,
+        api_user: Optional[str] = None,
+        api_key: Optional[str] = None,
+        *,
+        client_ip: Optional[str] = None,
+        settings: Optional[Settings] = None,
+        config_file: Optional[str] = None,
+        **overrides: Any,
+    ) -> None:
+        given = dict(overrides, api_user=api_user, api_key=api_key, client_ip=client_ip)
+        changes = {k: v for k, v in given.items() if v is not None}
+        if settings is None:
+            settings = load_settings(config_file, **changes)
+        elif changes:
+            settings = load_settings(None, **{**settings.model_dump(), **changes})
+
+        self.settings = settings
+        self._credentials = settings.require_credentials()
+        self.base_url = settings.resolved_base_url()
+        self.environment = settings.environment.lower()
+        self.timeout = settings.timeout
+        self.max_retries = settings.max_retries
+        self.max_retry_wait = settings.max_retry_wait
+        self.user_agent = settings.resolved_user_agent()
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(environment={self.environment!r}, base_url={self.base_url!r})"
+
+    def _headers(self) -> dict[str, str]:
+        return {"Accept": "application/xml", "User-Agent": self.user_agent}
+
+    def _request_args(self, call: Call) -> dict[str, Any]:
+        params = {**self._credentials, "Command": call.command, **call.clean_params()}
+        return {"data": params} if call.write else {"params": params}
+
+    def _wait_for(self, attempt: int, retry_after: Optional[float] = None) -> float:
+        if retry_after is not None:
+            return max(0.0, retry_after)
+        delay = self.settings.backoff_base * (2 ** attempt)
+        return min(self.settings.backoff_cap, delay) + random.uniform(0, self.settings.backoff_base / 2)
+
+    def _outcome(self, call: Call, response: httpx.Response) -> Any:
+        if response.status_code != 200:
+            raise from_status(response, call.command)
+        root = parse_xml(response.text)
+        if root.get("Status", "").upper() == "ERROR":
+            details = [APIErrorDetail(e.get("Number", ""), (e.text or "").strip())
+                       for e in root.iterfind("./Errors/Error")]
+            raise from_details(details, call.command, response)
+        found = root.find("CommandResponse")
+        return call.parse(found if found is not None else root)
+
+    def _retry_wait(self, error: Exception, attempt: int) -> Optional[float]:
+        if attempt >= self.max_retries:
+            return None
+        if isinstance(error, RateLimitError):
+            wait = self._wait_for(attempt, error.retry_after)
+            return wait if wait <= self.max_retry_wait else None
+        if isinstance(error, (ServerError, APIConnectionError)):
+            return self._wait_for(attempt)
+        return None
+
+    def _execute(self, call: Call) -> Any:
+        raise NotImplementedError
+
+    def _drive(self, flow: Flow[Any]) -> Any:
+        raise NotImplementedError
+
+
+class SyncClient(BaseClient):
+    def __init__(self, *args: Any, http_client: Optional[httpx.Client] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=self.timeout)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self: T) -> T:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def _send(self, call: Call) -> httpx.Response:
+        method = "POST" if call.write else "GET"
+        try:
+            return self._http.request(method, self.base_url, headers=self._headers(), **self._request_args(call))
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(text("error.timeout", error=exc)) from exc
+        except httpx.TransportError as exc:
+            raise APIConnectionError(text("error.connection", error=exc)) from exc
+
+    def _execute(self, call: Call) -> Any:
+        attempt = 0
+        while True:
+            try:
+                return self._outcome(call, self._send(call))
+            except (APIError, APIConnectionError) as error:
+                wait = self._retry_wait(error, attempt)
+                if wait is None:
+                    raise
+                time.sleep(wait)
+                attempt += 1
+
+    def _drive(self, flow: Flow[Any]) -> Any:
+        try:
+            call = next(flow)
+            while True:
+                call = flow.send(self._execute(call))
+        except StopIteration as stop:
+            return stop.value
+
+
+class AsyncClient(BaseClient):
+    def __init__(self, *args: Any, http_client: Optional[httpx.AsyncClient] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=self.timeout)
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self: T) -> T:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def _send(self, call: Call) -> httpx.Response:
+        method = "POST" if call.write else "GET"
+        try:
+            return await self._http.request(method, self.base_url, headers=self._headers(),
+                                            **self._request_args(call))
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(text("error.timeout", error=exc)) from exc
+        except httpx.TransportError as exc:
+            raise APIConnectionError(text("error.connection", error=exc)) from exc
+
+    async def _execute(self, call: Call) -> Any:
+        attempt = 0
+        while True:
+            try:
+                return self._outcome(call, await self._send(call))
+            except (APIError, APIConnectionError) as error:
+                wait = self._retry_wait(error, attempt)
+                if wait is None:
+                    raise
+                await asyncio.sleep(wait)
+                attempt += 1
+
+    async def _drive(self, flow: Flow[Any]) -> Any:
+        try:
+            call = next(flow)
+            while True:
+                call = flow.send(await self._execute(call))
+        except StopIteration as stop:
+            return stop.value
+
+
+__all__ = ["Call", "Flow", "SyncClient", "AsyncClient", "parse_xml"]

namecheap_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"