dnscale 1.0.0__py3-none-any.whl

dnscale/__init__.py

@@ -0,0 +1,27 @@
+"""Ergonomic entry point for the DNScale Python SDK."""
+
+from dnscale_api.models.record import Record
+from dnscale_api.models.record_type import RecordType
+from dnscale_api.models.zone import Zone
+from dnscale_api.models.zone_region import ZoneRegion
+from dnscale_api.models.zone_status import ZoneStatus
+from dnscale_api.models.zone_type import ZoneType
+
+from .client import DEFAULT_BASE_URL, DNScale
+from .errors import APIError, ProtocolError, RateLimitError
+
+__all__ = (
+    "APIError",
+    "DEFAULT_BASE_URL",
+    "DNScale",
+    "ProtocolError",
+    "RateLimitError",
+    "Record",
+    "RecordType",
+    "Zone",
+    "ZoneRegion",
+    "ZoneStatus",
+    "ZoneType",
+)
+
+__version__ = "1.0.0"

dnscale/client.py

@@ -0,0 +1,125 @@
+"""Configured DNScale API client."""
+
+from __future__ import annotations
+
+import os
+import ssl
+from collections.abc import Mapping
+
+import httpx
+
+from dnscale_api import AuthenticatedClient
+
+from .errors import acheck_error_response, check_error_response
+from .records import Records
+from .transport import AsyncRetryTransport, RetryTransport
+from .zones import Zones
+
+DEFAULT_BASE_URL = "https://api.dnscale.eu/v1"
+
+
+class DNScale:
+    """DNScale client with typed resources and access to every generated endpoint.
+
+    The API key is read from ``DNSCALE_API_KEY`` when it is not passed explicitly.
+    Only safe read requests are retried after transient HTTP or transport failures.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = 10.0,
+        max_retries: int = 2,
+        retry_backoff: float = 0.25,
+        verify_ssl: str | bool | ssl.SSLContext = True,
+        follow_redirects: bool = False,
+        headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+        async_transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        token = api_key or os.getenv("DNSCALE_API_KEY")
+        if not token:
+            raise ValueError("A DNScale API key is required; pass api_key or set DNSCALE_API_KEY")
+        if max_retries < 0:
+            raise ValueError("max_retries must be zero or greater")
+        if retry_backoff < 0:
+            raise ValueError("retry_backoff must be zero or greater")
+
+        normalized_base_url = base_url.rstrip("/")
+        request_headers = {
+            "Accept": "application/json",
+            "User-Agent": "dnscale-python/1.0.0",
+            **dict(headers or {}),
+            "Authorization": f"Bearer {token}",
+        }
+
+        sync_client = httpx.Client(
+            event_hooks={"response": [check_error_response]},
+            base_url=normalized_base_url,
+            headers=request_headers,
+            timeout=timeout,
+            verify=verify_ssl,
+            follow_redirects=follow_redirects,
+            transport=RetryTransport(
+                max_retries=max_retries,
+                backoff=retry_backoff,
+                verify_ssl=verify_ssl,
+                transport=transport,
+            ),
+        )
+        async_client = httpx.AsyncClient(
+            event_hooks={"response": [acheck_error_response]},
+            base_url=normalized_base_url,
+            headers=request_headers,
+            timeout=timeout,
+            verify=verify_ssl,
+            follow_redirects=follow_redirects,
+            transport=AsyncRetryTransport(
+                max_retries=max_retries,
+                backoff=retry_backoff,
+                verify_ssl=verify_ssl,
+                transport=async_transport,
+            ),
+        )
+
+        self.client = AuthenticatedClient(
+            base_url=normalized_base_url,
+            token=token,
+            headers=dict(request_headers),
+            timeout=httpx.Timeout(timeout) if isinstance(timeout, float | int) else timeout,
+            verify_ssl=verify_ssl,
+            follow_redirects=follow_redirects,
+            raise_on_unexpected_status=True,
+        )
+        self.client.set_httpx_client(sync_client)
+        self.client.set_async_httpx_client(async_client)
+
+        self.zones = Zones(self.client)
+        self.records = Records(self.client)
+
+    def close(self) -> None:
+        """Close the blocking HTTP client."""
+
+        self.client.get_httpx_client().close()
+
+    async def aclose(self) -> None:
+        """Close both clients, including any sync calls used in an async workflow."""
+
+        try:
+            await self.client.get_async_httpx_client().aclose()
+        finally:
+            self.close()
+
+    def __enter__(self) -> DNScale:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    async def __aenter__(self) -> DNScale:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

dnscale/errors.py

@@ -0,0 +1,118 @@
+"""Exceptions raised by the handwritten SDK layer."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar, cast
+
+import httpx
+
+from dnscale_api.models.error_response import ErrorResponse
+from dnscale_api.types import Response, Unset
+
+T = TypeVar("T")
+
+
+class APIError(Exception):
+    """A structured error returned by DNScale."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: list[dict[str, Any]] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.details = details
+        self.request_id = request_id
+        super().__init__(f"DNScale API error {status_code} ({code}): {message}")
+
+
+class RateLimitError(APIError):
+    """The API still returned HTTP 429 after safe retries were exhausted."""
+
+    def __init__(self, *, retry_after: str | None = None, **kwargs: Any) -> None:
+        self.retry_after = retry_after
+        super().__init__(**kwargs)
+
+
+class ProtocolError(Exception):
+    """The API returned a successful response that did not match its contract."""
+
+
+def _check_error_body(response: httpx.Response) -> None:
+    try:
+        body = response.json()
+        if (
+            isinstance(body, dict)
+            and body.get("status") == "error"
+            and isinstance(body.get("error"), dict)
+        ):
+            error = body["error"]
+            if isinstance(error.get("code"), str) and isinstance(error.get("message"), str):
+                return
+    except ValueError:
+        pass
+    kwargs: dict[str, Any] = {
+        "status_code": response.status_code,
+        "code": "HTTP_ERROR",
+        "message": "DNScale returned an HTTP error without a valid API error envelope",
+        "request_id": response.headers.get("X-Request-ID"),
+    }
+    if response.status_code == 429:
+        raise RateLimitError(retry_after=response.headers.get("Retry-After"), **kwargs)
+    raise APIError(**kwargs)
+
+
+def check_error_response(response: httpx.Response) -> None:
+    if response.status_code >= 400:
+        response.read()
+        _check_error_body(response)
+
+
+async def acheck_error_response(response: httpx.Response) -> None:
+    if response.status_code >= 400:
+        await response.aread()
+        _check_error_body(response)
+
+
+def unwrap(response: Response[T | ErrorResponse]) -> T | None:
+    """Return a successful parsed response or raise a structured SDK exception."""
+
+    parsed = response.parsed
+    if isinstance(parsed, ErrorResponse):
+        raw_details = parsed.error.details
+        details = None
+        if not isinstance(raw_details, Unset):
+            details = [item.to_dict() for item in raw_details]
+
+        error_type = RateLimitError if int(response.status_code) == 429 else APIError
+        kwargs: dict[str, Any] = {
+            "status_code": int(response.status_code),
+            "code": parsed.error.code,
+            "message": parsed.error.message,
+            "details": details,
+            "request_id": response.headers.get("X-Request-ID"),
+        }
+        if error_type is RateLimitError:
+            kwargs["retry_after"] = response.headers.get("Retry-After")
+        raise error_type(**kwargs)
+
+    if parsed is None and not 200 <= int(response.status_code) < 300:
+        raise ProtocolError(
+            f"DNScale returned HTTP {int(response.status_code)} without a valid error body"
+        )
+
+    return cast(T | None, parsed)
+
+
+def expect(value: T | None, expected_type: type[T]) -> T:
+    """Narrow generated response unions and detect successful contract drift."""
+
+    if not isinstance(value, expected_type):
+        raise ProtocolError(f"DNScale returned an invalid {expected_type.__name__} response")
+    return value

dnscale/pagination.py

@@ -0,0 +1,20 @@
+"""Pagination guards shared by synchronous and asynchronous iterators."""
+
+from dnscale_api.models.pagination import Pagination
+
+from .errors import ProtocolError
+
+
+def validate_page_size(page_size: int) -> None:
+    if not 1 <= page_size <= 100:
+        raise ValueError("page_size must be between 1 and 100")
+
+
+def next_offset(page: Pagination, offset: int, count: int) -> int | None:
+    if page.offset != offset or page.count != count:
+        raise ProtocolError("DNScale returned inconsistent pagination metadata")
+    if not page.has_more:
+        return None
+    if count == 0:
+        raise ProtocolError("DNScale pagination has_more is true on an empty page")
+    return offset + count

dnscale/py.typed

@@ -0,0 +1 @@
+

dnscale/records.py

@@ -0,0 +1,295 @@
+"""Convenience methods for record CRUD."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from uuid import UUID
+
+from dnscale_api import AuthenticatedClient
+from dnscale_api.api.records import (
+    create_record,
+    delete_record,
+    delete_records_by_name_and_type,
+    get_record,
+    list_records,
+    update_record,
+    update_record_by_name_and_type,
+)
+from dnscale_api.models.create_record_request import CreateRecordRequest
+from dnscale_api.models.record import Record
+from dnscale_api.models.record_response import RecordResponse
+from dnscale_api.models.record_type import RecordType
+from dnscale_api.models.records_data import RecordsData
+from dnscale_api.models.records_response import RecordsResponse
+from dnscale_api.models.update_record_by_name_request import UpdateRecordByNameRequest
+from dnscale_api.types import UNSET, Unset
+
+from .errors import expect, unwrap
+from .pagination import next_offset, validate_page_size
+from .zones import _uuid
+
+
+def _record_body(
+    *,
+    name: str,
+    record_type: RecordType | str,
+    content: str,
+    ttl: int,
+    priority: int | None | Unset,
+    disabled: bool,
+    comment: str | None | Unset,
+) -> CreateRecordRequest:
+    return CreateRecordRequest(
+        name=name,
+        type_=RecordType(record_type),
+        content=content,
+        ttl=ttl,
+        priority=priority,
+        disabled=disabled,
+        comment=comment,
+    )
+
+
+class Records:
+    """Typed record operations bound to a DNScale client."""
+
+    def __init__(self, client: AuthenticatedClient) -> None:
+        self._client = client
+
+    def iter(self, zone_id: str | UUID, *, page_size: int = 100) -> Iterator[Record]:
+        """Lazily fetch all records, including server-limited pages."""
+        validate_page_size(page_size)
+        offset = 0
+        while True:
+            page = self.list(zone_id, offset=offset, limit=page_size)
+            following = next_offset(page.pagination, offset, len(page.records))
+            yield from page.records
+            if following is None:
+                return
+            offset = following
+
+    async def aiter(self, zone_id: str | UUID, *, page_size: int = 100) -> AsyncIterator[Record]:
+        validate_page_size(page_size)
+        offset = 0
+        while True:
+            page = await self.alist(zone_id, offset=offset, limit=page_size)
+            following = next_offset(page.pagination, offset, len(page.records))
+            for record in page.records:
+                yield record
+            if following is None:
+                return
+            offset = following
+
+    def update_by_name(
+        self,
+        zone_id: str | UUID,
+        name: str,
+        type_: RecordType | str,
+        *,
+        body: UpdateRecordByNameRequest,
+        content: str | Unset = UNSET,
+    ) -> Record:
+        """Update by owner name/type. See API semantics for multi-value RRsets."""
+        response = update_record_by_name_and_type.sync_detailed(
+            _uuid(zone_id),
+            name,
+            RecordType(type_),
+            client=self._client,
+            body=body,
+            content=content,
+        )
+        return expect(unwrap(response), RecordResponse).data.record
+
+    async def aupdate_by_name(
+        self,
+        zone_id: str | UUID,
+        name: str,
+        type_: RecordType | str,
+        *,
+        body: UpdateRecordByNameRequest,
+        content: str | Unset = UNSET,
+    ) -> Record:
+        response = await update_record_by_name_and_type.asyncio_detailed(
+            _uuid(zone_id),
+            name,
+            RecordType(type_),
+            client=self._client,
+            body=body,
+            content=content,
+        )
+        return expect(unwrap(response), RecordResponse).data.record
+
+    def delete_by_name(
+        self,
+        zone_id: str | UUID,
+        name: str,
+        type_: RecordType | str,
+        *,
+        content: str | Unset = UNSET,
+    ) -> None:
+        """Delete one value when content is supplied; otherwise delete the whole RRset."""
+        if content == "":
+            raise ValueError("content must be non-empty; omit it to delete the whole RRset")
+        unwrap(
+            delete_records_by_name_and_type.sync_detailed(
+                _uuid(zone_id), name, RecordType(type_), client=self._client, content=content
+            )
+        )
+
+    async def adelete_by_name(
+        self,
+        zone_id: str | UUID,
+        name: str,
+        type_: RecordType | str,
+        *,
+        content: str | Unset = UNSET,
+    ) -> None:
+        if content == "":
+            raise ValueError("content must be non-empty; omit it to delete the whole RRset")
+        unwrap(
+            await delete_records_by_name_and_type.asyncio_detailed(
+                _uuid(zone_id), name, RecordType(type_), client=self._client, content=content
+            )
+        )
+
+    def list(self, zone_id: str | UUID, *, offset: int = 0, limit: int = 50) -> RecordsData:
+        response = list_records.sync_detailed(
+            _uuid(zone_id), client=self._client, offset=offset, limit=limit
+        )
+        return expect(unwrap(response), RecordsResponse).data
+
+    async def alist(self, zone_id: str | UUID, *, offset: int = 0, limit: int = 50) -> RecordsData:
+        response = await list_records.asyncio_detailed(
+            _uuid(zone_id), client=self._client, offset=offset, limit=limit
+        )
+        return expect(unwrap(response), RecordsResponse).data
+
+    def get(self, zone_id: str | UUID, record_id: str) -> Record:
+        response = get_record.sync_detailed(_uuid(zone_id), record_id, client=self._client)
+        return expect(unwrap(response), RecordResponse).data.record
+
+    async def aget(self, zone_id: str | UUID, record_id: str) -> Record:
+        response = await get_record.asyncio_detailed(_uuid(zone_id), record_id, client=self._client)
+        return expect(unwrap(response), RecordResponse).data.record
+
+    def create(
+        self,
+        zone_id: str | UUID,
+        *,
+        name: str,
+        type_: RecordType | str,
+        content: str,
+        ttl: int = 3600,
+        priority: int | None | Unset = UNSET,
+        disabled: bool = False,
+        comment: str | None | Unset = UNSET,
+    ) -> Record:
+        response = create_record.sync_detailed(
+            _uuid(zone_id),
+            client=self._client,
+            body=_record_body(
+                name=name,
+                record_type=type_,
+                content=content,
+                ttl=ttl,
+                priority=priority,
+                disabled=disabled,
+                comment=comment,
+            ),
+        )
+        return expect(unwrap(response), RecordResponse).data.record
+
+    async def acreate(
+        self,
+        zone_id: str | UUID,
+        *,
+        name: str,
+        type_: RecordType | str,
+        content: str,
+        ttl: int = 3600,
+        priority: int | None | Unset = UNSET,
+        disabled: bool = False,
+        comment: str | None | Unset = UNSET,
+    ) -> Record:
+        response = await create_record.asyncio_detailed(
+            _uuid(zone_id),
+            client=self._client,
+            body=_record_body(
+                name=name,
+                record_type=type_,
+                content=content,
+                ttl=ttl,
+                priority=priority,
+                disabled=disabled,
+                comment=comment,
+            ),
+        )
+        return expect(unwrap(response), RecordResponse).data.record
+
+    def update(
+        self,
+        zone_id: str | UUID,
+        record_id: str,
+        *,
+        name: str,
+        type_: RecordType | str,
+        content: str,
+        ttl: int = 3600,
+        priority: int | None | Unset = UNSET,
+        disabled: bool = False,
+        comment: str | None | Unset = UNSET,
+    ) -> Record:
+        response = update_record.sync_detailed(
+            _uuid(zone_id),
+            record_id,
+            client=self._client,
+            body=_record_body(
+                name=name,
+                record_type=type_,
+                content=content,
+                ttl=ttl,
+                priority=priority,
+                disabled=disabled,
+                comment=comment,
+            ),
+        )
+        return expect(unwrap(response), RecordResponse).data.record
+
+    async def aupdate(
+        self,
+        zone_id: str | UUID,
+        record_id: str,
+        *,
+        name: str,
+        type_: RecordType | str,
+        content: str,
+        ttl: int = 3600,
+        priority: int | None | Unset = UNSET,
+        disabled: bool = False,
+        comment: str | None | Unset = UNSET,
+    ) -> Record:
+        response = await update_record.asyncio_detailed(
+            _uuid(zone_id),
+            record_id,
+            client=self._client,
+            body=_record_body(
+                name=name,
+                record_type=type_,
+                content=content,
+                ttl=ttl,
+                priority=priority,
+                disabled=disabled,
+                comment=comment,
+            ),
+        )
+        return expect(unwrap(response), RecordResponse).data.record
+
+    def delete(self, zone_id: str | UUID, record_id: str) -> None:
+        response = delete_record.sync_detailed(_uuid(zone_id), record_id, client=self._client)
+        unwrap(response)
+
+    async def adelete(self, zone_id: str | UUID, record_id: str) -> None:
+        response = await delete_record.asyncio_detailed(
+            _uuid(zone_id), record_id, client=self._client
+        )
+        unwrap(response)