dnscale 1.0.0__tar.gz

dnscale-1.0.0/GENERATION.md

@@ -0,0 +1,24 @@
+# Generated client policy
+
+`dnscale_api/` is generated from the bundled `openapi.yaml`; do not edit it manually.
+`dnscale/` is the stable, handwritten layer and is preserved during regeneration.
+
+From the repository root:
+
+```bash
+bash scripts/generate.sh
+```
+
+The script pins `openapi-python-client` so regeneration is deterministic. Review
+the generated diff whenever the OpenAPI contract changes, then run the SDK tests
+and build before committing both changes together.
+
+Generator formatting ignores Git ignore rules within the generated output so
+the same model files are formatted in standalone and monorepo checkouts. The
+generated `provider_credentials.py` contains schema definitions, not secrets,
+and must remain tracked despite the monorepo's broad credentials ignore rule.
+
+Its inputs are the bundled `openapi.yaml` and `generator.yaml`. These are
+maintainer-synchronized copies of the authoritative API contract and generator
+configuration. Do not edit the copies to change API behaviour; propose API
+changes to the maintainers first, then regenerate from the approved contract.

dnscale-1.0.0/LICENSE

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

dnscale-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include GENERATION.md openapi.yaml generator.yaml
+recursive-include scripts *.sh
+exclude RELEASING.md .pypirc .npmrc
+global-exclude .env .env.* *.pem *.key

