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

hostinger_sdk/_base.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Generator, Mapping, Optional, TypeVar
+
+import httpx
+
+from .config import Settings, load_settings
+from .errors import APIConnectionError, APITimeoutError, error_from_response, retry_after_from
+from .messages import text
+
+T = TypeVar("T")
+
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "PUT", "DELETE", "OPTIONS"})
+RETRY_STATUSES = frozenset({500, 502, 503, 504})
+
+
+@dataclass
+class Call:
+    method: str
+    path: str
+    params: Optional[Mapping[str, Any]] = None
+    json: Any = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+    parse: Callable[[Any], Any] = lambda body: body
+    allow_status: frozenset[int] = frozenset()
+
+    def clean_params(self) -> Optional[dict[str, Any]]:
+        if not self.params:
+            return None
+        cleaned: dict[str, Any] = {}
+        for key, value in self.params.items():
+            if value is None:
+                continue
+            cleaned[key] = ("true" if value else "false") if isinstance(value, bool) else value
+        return cleaned or None
+
+
+Flow = Generator[Call, Any, T]
+
+
+def _body_of(response: httpx.Response) -> Any:
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return response.text
+
+
+class BaseClient:
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        *,
+        settings: Optional[Settings] = None,
+        config_file: Optional[str] = None,
+        **overrides: Any,
+    ) -> None:
+        if settings is None:
+            settings = load_settings(config_file, api_token=token, **overrides)
+        elif token or overrides:
+            changes = {k: v for k, v in dict(overrides, api_token=token).items() if v is not None}
+            settings = load_settings(None, **{**settings.model_dump(), **changes})
+
+        self.settings = settings
+        self._token = settings.require_token()
+        self.base_url = settings.resolved_base_url()
+        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__}(base_url={self.base_url!r})"
+
+    def _default_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": self.user_agent,
+        }
+
+    def _url(self, path: str) -> str:
+        return path if path.startswith(("http://", "https://")) else self.base_url + path
+
+    def _can_retry(self, call: Call, attempt: int) -> bool:
+        return attempt < self.max_retries and call.method.upper() in IDEMPOTENT_METHODS
+
+    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 _decide(self, call: Call, response: httpx.Response, attempt: int) -> tuple[str, float]:
+        status = response.status_code
+        if status < 400 or status in call.allow_status:
+            return "done", 0.0
+        if status == 429 and attempt < self.max_retries:
+            wait = self._wait_for(attempt, retry_after_from(response))
+            if wait <= self.max_retry_wait:
+                return "retry", wait
+        if status in RETRY_STATUSES and self._can_retry(call, attempt):
+            return "retry", self._wait_for(attempt)
+        return "fail", 0.0
+
+    def _finish(self, call: Call, response: httpx.Response) -> Any:
+        if response.status_code in call.allow_status:
+            return call.parse(None)
+        return call.parse(_body_of(response))
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+        missing_ok: bool = False,
+    ) -> Any:
+        allow = frozenset({404}) if missing_ok else frozenset()
+        return self._execute(Call(method.upper(), path, params=params, json=json, allow_status=allow))
+
+    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 _execute(self, call: Call) -> Any:
+        headers = {**self._default_headers(), **call.headers}
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    call.method, self._url(call.path), params=call.clean_params(), json=call.json, headers=headers
+                )
+            except httpx.TimeoutException as exc:
+                if self._can_retry(call, attempt):
+                    time.sleep(self._wait_for(attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError(text("error.timeout", error=exc)) from exc
+            except httpx.TransportError as exc:
+                if self._can_retry(call, attempt):
+                    time.sleep(self._wait_for(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(text("error.connection", error=exc)) from exc
+
+            action, wait = self._decide(call, response, attempt)
+            if action == "done":
+                return self._finish(call, response)
+            if action == "retry":
+                time.sleep(wait)
+                attempt += 1
+                continue
+            raise error_from_response(response)
+
+    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 _execute(self, call: Call) -> Any:
+        headers = {**self._default_headers(), **call.headers}
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    call.method, self._url(call.path), params=call.clean_params(), json=call.json, headers=headers
+                )
+            except httpx.TimeoutException as exc:
+                if self._can_retry(call, attempt):
+                    await asyncio.sleep(self._wait_for(attempt))
+                    attempt += 1
+                    continue
+                raise APITimeoutError(text("error.timeout", error=exc)) from exc
+            except httpx.TransportError as exc:
+                if self._can_retry(call, attempt):
+                    await asyncio.sleep(self._wait_for(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(text("error.connection", error=exc)) from exc
+
+            action, wait = self._decide(call, response, attempt)
+            if action == "done":
+                return self._finish(call, response)
+            if action == "retry":
+                await asyncio.sleep(wait)
+                attempt += 1
+                continue
+            raise error_from_response(response)
+
+    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"]

hostinger_sdk/_version.py

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

hostinger_sdk/client.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import AsyncClient, SyncClient
+from .resources import DNS, AsyncDNS, AsyncDomains, Domains
+
+
+class Hostinger(SyncClient):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.domains = Domains(self)
+        self.dns = DNS(self)
+
+
+class AsyncHostinger(AsyncClient):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.domains = AsyncDomains(self)
+        self.dns = AsyncDNS(self)

hostinger_sdk/config.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import quote
+
+from goodconf import Field, GoodConf, GoodConfConfigDict
+from pydantic import BaseModel, SecretStr
+
+from ._version import __version__
+from .errors import AuthenticationError
+from .messages import text
+
+
+class Endpoints(BaseModel):
+    zone: str = "/api/dns/{version}/zones/{domain}"
+    zone_reset: str = "/api/dns/{version}/zones/{domain}/reset"
+    zone_validate: str = "/api/dns/{version}/zones/{domain}/validate"
+    snapshots: str = "/api/dns/{version}/snapshots/{domain}"
+    snapshot: str = "/api/dns/{version}/snapshots/{domain}/{snapshot_id}"
+    snapshot_restore: str = "/api/dns/{version}/snapshots/{domain}/{snapshot_id}/restore"
+    domains: str = "/api/domains/{version}/portfolio"
+    domain: str = "/api/domains/{version}/portfolio/{domain}"
+    availability: str = "/api/domains/{version}/availability"
+    nameservers: str = "/api/domains/{version}/portfolio/{domain}/nameservers"
+    domain_lock: str = "/api/domains/{version}/portfolio/{domain}/domain-lock"
+    privacy: str = "/api/domains/{version}/portfolio/{domain}/privacy-protection"
+    forwardings: str = "/api/domains/{version}/forwarding"
+    forwarding: str = "/api/domains/{version}/forwarding/{domain}"
+
+
+class Settings(GoodConf):
+    model_config = GoodConfConfigDict(
+        env_prefix="HOSTINGER_",
+        file_env_var="HOSTINGER_CONFIG",
+        default_files=["hostinger.toml", "hostinger.yaml", "hostinger.yml", "hostinger.json"],
+        extra="ignore",
+        env_nested_delimiter="__",
+    )
+
+    api_token: SecretStr = Field(default=SecretStr(""), description=text("settings.api_token"))
+    base_url: str = Field(default="https://developers.hostinger.com", description=text("settings.base_url"))
+    api_version: str = Field(default="v1", description=text("settings.api_version"))
+    endpoints: Endpoints = Field(default_factory=Endpoints, description=text("settings.endpoints"))
+    timeout: float = Field(default=30.0, gt=0, description=text("settings.timeout"))
+    max_retries: int = Field(default=3, ge=0, description=text("settings.max_retries"))
+    max_retry_wait: float = Field(default=60.0, ge=0, description=text("settings.max_retry_wait"))
+    backoff_base: float = Field(default=0.5, ge=0, description=text("settings.backoff_base"))
+    backoff_cap: float = Field(default=8.0, ge=0, description=text("settings.backoff_cap"))
+    default_ttl: int = Field(default=14400, ge=60, description=text("settings.default_ttl"))
+    user_agent: str = Field(default="hostinger-python-sdk/{version}", description=text("settings.user_agent"))
+
+    def resolved_base_url(self) -> str:
+        return self.base_url.rstrip("/")
+
+    def path(self, endpoint: str, **params: Any) -> str:
+        template = getattr(self.endpoints, endpoint)
+        values = {key: quote(str(value), safe="@") for key, value in params.items()}
+        return template.format(version=quote(self.api_version, safe=""), **values)
+
+    def resolved_user_agent(self) -> str:
+        return self.user_agent.replace("{version}", __version__)
+
+    def require_token(self) -> str:
+        token = self.api_token.get_secret_value().strip()
+        if not token:
+            raise AuthenticationError(text("error.missing_token"))
+        return token
+
+
+Settings.__doc__ = text("settings.description")
+
+
+def load_settings(config_file: Optional[str] = None, **overrides: Any) -> Settings:
+    given = {key: value for key, value in overrides.items() if value is not None}
+    return Settings(load=True, config_file=config_file, **given)

hostinger_sdk/errors.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from .messages import text
+
+
+@dataclass(frozen=True)
+class FieldError:
+    field: str
+    messages: tuple[str, ...]
+
+
+class HostingerError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        correlation_id: Optional[str] = None,
+        fields: Optional[list[FieldError]] = None,
+        response: Optional[httpx.Response] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.correlation_id = correlation_id
+        self.fields = fields or []
+        self.response = response
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code:
+            parts.append(f"[{self.status_code}]")
+        parts.append(self.message)
+        if self.fields:
+            parts.append("(" + "; ".join(f"{f.field}: {' '.join(f.messages)}" for f in self.fields) + ")")
+        if self.correlation_id:
+            parts.append(f"[correlation {self.correlation_id}]")
+        return " ".join(parts)
+
+
+class APIConnectionError(HostingerError):
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    pass
+
+
+class APIStatusError(HostingerError):
+    pass
+
+
+class ValidationError(APIStatusError):
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    pass
+
+
+class PermissionDeniedError(APIStatusError):
+    pass
+
+
+class NotFoundError(APIStatusError):
+    pass
+
+
+class ConflictError(APIStatusError):
+    pass
+
+
+class RateLimitError(APIStatusError):
+    def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(APIStatusError):
+    pass
+
+
+_STATUS_MAP: dict[int, type[APIStatusError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+def retry_after_from(response: httpx.Response, now: Optional[float] = None) -> Optional[float]:
+    header = response.headers.get("Retry-After")
+    if header:
+        try:
+            return max(0.0, float(header))
+        except ValueError:
+            pass
+    reset = response.headers.get("X-RateLimit-Reset")
+    if reset:
+        try:
+            value = float(reset)
+        except ValueError:
+            return None
+        current = now if now is not None else time.time()
+        return max(0.0, value - current) if value > 1_000_000_000 else max(0.0, value)
+    return None
+
+
+def _fields(body: Any) -> list[FieldError]:
+    errors = body.get("errors") if isinstance(body, dict) else None
+    if not isinstance(errors, dict):
+        return []
+    found = []
+    for name, messages in errors.items():
+        items = messages if isinstance(messages, list) else [messages]
+        found.append(FieldError(str(name), tuple(str(m) for m in items)))
+    return found
+
+
+def error_from_response(response: httpx.Response) -> APIStatusError:
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    if isinstance(body, dict):
+        found = body.get("message") or body.get("error")
+        message = str(found or response.reason_phrase or text("error.request_failed"))
+        correlation_id = body.get("correlation_id")
+    else:
+        message = response.text.strip() or response.reason_phrase or text("error.request_failed")
+        correlation_id = None
+
+    status = response.status_code
+    kwargs: dict[str, Any] = dict(status_code=status, correlation_id=correlation_id, fields=_fields(body),
+                                  response=response)
+
+    if status == 429:
+        return RateLimitError(message, retry_after=retry_after_from(response), **kwargs)
+    if status >= 500:
+        return ServerError(message, **kwargs)
+    return _STATUS_MAP.get(status, APIStatusError)(message, **kwargs)

hostinger_sdk/messages.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+
+PathLike = Union[str, Path]
+
+_PACKAGE_FILE = "messages.yaml"
+_catalog: dict[str, str] = {}
+
+
+def _flatten(node: Mapping[str, Any], prefix: str = "") -> dict[str, str]:
+    flat: dict[str, str] = {}
+    for key, value in node.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, Mapping):
+            flat.update(_flatten(value, f"{path}."))
+        else:
+            flat[path] = str(value)
+    return flat
+
+
+def _parse(raw: str) -> dict[str, str]:
+    data = yaml.safe_load(raw) or {}
+    if not isinstance(data, Mapping):
+        raise ValueError("messages file must contain a mapping")
+    return _flatten(data)
+
+
+def _read_packaged() -> dict[str, str]:
+    raw = resources.files(__package__).joinpath(_PACKAGE_FILE).read_text(encoding="utf-8")
+    return _parse(raw)
+
+
+def catalog() -> Mapping[str, str]:
+    if not _catalog:
+        _catalog.update(_read_packaged())
+    return _catalog
+
+
+def use(source: PathLike | Mapping[str, Any]) -> None:
+    if isinstance(source, Mapping):
+        overrides = _flatten(source)
+    else:
+        overrides = _parse(Path(source).read_text(encoding="utf-8"))
+    unknown = set(overrides) - set(_read_packaged())
+    if unknown:
+        raise KeyError(", ".join(sorted(unknown)))
+    catalog()
+    _catalog.update(overrides)
+
+
+def reset() -> None:
+    _catalog.clear()
+
+
+def text(key: str, **params: Any) -> str:
+    template = catalog()[key]
+    return template.format(**params) if params else template

hostinger_sdk/messages.yaml

@@ -0,0 +1,28 @@
+settings:
+  description: Settings for the Hostinger API client.
+  api_token: API token from hpanel.hostinger.com/profile/api.
+  base_url: API URL without any path.
+  api_version: API version that fills the {version} part of every endpoint.
+  endpoints: Path templates for every API call, relative to the base URL.
+  timeout: Seconds to wait for a single request.
+  max_retries: How many times a failed request is tried again.
+  max_retry_wait: Longest wait in seconds the client accepts from a rate limit answer.
+  backoff_base: First backoff delay in seconds, doubled on every retry.
+  backoff_cap: Longest backoff delay in seconds.
+  default_ttl: TTL in seconds used for new records when none is given.
+  user_agent: User-Agent header. {version} is replaced with the package version.
+error:
+  request_failed: Request failed
+  missing_token: Missing token. Pass token, set HOSTINGER_API_TOKEN, or point HOSTINGER_CONFIG at a config file.
+  timeout: 'Request timed out: {error}'
+  connection: 'Connection failed: {error}'
+value:
+  empty_domain: domain must not be empty
+  empty_name: record name must not be empty, use '@' for the apex
+  empty_type: record type must not be empty
+  no_values: at least one record value is required
+  add_needs_records: add() needs at least one DNSRecord
+  foreign_name: '{name!r} is not inside {domain}'
+  nameserver_count: a domain needs between 2 and 4 name servers, got {count}
+  no_tlds: available() needs at least one TLD
+  redirect_type: redirect type must be 301 or 302, got {value!r}