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

digitalocean_sdk/client.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import AsyncClient, Call, SyncClient
+from .models import Account
+from .resources import DNS, AsyncDNS, AsyncDomains, Domains
+
+
+def _account(body: Any) -> Account:
+    return Account.from_api((body or {}).get("account") or {})
+
+
+class DigitalOcean(SyncClient):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.domains = Domains(self)
+        self.dns = DNS(self)
+
+    def account(self) -> Account:
+        result: Account = self._execute(Call("GET", self.settings.path("account"), parse=_account))
+        return result
+
+
+class AsyncDigitalOcean(AsyncClient):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.domains = AsyncDomains(self)
+        self.dns = AsyncDNS(self)
+
+    async def account(self) -> Account:
+        result: Account = await self._execute(Call("GET", self.settings.path("account"), parse=_account))
+        return result

digitalocean_sdk/config.py

@@ -0,0 +1,67 @@
+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):
+    account: str = "/{version}/account"
+    domains: str = "/{version}/domains"
+    domain: str = "/{version}/domains/{domain}"
+    records: str = "/{version}/domains/{domain}/records"
+    record: str = "/{version}/domains/{domain}/records/{record_id}"
+
+
+class Settings(GoodConf):
+    model_config = GoodConfConfigDict(
+        env_prefix="DIGITALOCEAN_",
+        file_env_var="DIGITALOCEAN_CONFIG",
+        default_files=["digitalocean.toml", "digitalocean.yaml", "digitalocean.yml", "digitalocean.json"],
+        extra="ignore",
+        env_nested_delimiter="__",
+    )
+
+    token: SecretStr = Field(default=SecretStr(""), description=text("settings.token"))
+    base_url: str = Field(default="https://api.digitalocean.com", description=text("settings.base_url"))
+    api_version: str = Field(default="v2", 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"))
+    page_size: int = Field(default=200, ge=1, le=200, description=text("settings.page_size"))
+    default_ttl: int = Field(default=1800, ge=30, description=text("settings.default_ttl"))
+    user_agent: str = Field(default="digitalocean-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.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)

digitalocean_sdk/errors.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .messages import text
+
+
+class DigitalOceanError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        response: Optional[httpx.Response] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.response = response
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code:
+            parts.append(f"[{self.status_code}]")
+        if self.code:
+            parts.append(self.code)
+        parts.append(self.message)
+        if self.request_id:
+            parts.append(f"(request {self.request_id})")
+        return " ".join(parts)
+
+
+class APIConnectionError(DigitalOceanError):
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    pass
+
+
+class APIStatusError(DigitalOceanError):
+    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("ratelimit-reset")
+    if reset:
+        try:
+            return max(0.0, float(reset) - (now if now is not None else time.time()))
+        except ValueError:
+            return None
+    return None
+
+
+def error_from_response(response: httpx.Response) -> APIStatusError:
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    if isinstance(body, dict):
+        message = str(body.get("message") or response.reason_phrase or text("error.request_failed"))
+        code = body.get("id")
+        request_id = body.get("request_id") or response.headers.get("x-request-id")
+    else:
+        message = response.text.strip() or response.reason_phrase or text("error.request_failed")
+        code = None
+        request_id = response.headers.get("x-request-id")
+
+    status = response.status_code
+    kwargs: dict[str, Any] = dict(status_code=status, code=code, request_id=request_id, 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)

digitalocean_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

digitalocean_sdk/messages.yaml

@@ -0,0 +1,28 @@
+settings:
+  description: Settings for the DigitalOcean API client.
+  token: Personal access token from cloud.digitalocean.com/account/api/tokens.
+  base_url: API URL without the version part.
+  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.
+  page_size: Items asked for on every page when listing, between 1 and 200.
+  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 DIGITALOCEAN_TOKEN, or point DIGITALOCEAN_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
+  update_needs_fields: update() needs at least one field to change
+  needs_id: record {name!r} has no id, fetch it from the API first
+  foreign_name: '{name!r} is not inside {domain}'

digitalocean_sdk/models.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Union
+
+from .messages import text
+
+
+class RecordType(str, Enum):
+    A = "A"
+    AAAA = "AAAA"
+    CAA = "CAA"
+    CNAME = "CNAME"
+    MX = "MX"
+    NS = "NS"
+    SOA = "SOA"
+    SRV = "SRV"
+    TXT = "TXT"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+RecordTypeLike = Union[RecordType, str]
+HOST_TYPES = frozenset({"CNAME", "MX", "NS", "SRV"})
+
+
+def record_type(value: RecordTypeLike) -> str:
+    kind = value.value if isinstance(value, RecordType) else str(value).strip().upper()
+    if not kind:
+        raise ValueError(text("value.empty_type"))
+    return kind
+
+
+def hostname(value: str) -> str:
+    host = value.strip()
+    if host == "@" or host.endswith(".") or "." not in host:
+        return host
+    return f"{host}."
+
+
+@dataclass
+class DNSRecord:
+    type: str
+    name: str
+    data: str
+    ttl: Optional[int] = None
+    priority: Optional[int] = None
+    port: Optional[int] = None
+    weight: Optional[int] = None
+    flags: Optional[int] = None
+    tag: Optional[str] = None
+    id: Optional[int] = field(default=None, compare=False)
+
+    def __post_init__(self) -> None:
+        self.type = record_type(self.type)
+        self.name = self.name.strip() or "@"
+
+    @classmethod
+    def a(cls, name: str, ip: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("A", name, str(ipaddress.IPv4Address(ip)), ttl)
+
+    @classmethod
+    def aaaa(cls, name: str, ip: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("AAAA", name, str(ipaddress.IPv6Address(ip)), ttl)
+
+    @classmethod
+    def cname(cls, name: str, target: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("CNAME", name, hostname(target), ttl)
+
+    @classmethod
+    def txt(cls, name: str, value: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("TXT", name, value, ttl)
+
+    @classmethod
+    def mx(cls, name: str, host: str, priority: int = 10, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("MX", name, hostname(host), ttl, priority=priority)
+
+    @classmethod
+    def ns(cls, name: str, host: str, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("NS", name, hostname(host), ttl)
+
+    @classmethod
+    def srv(
+        cls, name: str, target: str, port: int, priority: int = 10, weight: int = 5, ttl: Optional[int] = None
+    ) -> DNSRecord:
+        return cls("SRV", name, hostname(target), ttl, priority=priority, port=port, weight=weight)
+
+    @classmethod
+    def caa(cls, name: str, value: str, tag: str = "issue", flags: int = 0, ttl: Optional[int] = None) -> DNSRecord:
+        return cls("CAA", name, value, ttl, flags=flags, tag=tag)
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> DNSRecord:
+        return cls(
+            type=str(data.get("type", "")),
+            name=str(data.get("name", "@")),
+            data=str(data.get("data", "")),
+            ttl=data.get("ttl"),
+            priority=data.get("priority"),
+            port=data.get("port"),
+            weight=data.get("weight"),
+            flags=data.get("flags"),
+            tag=data.get("tag"),
+            id=data.get("id"),
+        )
+
+    def to_api(self, default_ttl: Optional[int] = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"type": self.type, "name": self.name, "data": self.data}
+        ttl = self.ttl if self.ttl is not None else default_ttl
+        if ttl is not None:
+            body["ttl"] = ttl
+        for key in ("priority", "port", "weight", "flags", "tag"):
+            value = getattr(self, key)
+            if value is not None:
+                body[key] = value
+        return body
+
+    def fqdn(self, domain: str) -> str:
+        return domain if self.name == "@" else f"{self.name}.{domain}"
+
+
+@dataclass
+class Domain:
+    name: str
+    ttl: Optional[int] = None
+    zone_file: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Domain:
+        return cls(name=str(data.get("name", "")), ttl=data.get("ttl"), zone_file=data.get("zone_file"))
+
+
+@dataclass
+class Account:
+    email: str
+    uuid: str
+    status: str
+    email_verified: bool = False
+    droplet_limit: Optional[int] = None
+    floating_ip_limit: Optional[int] = None
+    team: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Account:
+        team = data.get("team") if isinstance(data.get("team"), dict) else {}
+        return cls(
+            email=str(data.get("email", "")),
+            uuid=str(data.get("uuid", "")),
+            status=str(data.get("status", "")),
+            email_verified=bool(data.get("email_verified", False)),
+            droplet_limit=data.get("droplet_limit"),
+            floating_ip_limit=data.get("floating_ip_limit"),
+            team=team.get("name") if team else None,
+        )

digitalocean_sdk/resources/__init__.py

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

digitalocean_sdk/resources/_paging.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Optional
+
+from .._base import Call, Flow
+
+
+def has_next(body: Any) -> bool:
+    if not isinstance(body, dict):
+        return False
+    pages = (body.get("links") or {}).get("pages") or {}
+    return bool(pages.get("next"))
+
+
+def page_call(path: str, page: int, size: int, params: Optional[Mapping[str, Any]] = None) -> Call:
+    return Call("GET", path, params={**(params or {}), "page": page, "per_page": size})
+
+
+def items_of(body: Any, key: str, parse: Callable[[dict[str, Any]], Any]) -> list[Any]:
+    rows = body.get(key) if isinstance(body, dict) else None
+    return [parse(row) for row in rows or [] if isinstance(row, dict)]
+
+
+def collect(
+    path: str, key: str, parse: Callable[[dict[str, Any]], Any], size: int, params: Optional[Mapping[str, Any]] = None
+) -> Flow[list[Any]]:
+    found: list[Any] = []
+    page = 1
+    while True:
+        body = yield page_call(path, page, size, params)
+        batch = items_of(body, key, parse)
+        found.extend(batch)
+        if not batch or not has_next(body):
+            return found
+        page += 1