dnscale-1.0.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: dnscale
+Version: 1.0.0
+Summary: Official Python SDK for the DNScale API
+Author-email: DNScale <ops@dnscale.eu>
+License-Expression: MIT
+Project-URL: Documentation, https://docs.dnscale.eu
+Project-URL: Homepage, https://dnscale.eu
+Project-URL: Repository, https://github.com/dnscaleou/dnscale-python
+Project-URL: Issues, https://github.com/dnscaleou/dnscale-python/issues
+Keywords: dns,dnscale,api,sdk
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx<0.29.0,>=0.23.0
+Requires-Dist: python-dateutil<3,>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.3.0; extra == "dev"
+Requires-Dist: ruff<0.13,>=0.12.0; extra == "dev"
+Dynamic: license-file
+
+# DNScale Python SDK
+
+The official Python client for the DNScale API. It supports Python 3.10 and newer,
+provides synchronous and asynchronous calls, and is generated from the public
+OpenAPI contract bundled as [openapi.yaml](openapi.yaml).
+
+## Installation
+
+Install a published release from PyPI:
+
+```bash
+python -m pip install dnscale
+```
+
+The distribution and import name are both `dnscale`; the source repository is
+`dnscale-python`. Before the first PyPI release, or to work from source, clone
+this repository and install from its root:
+
+```bash
+python -m pip install .
+```
+
+## Quick start
+
+Create an API key in the DNScale dashboard and pass it directly or export it as
+`DNSCALE_API_KEY`.
+
+```python
+from dnscale import DNScale
+
+with DNScale() as dns:
+    zones = dns.zones.list(limit=25)
+    for zone in zones.zones:
+        print(zone.id, zone.name)
+
+    created = dns.records.create(
+        zones.zones[0].id,
+        name="www",
+        type_="A",
+        content="192.0.2.10",
+        ttl=300,
+    )
+    print(created.id)
+```
+
+The same resources provide async methods prefixed with `a`:
+
+```python
+from dnscale import DNScale
+
+
+async def list_zone_names() -> list[str]:
+    async with DNScale() as dns:
+        result = await dns.zones.alist(limit=100)
+        return [zone.name for zone in result.zones]
+```
+
+`DNScale` retries transient failures for `GET`, `HEAD`, and `OPTIONS` requests.
+It never automatically retries mutations such as record or zone creation. Set
+`max_retries=0` to disable retries.
+If `Retry-After` exceeds the 30-second retry waiting budget, the response is
+surfaced immediately instead of retrying before the server permits it. HTTP-date
+and numeric delay values are supported. Network errors remain `httpx` errors.
+
+## Pagination and record identity
+
+`list()` returns one page. Use lazy iterators to traverse all pages:
+
+```python
+with DNScale() as dns:
+    for zone in dns.zones.iter():
+        for record in dns.records.iter(zone.id):
+            print(zone.name, record.name, record.content)
+```
+
+Async equivalents are `zones.aiter()` and `records.aiter(zone_id)`. Iterators
+honour the returned page size and reject inconsistent pagination. Offset-based
+listing is not an atomic snapshot if another client changes the zone concurrently.
+
+Record IDs are opaque and content-derived: use the **returned ID after an
+update**. By-name helpers can avoid retaining an ID:
+
+```python
+from dnscale_api.models import UpdateRecordByNameRequest
+
+with DNScale() as dns:
+    updated = dns.records.update_by_name(
+        zone_id, "_acme-challenge.example.com.", "TXT",
+        content="old-value",  # select this value in a multi-value RRset
+        body=UpdateRecordByNameRequest(content="new-value", ttl=300),
+    )
+    dns.records.delete_by_name(zone_id, updated.name, "TXT", content="new-value")
+```
+
+Omitting `content` from `delete_by_name()` deletes the **entire RRset**. Empty
+content is rejected by the helper to prevent accidental whole-RRset deletion.
+Async variants are `aupdate_by_name()` and `adelete_by_name()`.
+
+## Errors
+
+The convenience resources convert the API's error envelope into exceptions:
+
+```python
+from dnscale import APIError, DNScale, RateLimitError
+
+try:
+    with DNScale() as dns:
+        dns.zones.get("00000000-0000-0000-0000-000000000000")
+except RateLimitError as error:
+    print(error.retry_after)
+except APIError as error:
+    print(error.status_code, error.code, error.message, error.request_id)
+```
+
+Network and timeout failures remain standard `httpx` exceptions.
+
+## Complete generated API
+
+The `dnscale` layer offers concise zone and record CRUD. Every public endpoint is
+also available through the generated `dnscale_api` package, including alerts,
+DNSSEC, usage, billing, users, invitations, API keys, activity, and DNS Control.
+
+```python
+from dnscale import DNScale
+from dnscale_api.api.usage import get_current_usage
+
+with DNScale(api_key="your-api-key") as dns:
+    response = get_current_usage.sync(client=dns.client)
+    print(response)
+```
+
+Each generated operation has `sync`, `sync_detailed`, `asyncio`, and
+`asyncio_detailed` variants. Request and response models live in
+`dnscale_api.models`.
+
+## Development
+
+From this repository's root, install development dependencies and regenerate
+the client. Python 3.10+ and [uv](https://docs.astral.sh/uv/) are required.
+Do not edit `dnscale_api` by hand.
+
+```bash
+python -m pip install -e '.[dev]'
+bash scripts/generate.sh
+```
+
+The generator version is pinned in the script. To verify the package:
+
+```bash
+python -m pytest
+ruff check dnscale tests
+ruff format --check dnscale tests
+uv build
+```
+
+The generator is pinned; see [GENERATION.md](GENERATION.md) for the contract
+update policy. Commit the reviewed generated changes with their input changes.
+
+Live verification is explicitly opt-in and creates/deletes a unique test zone:
+
+```bash
+export DNSCALE_TEST_BASE_URL=https://your-sandbox.example/v1
+export DNSCALE_TEST_API_KEY=your-disposable-account-key
+DNSCALE_LIVE_TEST=1 python -m pytest tests/test_live.py
+```
+
+The test uses separate credentials from `DNSCALE_API_KEY`. Use a disposable
+account with zone and record read/write scopes. No real domain delegation is
+needed. Tests are skipped when `DNSCALE_LIVE_TEST` is not `1`.
+
+Report bugs and feature requests in the
+[issue tracker](https://github.com/dnscaleou/dnscale-python/issues).

dnscale-1.0.0/README.md

@@ -0,0 +1,172 @@
+# DNScale Python SDK
+
+The official Python client for the DNScale API. It supports Python 3.10 and newer,
+provides synchronous and asynchronous calls, and is generated from the public
+OpenAPI contract bundled as [openapi.yaml](openapi.yaml).
+
+## Installation
+
+Install a published release from PyPI:
+
+```bash
+python -m pip install dnscale
+```
+
+The distribution and import name are both `dnscale`; the source repository is
+`dnscale-python`. Before the first PyPI release, or to work from source, clone
+this repository and install from its root:
+
+```bash
+python -m pip install .
+```
+
+## Quick start
+
+Create an API key in the DNScale dashboard and pass it directly or export it as
+`DNSCALE_API_KEY`.
+
+```python
+from dnscale import DNScale
+
+with DNScale() as dns:
+    zones = dns.zones.list(limit=25)
+    for zone in zones.zones:
+        print(zone.id, zone.name)
+
+    created = dns.records.create(
+        zones.zones[0].id,
+        name="www",
+        type_="A",
+        content="192.0.2.10",
+        ttl=300,
+    )
+    print(created.id)
+```
+
+The same resources provide async methods prefixed with `a`:
+
+```python
+from dnscale import DNScale
+
+
+async def list_zone_names() -> list[str]:
+    async with DNScale() as dns:
+        result = await dns.zones.alist(limit=100)
+        return [zone.name for zone in result.zones]
+```
+
+`DNScale` retries transient failures for `GET`, `HEAD`, and `OPTIONS` requests.
+It never automatically retries mutations such as record or zone creation. Set
+`max_retries=0` to disable retries.
+If `Retry-After` exceeds the 30-second retry waiting budget, the response is
+surfaced immediately instead of retrying before the server permits it. HTTP-date
+and numeric delay values are supported. Network errors remain `httpx` errors.
+
+## Pagination and record identity
+
+`list()` returns one page. Use lazy iterators to traverse all pages:
+
+```python
+with DNScale() as dns:
+    for zone in dns.zones.iter():
+        for record in dns.records.iter(zone.id):
+            print(zone.name, record.name, record.content)
+```
+
+Async equivalents are `zones.aiter()` and `records.aiter(zone_id)`. Iterators
+honour the returned page size and reject inconsistent pagination. Offset-based
+listing is not an atomic snapshot if another client changes the zone concurrently.
+
+Record IDs are opaque and content-derived: use the **returned ID after an
+update**. By-name helpers can avoid retaining an ID:
+
+```python
+from dnscale_api.models import UpdateRecordByNameRequest
+
+with DNScale() as dns:
+    updated = dns.records.update_by_name(
+        zone_id, "_acme-challenge.example.com.", "TXT",
+        content="old-value",  # select this value in a multi-value RRset
+        body=UpdateRecordByNameRequest(content="new-value", ttl=300),
+    )
+    dns.records.delete_by_name(zone_id, updated.name, "TXT", content="new-value")
+```
+
+Omitting `content` from `delete_by_name()` deletes the **entire RRset**. Empty
+content is rejected by the helper to prevent accidental whole-RRset deletion.
+Async variants are `aupdate_by_name()` and `adelete_by_name()`.
+
+## Errors
+
+The convenience resources convert the API's error envelope into exceptions:
+
+```python
+from dnscale import APIError, DNScale, RateLimitError
+
+try:
+    with DNScale() as dns:
+        dns.zones.get("00000000-0000-0000-0000-000000000000")
+except RateLimitError as error:
+    print(error.retry_after)
+except APIError as error:
+    print(error.status_code, error.code, error.message, error.request_id)
+```
+
+Network and timeout failures remain standard `httpx` exceptions.
+
+## Complete generated API
+
+The `dnscale` layer offers concise zone and record CRUD. Every public endpoint is
+also available through the generated `dnscale_api` package, including alerts,
+DNSSEC, usage, billing, users, invitations, API keys, activity, and DNS Control.
+
+```python
+from dnscale import DNScale
+from dnscale_api.api.usage import get_current_usage
+
+with DNScale(api_key="your-api-key") as dns:
+    response = get_current_usage.sync(client=dns.client)
+    print(response)
+```
+
+Each generated operation has `sync`, `sync_detailed`, `asyncio`, and
+`asyncio_detailed` variants. Request and response models live in
+`dnscale_api.models`.
+
+## Development
+
+From this repository's root, install development dependencies and regenerate
+the client. Python 3.10+ and [uv](https://docs.astral.sh/uv/) are required.
+Do not edit `dnscale_api` by hand.
+
+```bash
+python -m pip install -e '.[dev]'
+bash scripts/generate.sh
+```
+
+The generator version is pinned in the script. To verify the package:
+
+```bash
+python -m pytest
+ruff check dnscale tests
+ruff format --check dnscale tests
+uv build
+```
+
+The generator is pinned; see [GENERATION.md](GENERATION.md) for the contract
+update policy. Commit the reviewed generated changes with their input changes.
+
+Live verification is explicitly opt-in and creates/deletes a unique test zone:
+
+```bash
+export DNSCALE_TEST_BASE_URL=https://your-sandbox.example/v1
+export DNSCALE_TEST_API_KEY=your-disposable-account-key
+DNSCALE_LIVE_TEST=1 python -m pytest tests/test_live.py
+```
+
+The test uses separate credentials from `DNSCALE_API_KEY`. Use a disposable
+account with zone and record read/write scopes. No real domain delegation is
+needed. Tests are skipped when `DNSCALE_LIVE_TEST` is not `1`.
+
+Report bugs and feature requests in the
+[issue tracker](https://github.com/dnscaleou/dnscale-python/issues).

dnscale-1.0.0/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-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-1.0.0/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