devnomads 0.1.3__tar.gz → 0.2.0__tar.gz

{devnomads-0.1.3 → devnomads-0.2.0}/.gitlab-ci.yml

@@ -12,6 +12,7 @@ default:
 check:
   stage: check
   script:
+    - uv run python tools/generate.py --check
     - uv run black --check .
     - uv run isort --check-only .
     - uv run flake8 src tests

devnomads-0.2.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: spec generate build check test
+
+# refresh the committed OpenAPI snapshot from the live API
+spec:
+	curl -sf "https://api.devnomads.nl/docs?api-docs.json" -o openapi.json
+
+# regenerate src/devnomads/api/_services.py from openapi.json
+generate:
+	uv run python tools/generate.py
+	uv run black -q .
+	uv run isort -q .
+
+# full build: refresh spec, regenerate, verify
+build: spec generate check
+
+check:
+	uv run python tools/generate.py --check
+	uv run black --check .
+	uv run isort --check-only .
+	uv run flake8 src tests tools
+	uv run bandit -q -r src
+	uv run semgrep scan --quiet --error --config p/python src
+	uv run mypy src
+	uv run pytest -q
+
+test:
+	uv run pytest -v

{devnomads-0.1.3 → devnomads-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devnomads
-Version: 0.1.3
+Version: 0.2.0
 Summary: Python client for the DevNomads API (transport, DNS, ACME)
 Project-URL: Homepage, https://devnomads.nl
 Author-email: Loek Geleijn <support@devnomads.nl>
@@ -18,8 +18,8 @@ Description-Content-Type: text/markdown
 # devnomads
 
 Python client library for the [DevNomads](https://devnomads.nl) API:
-HTTP transport, DNS zone/record management, and ACME certificate
-issuance.
+HTTP transport, a generated resource SDK covering the whole API, DNS
+zone/record management, and ACME certificate issuance.
 
 It is the shared foundation of the DevNomads command-line tools - `dnctl`
 and `dnsync` - exposed so you can build against the same primitives
@@ -33,6 +33,7 @@ directly instead of reimplementing them.
 - [Architecture](#architecture)
 - [Authentication](#authentication)
 - [Transport](#transport)
+- [Services](#services)
 - [DNS](#dns)
 - [Certificates](#certificates)
 - [Errors](#errors)
@@ -45,6 +46,8 @@ directly instead of reimplementing them.
 
 - Authenticated HTTP transport with retries (`Retry-After` aware) and
   Laravel resource-envelope unwrapping.
+- A generated resource SDK covering the whole API as client
+  attributes, e.g. `client.servers.list()`.
 - DNS zone discovery (longest-suffix matching), merge-aware TXT updates,
   and generic record management.
 - ACME certificate issuance over DNS-01 and HTTP-01 - including
@@ -85,13 +88,17 @@ The package is split into three layers by dependency weight. Import only
 what you need.
 
 ```text
-devnomads.api    transport: auth, retries, errors          (httpx)
+devnomads.api    transport + generated resource SDK         (httpx)
       ▲
 devnomads.dns    zones, records, TXT/ACME challenges        (httpx)
       ▲
 devnomads.acme   ACME issuance: DNS-01 + HTTP-01   (+ acme extra deps)
 ```
 
+`devnomads.api` carries both the low-level `Client` transport and a
+generated SDK that maps the full API onto client attributes (see
+[Services](#services)).
+
 The DevNomads DNS API is a PowerDNS proxy scoped to the zones a key may
 access, so zone ids and record names are absolute (trailing dot) and TXT
 content is stored quoted; the library handles these conventions for you.
@@ -182,6 +189,55 @@ JSON and:
   resource reads as absence;
 - raises `AuthError` on `401`/`403` and `ApiError` on any other `4xx`.
 
+## Services
+
+Beyond the curated DNS and ACME helpers, the `Client` exposes the rest
+of the API through a generated, resource-attribute SDK. Each top-level
+resource is an attribute on the client; nested resources chain as
+further attributes; operations are methods.
+
+```python
+from devnomads.api import Client
+
+with Client.from_environment() as client:
+    client.servers.list()
+    client.servers.show(server_id)
+    client.databases.clusters.list()
+    client.databases.create(body={"name": "blog"})
+    client.emails.mailboxes.list(service_id)
+    client.emails.mailboxes.create(service_id, body={...})
+    client.proxies.up(service_id)
+```
+
+The top-level resources are `servers`, `databases`, `emails`, `spams`,
+`containers`, `proxies`, `sites`, `buckets`, `domains`, `forwards`,
+`searches`, `apps`, and `handles`. (DNS stays the curated
+`devnomads.dns` interface and is not generated here.)
+
+### Conventions
+
+- **Path parameters** are positional, in URL order, snake-cased from
+  the path template - e.g. `client.emails.mailboxes.show(service_id,
+  emailaddress)`.
+- **Query parameters** go through `params=` as a dict.
+- **Request bodies** (POST/PUT/PATCH) go through `body=`, sent as JSON.
+- **Method names** map the API action: `index` -> `list`, `store`/
+  `create` -> `create`, `show`, `update`, `destroy`/`delete` ->
+  `delete`, `patch`; any other action (`state`, `deploy`, `logs`, `up`,
+  `down`, `enable`, ...) passes through snake-cased.
+
+Returns are the parsed JSON payload (envelope already unwrapped). The
+OpenAPI spec ships no component schemas, so there are no typed response
+models - methods return `Any`. The SDK is generated from the committed
+`openapi.json`; see [Development](#development).
+
+```python
+mailbox = client.emails.mailboxes.create(
+    service_id, body={"address": "hi@example.com"}
+)
+aliases = client.emails.aliases.list(service_id, params={"page": 2})
+```
+
 ## DNS
 
 `Dns` wraps a `Client` with zone-scoped operations. Zone discovery lists
@@ -459,6 +515,16 @@ uv run pytest
 uv run black . && uv run flake8 src tests
 ```
 
+The `Services` SDK in `src/devnomads/api/_services.py` is generated from
+the committed `openapi.json` snapshot. Regenerate it after refreshing
+the spec; CI fails if the checked-in file is stale.
+
+```bash
+make spec       # refresh openapi.json from the live API
+make generate   # rewrite _services.py from openapi.json
+make check      # lint + type + test + generate --check
+```
+
 ## License
 
 MIT

{devnomads-0.1.3 → devnomads-0.2.0}/README.md

@@ -1,8 +1,8 @@
 # devnomads
 
 Python client library for the [DevNomads](https://devnomads.nl) API:
-HTTP transport, DNS zone/record management, and ACME certificate
-issuance.
+HTTP transport, a generated resource SDK covering the whole API, DNS
+zone/record management, and ACME certificate issuance.
 
 It is the shared foundation of the DevNomads command-line tools - `dnctl`
 and `dnsync` - exposed so you can build against the same primitives
@@ -16,6 +16,7 @@ directly instead of reimplementing them.
 - [Architecture](#architecture)
 - [Authentication](#authentication)
 - [Transport](#transport)
+- [Services](#services)
 - [DNS](#dns)
 - [Certificates](#certificates)
 - [Errors](#errors)
@@ -28,6 +29,8 @@ directly instead of reimplementing them.
 
 - Authenticated HTTP transport with retries (`Retry-After` aware) and
   Laravel resource-envelope unwrapping.
+- A generated resource SDK covering the whole API as client
+  attributes, e.g. `client.servers.list()`.
 - DNS zone discovery (longest-suffix matching), merge-aware TXT updates,
   and generic record management.
 - ACME certificate issuance over DNS-01 and HTTP-01 - including
@@ -68,13 +71,17 @@ The package is split into three layers by dependency weight. Import only
 what you need.
 
 ```text
-devnomads.api    transport: auth, retries, errors          (httpx)
+devnomads.api    transport + generated resource SDK         (httpx)
       ▲
 devnomads.dns    zones, records, TXT/ACME challenges        (httpx)
       ▲
 devnomads.acme   ACME issuance: DNS-01 + HTTP-01   (+ acme extra deps)
 ```
 
+`devnomads.api` carries both the low-level `Client` transport and a
+generated SDK that maps the full API onto client attributes (see
+[Services](#services)).
+
 The DevNomads DNS API is a PowerDNS proxy scoped to the zones a key may
 access, so zone ids and record names are absolute (trailing dot) and TXT
 content is stored quoted; the library handles these conventions for you.
@@ -165,6 +172,55 @@ JSON and:
   resource reads as absence;
 - raises `AuthError` on `401`/`403` and `ApiError` on any other `4xx`.
 
+## Services
+
+Beyond the curated DNS and ACME helpers, the `Client` exposes the rest
+of the API through a generated, resource-attribute SDK. Each top-level
+resource is an attribute on the client; nested resources chain as
+further attributes; operations are methods.
+
+```python
+from devnomads.api import Client
+
+with Client.from_environment() as client:
+    client.servers.list()
+    client.servers.show(server_id)
+    client.databases.clusters.list()
+    client.databases.create(body={"name": "blog"})
+    client.emails.mailboxes.list(service_id)
+    client.emails.mailboxes.create(service_id, body={...})
+    client.proxies.up(service_id)
+```
+
+The top-level resources are `servers`, `databases`, `emails`, `spams`,
+`containers`, `proxies`, `sites`, `buckets`, `domains`, `forwards`,
+`searches`, `apps`, and `handles`. (DNS stays the curated
+`devnomads.dns` interface and is not generated here.)
+
+### Conventions
+
+- **Path parameters** are positional, in URL order, snake-cased from
+  the path template - e.g. `client.emails.mailboxes.show(service_id,
+  emailaddress)`.
+- **Query parameters** go through `params=` as a dict.
+- **Request bodies** (POST/PUT/PATCH) go through `body=`, sent as JSON.
+- **Method names** map the API action: `index` -> `list`, `store`/
+  `create` -> `create`, `show`, `update`, `destroy`/`delete` ->
+  `delete`, `patch`; any other action (`state`, `deploy`, `logs`, `up`,
+  `down`, `enable`, ...) passes through snake-cased.
+
+Returns are the parsed JSON payload (envelope already unwrapped). The
+OpenAPI spec ships no component schemas, so there are no typed response
+models - methods return `Any`. The SDK is generated from the committed
+`openapi.json`; see [Development](#development).
+
+```python
+mailbox = client.emails.mailboxes.create(
+    service_id, body={"address": "hi@example.com"}
+)
+aliases = client.emails.aliases.list(service_id, params={"page": 2})
+```
+
 ## DNS
 
 `Dns` wraps a `Client` with zone-scoped operations. Zone discovery lists
@@ -442,6 +498,16 @@ uv run pytest
 uv run black . && uv run flake8 src tests
 ```
 
+The `Services` SDK in `src/devnomads/api/_services.py` is generated from
+the committed `openapi.json` snapshot. Regenerate it after refreshing
+the spec; CI fails if the checked-in file is stale.
+
+```bash
+make spec       # refresh openapi.json from the live API
+make generate   # rewrite _services.py from openapi.json
+make check      # lint + type + test + generate --check
+```
+
 ## License
 
 MIT