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

digitalocean_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,356 @@
+Metadata-Version: 2.5
+Name: digitalocean-python-sdk
+Version: 0.1.0
+Summary: A typed Python client for the DigitalOcean Domains and DNS API, sync and async.
+Project-URL: Homepage, https://theqiyas.cc/projects/digitalocean-python-sdk/
+Project-URL: Source, https://github.com/qiyascc/digitalocean-python-sdk
+Project-URL: Author, https://theqiyas.cc
+Project-URL: Issues, https://github.com/qiyascc/digitalocean-python-sdk/issues
+Project-URL: Changelog, https://github.com/qiyascc/digitalocean-python-sdk/blob/main/CHANGELOG.md
+Author-email: qiyascc <qiyasturk@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,digitalocean,dns,domains,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
+
+# digitalocean-python-sdk
+
+A small, typed Python client for the DigitalOcean Domains and DNS API. It works with both sync and async code, waits and retries when DigitalOcean rate limits you, and returns plain dataclasses, not raw JSON.
+
+```python
+from digitalocean_sdk import DigitalOcean
+
+with DigitalOcean("DIGITALOCEAN_TOKEN") as do:
+    do.dns.point("example.com", "shop", "203.0.113.10")
+```
+
+That call makes `shop.example.com` resolve to `203.0.113.10`. If the record already exists it is updated, if it is missing it is created, and extra `A` records with the same name are removed.
+
+## Install
+
+```bash
+pip install digitalocean-python-sdk
+```
+
+Requires Python 3.10 or newer. Dependencies: [httpx](https://www.python-httpx.org/), [goodconf](https://github.com/lincolnloop/goodconf), pydantic and PyYAML.
+
+The import name is `digitalocean_sdk`, so it can live next to the older `python-digitalocean` package without clashing.
+
+## 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.
+
+Create a personal access token at [cloud.digitalocean.com/account/api/tokens](https://cloud.digitalocean.com/account/api/tokens). For DNS work the token needs the `domain` scopes (read, create, update, delete). Then pick whichever option suits you:
+
+```python
+do = DigitalOcean("dop_v1_...")
+```
+
+```bash
+export DIGITALOCEAN_TOKEN=dop_v1_...
+```
+
+```toml
+token = "dop_v1_..."
+timeout = 15
+default_ttl = 1800
+```
+
+`DIGITALOCEAN_TOKEN` is the same variable `doctl` and Terraform use, so an existing setup usually works as is.
+
+With no arguments, the client looks for `digitalocean.toml`, `digitalocean.yaml`, `digitalocean.yml` or `digitalocean.json` in the working directory. To load a file from somewhere else, set `DIGITALOCEAN_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 "digitalocean-python-sdk[yaml]"
+```
+
+| Setting | Env variable | Default |
+| --- | --- | --- |
+| `token` | `DIGITALOCEAN_TOKEN` | |
+| `base_url` | `DIGITALOCEAN_BASE_URL` | `https://api.digitalocean.com` |
+| `api_version` | `DIGITALOCEAN_API_VERSION` | `v2` |
+| `endpoints.*` | `DIGITALOCEAN_ENDPOINTS__<NAME>` | see below |
+| `timeout` | `DIGITALOCEAN_TIMEOUT` | `30` |
+| `max_retries` | `DIGITALOCEAN_MAX_RETRIES` | `3` |
+| `max_retry_wait` | `DIGITALOCEAN_MAX_RETRY_WAIT` | `60` |
+| `backoff_base` | `DIGITALOCEAN_BACKOFF_BASE` | `0.5` |
+| `backoff_cap` | `DIGITALOCEAN_BACKOFF_CAP` | `8` |
+| `page_size` | `DIGITALOCEAN_PAGE_SIZE` | `200` (the API maximum) |
+| `default_ttl` | `DIGITALOCEAN_DEFAULT_TTL` | `1800` |
+| `user_agent` | `DIGITALOCEAN_USER_AGENT` | `digitalocean-python-sdk/{version}` |
+
+Any setting can also be passed straight to the client, for example `DigitalOcean(timeout=10, max_retries=5)`. If you build settings yourself, hand them over with `settings=`:
+
+```python
+from digitalocean_sdk import DigitalOcean, load_settings
+
+settings = load_settings("/etc/myapp/digitalocean.toml", default_ttl=300)
+do = DigitalOcean(settings=settings)
+```
+
+### Endpoints
+
+API paths are part of the settings too, so nothing is pinned in the code. Each one is a template relative to the base URL. `{version}` comes from `api_version`, and the other placeholders are filled in and URL encoded for each call.
+
+| Name | Default |
+| --- | --- |
+| `account` | `/{version}/account` |
+| `domains` | `/{version}/domains` |
+| `domain` | `/{version}/domains/{domain}` |
+| `records` | `/{version}/domains/{domain}/records` |
+| `record` | `/{version}/domains/{domain}/records/{record_id}` |
+
+```bash
+export DIGITALOCEAN_ENDPOINTS__RECORDS="/{version}/domains/{domain}/records"
+```
+
+Check that the token works:
+
+```python
+do.account()
+```
+
+```python
+Account(email='you@example.com', uuid='...', status='active', email_verified=True, droplet_limit=25, ...)
+```
+
+## Domains
+
+DigitalOcean is not a registrar. A domain here is a zone you manage with DigitalOcean DNS: buy the name anywhere, then set its name servers to `ns1.digitalocean.com`, `ns2.digitalocean.com` and `ns3.digitalocean.com`.
+
+```python
+do.domains.create("example.com")
+do.domains.create("example.com", ip_address="203.0.113.10")
+
+for domain in do.domains.iter():
+    print(domain.name, domain.ttl)
+
+do.domains.list()
+do.domains.get("example.com").zone_file
+do.domains.exists("example.com")
+do.domains.delete("example.com")
+do.domains.delete("maybe-gone.com", missing_ok=True)
+```
+
+When `ip_address` is given, DigitalOcean creates an `A` record for the apex right away.
+
+## DNS
+
+Every DNS method takes the domain first. 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 digitalocean_sdk import DigitalOcean, DNSRecord
+
+do = DigitalOcean()
+
+do.dns.list("example.com")
+do.dns.list("example.com", "A")
+do.dns.list("example.com", "A", "www")
+do.dns.list("example.com", name="www")
+do.dns.exists("example.com", "A", "shop")
+do.dns.get("example.com", 28448433)
+```
+
+Filtering by type and name happens on DigitalOcean's side. Lists follow every page for you, and `iter()` does the same lazily. Each item is a `DNSRecord`:
+
+```python
+DNSRecord(type='A', name='www', data='203.0.113.10', ttl=1800, priority=None, port=None, weight=None, flags=None, tag=None, id=28448433)
+```
+
+### Creating and changing records
+
+DigitalOcean identifies records by id. `create` and `add` return the new records with their ids filled in.
+
+```python
+record = do.dns.create("example.com", DNSRecord.a("api", "203.0.113.20"))
+
+do.dns.add(
+    "example.com",
+    DNSRecord.txt("@", "google-site-verification=abc"),
+    DNSRecord.mx("@", "mail.example.com", priority=10),
+    DNSRecord.caa("@", "letsencrypt.org"),
+    DNSRecord.srv("_sip._udp", "sip.example.com", port=5060),
+)
+
+do.dns.update("example.com", record, data="203.0.113.21", ttl=300)
+do.dns.update("example.com", 28448433, name="api-v2")
+
+record.ttl = 600
+do.dns.update("example.com", record)
+
+do.dns.delete("example.com", record)
+do.dns.delete("example.com", 28448433, missing_ok=True)
+do.dns.delete_all("example.com", "A", "old")
+```
+
+`update` with fields sends a `PATCH` and changes only those fields. `update` with just a record sends a `PUT` with the whole record.
+
+Host names in `CNAME`, `MX`, `NS` and `SRV` records must be fully qualified with a trailing dot. The helpers add that dot for you, so `DNSRecord.cname("docs", "example.github.io")` is sent as `example.github.io.`. Use `@` to point at the apex itself.
+
+### Replacing a set of records
+
+`replace` makes one type and name hold exactly the values you pass. Matching records are kept, missing ones are created and the rest are deleted. Pass `ttl` to change it on every record in the set.
+
+```python
+do.dns.replace("example.com", "A", "www", ["203.0.113.10", "203.0.113.11"], ttl=600)
+```
+
+### Shortcuts
+
+```python
+do.dns.point("example.com", "shop", "203.0.113.10")
+do.dns.point("example.com", "shop", "2001:db8::10")
+do.dns.alias("example.com", "docs", "example.github.io")
+do.dns.set_txt("example.com", "_acme-challenge", "token-value", ttl=60)
+do.dns.unpoint("example.com", "shop")
+```
+
+`point` picks `A` or `AAAA` from the address you pass. `unpoint` deletes the matching records and returns how many it removed, so it is safe to call when nothing is there.
+
+### Example: one subdomain per customer
+
+```python
+from digitalocean_sdk import DigitalOcean
+
+SERVER_IP = "203.0.113.10"
+
+def create_customer_site(slug: str) -> str:
+    with DigitalOcean() as do:
+        if do.dns.exists("example.com", "A", slug):
+            raise ValueError(f"{slug}.example.com is already taken")
+        do.dns.point("example.com", slug, SERVER_IP, ttl=300)
+    return f"{slug}.example.com"
+```
+
+## Async
+
+`AsyncDigitalOcean` has the same methods. Await them.
+
+```python
+import asyncio
+from digitalocean_sdk import AsyncDigitalOcean
+
+async def main():
+    async with AsyncDigitalOcean() as do:
+        records = await do.dns.list("example.com", "A")
+        await do.dns.point("example.com", "shop", "203.0.113.10")
+        async for domain in do.domains.iter():
+            print(domain.name)
+
+asyncio.run(main())
+```
+
+## Other endpoints
+
+The SDK focuses on Domains and DNS, but the same authenticated client can call any other DigitalOcean endpoint, with the same retries and errors:
+
+```python
+droplets = do.request("GET", "/v2/droplets", params={"per_page": 50})
+do.request("POST", "/v2/droplets/123/actions", json={"type": "reboot"})
+```
+
+## Errors
+
+All exceptions inherit from `DigitalOceanError`.
+
+| Exception | When |
+| --- | --- |
+| `ValidationError` | 400 or 422, the request body or parameters were rejected |
+| `AuthenticationError` | 401, or no token was found |
+| `PermissionDeniedError` | 403, often a token without the right scope |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `RateLimitError` | 429 that is still failing after retries. Has `.retry_after` |
+| `ServerError` | 5xx |
+| `APIConnectionError` / `APITimeoutError` | the request never got an answer |
+
+Status errors carry `status_code`, DigitalOcean's error `code` (for example `not_found` or `unprocessable_entity`), the `request_id` to quote to support, and the raw `response`.
+
+```python
+from digitalocean_sdk import ValidationError
+
+try:
+    do.dns.create("example.com", DNSRecord.cname("@", "elsewhere.com"))
+except ValidationError as exc:
+    print(exc.code, exc.message, exc.request_id)
+```
+
+## Retries and timeouts
+
+DigitalOcean allows 5,000 requests per hour and 250 per minute. When it answers 429, the client waits until the `ratelimit-reset` time it sends and tries again, as long as that wait is under `max_retry_wait`. Server errors and dropped connections are retried with exponential backoff, but only for idempotent methods (`GET`, `PUT`, `DELETE`). A `POST` that creates a record is never sent twice.
+
+```python
+do = DigitalOcean(timeout=10, max_retries=5, max_retry_wait=30)
+```
+
+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 `digitalocean_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 digitalocean_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/digitalocean-python-sdk](https://github.com/qiyascc/digitalocean-python-sdk)
+- PyPI: [pypi.org/project/digitalocean-python-sdk](https://pypi.org/project/digitalocean-python-sdk/)
+- Project page: [theqiyas.cc/projects/digitalocean-python-sdk](https://theqiyas.cc/projects/digitalocean-python-sdk/)
+- Author: [Qiyas Sadıqov](https://theqiyas.cc), more projects at [theqiyas.cc](https://theqiyas.cc)
+
+## License
+
+MIT

digitalocean_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+digitalocean_sdk/__init__.py,sha256=EhVUGklF1XU418IJLxMXCj3M3pD6Rgv1VSfhiOelOFU,926
+digitalocean_sdk/_base.py,sha256=d9Tt9FeDMwS1b-NvLm7iIBqJnI47rgxsW9MllOYcygA,8761
+digitalocean_sdk/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+digitalocean_sdk/client.py,sha256=VRfQEoX7EWhk0GtWeCoKL1GNjIHMARr3FGnLDa4Vd9A,1042
+digitalocean_sdk/config.py,sha256=cQXoIMhGPjxgsCxIJvR5pyEgnJD9XBS1NlcaMLy_uko,2994
+digitalocean_sdk/errors.py,sha256=jKqQBVhcpb_wpGqARm14W66VEvxdNkw_c8mCNtptTAk,3351
+digitalocean_sdk/messages.py,sha256=Us_YoaNd64bApY58c9gbphy22V8IZ9SKmJOepMGo5WU,1635
+digitalocean_sdk/messages.yaml,sha256=7W-dwzU-cLLac8hS24lib8UwSPkCRNjerymjYUfmUqE,1577
+digitalocean_sdk/models.py,sha256=AFFrPa8dpbidYXLQdIDMkSZlxRAQ7D1ol-WnzdcUqzI,4915
+digitalocean_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+digitalocean_sdk/resources/__init__.py,sha256=SNR0uMexYuMHV2kL34CGR23D_3XOu7-EM9YsY0-IwqI,178
+digitalocean_sdk/resources/_paging.py,sha256=Dr-U0uGUIHXqRTmukIR9HcvhWSh0iQbZhyDdBhtYFjg,1141
+digitalocean_sdk/resources/dns.py,sha256=h3xffv5WMgxrgrNFDJRP20Z7UAk1QZ84PM0SH_SY9ZU,9720
+digitalocean_sdk/resources/domains.py,sha256=EbzOhy9GumJSAz7MKrwi1-1lIUIIIDjPsfE39HtJzCs,2803
+digitalocean_python_sdk-0.1.0.dist-info/METADATA,sha256=InaJGdrA_ARITvY8_CeanRYFX-xX2sTNdTiUUmREWR4,13327
+digitalocean_python_sdk-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+digitalocean_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=ENVL-_Eh4n1SumZuLuTjO2K0OOL_eXh4pkeme35b02I,1064
+digitalocean_python_sdk-0.1.0.dist-info/RECORD,,

digitalocean_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

digitalocean_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.

digitalocean_sdk/__init__.py

@@ -0,0 +1,42 @@
+from . import messages
+from ._version import __version__
+from .client import AsyncDigitalOcean, DigitalOcean
+from .config import Settings, load_settings
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    DigitalOceanError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import Account, DNSRecord, Domain, RecordType
+
+__all__ = [
+    "__version__",
+    "DigitalOcean",
+    "AsyncDigitalOcean",
+    "Settings",
+    "load_settings",
+    "messages",
+    "Account",
+    "DNSRecord",
+    "Domain",
+    "RecordType",
+    "DigitalOceanError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "ValidationError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+]

digitalocean_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, token=token, **overrides)
+        elif token or overrides:
+            changes = {k: v for k, v in dict(overrides, 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"]

digitalocean_sdk/_version.py

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