trmnl-terminus 0.1.0__tar.gz

trmnl_terminus-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.env
+.env.*
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+smoke-artifacts/
+

trmnl_terminus-0.1.0/LICENSE

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

trmnl_terminus-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: trmnl-terminus
+Version: 0.1.0
+Summary: Synchronous Python SDK for Terminus Server
+Project-URL: Documentation, https://github.com/hsperker/trmnl-terminus-sdk#readme
+Project-URL: Issues, https://github.com/hsperker/trmnl-terminus-sdk/issues
+Project-URL: Repository, https://github.com/hsperker/trmnl-terminus-sdk
+Author: hsperker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: e-ink,sdk,terminus,trmnl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Description-Content-Type: text/markdown
+
+# TRMNL Terminus Python SDK
+
+`trmnl-terminus` is a small, synchronous Python client for automating a
+self-hosted [Terminus](https://github.com/usetrmnl/terminus) server. It handles
+authentication and token rotation, validates requests and responses, and keeps
+the underlying HTTP contract visible.
+
+## Compatibility
+
+SDK `0.1.x` supports exactly Terminus tag `0.71.0`, commit
+[`e0cf90d8ef6d7bc16dfbac8ebab910a9fda9de56`](https://github.com/usetrmnl/terminus/commit/e0cf90d8ef6d7bc16dfbac8ebab910a9fda9de56).
+It makes no compatibility claim for Terminus `main`, older releases, or later
+releases.
+
+Python 3.12 or newer is required.
+
+## Install
+
+Add the SDK to an uv project:
+
+```sh
+uv add trmnl-terminus
+```
+
+Or install it with pip:
+
+```sh
+python -m pip install trmnl-terminus
+```
+
+To work from source, clone this repository and create its locked environment:
+
+```sh
+git clone https://github.com/hsperker/trmnl-terminus-sdk.git
+cd trmnl-terminus-sdk
+uv sync --locked
+```
+
+## Quick start
+
+Terminus authenticates with an email address and password. Keep both outside
+your source code:
+
+```sh
+export TERMINUS_BASE_URL="https://terminus.example.test"
+export TERMINUS_EMAIL="you@example.test"
+export TERMINUS_PASSWORD="..."
+```
+
+Then inspect your devices without changing the server:
+
+```python
+import os
+
+from pydantic import SecretStr
+
+from trmnl_terminus import Credentials, TerminusClient
+
+credentials = Credentials(
+    email=os.environ["TERMINUS_EMAIL"],
+    password=SecretStr(os.environ["TERMINUS_PASSWORD"]),
+)
+
+with TerminusClient(
+    os.environ["TERMINUS_BASE_URL"],
+    credentials=credentials,
+) as client:
+    for device in client.devices.list():
+        print(device.id, device.label, device.playlist_id)
+```
+
+The client logs in on demand. It rotates access and refresh tokens when needed
+and never writes them to disk unless you supply a `TokenStore`.
+
+## Examples
+
+The repository includes two runnable examples:
+
+| Example | What it proves | Server changes |
+| --- | --- | --- |
+| [`examples/list_resources.py`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/examples/list_resources.py) | Lists models, devices, screens, and playlists | None |
+| [`examples/render_screen.py`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/examples/render_screen.py) | Creates an HTML screen, downloads its rendered image, then deletes the screen | Temporary screen |
+
+Run the read-only example after setting the three variables above:
+
+```sh
+uv run python examples/list_resources.py
+```
+
+Rendering requires an explicit mutation opt-in. Remote-screen deletion runs in
+a `finally` block, so cleanup is attempted even when the image download fails:
+
+```sh
+TERMINUS_ALLOW_MUTATIONS=1 \
+  uv run python examples/render_screen.py rendered-screen.png
+```
+
+To prove the full path on real hardware, use the guarded
+[`physical-device proof workflow`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/scripts/run_device_smoke.py).
+It creates a temporary playlist and screen, assigns them to an existing device,
+waits for visual confirmation, restores the original playlist, and cleans up.
+Read the
+[`real-server smoke guide`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/docs/real-server-smoke.md)
+before running it.
+
+Playlist assignment does not wake a device. The new image appears on its next
+scheduled poll, power cycle, or manual refresh.
+
+## Supported API
+
+| Resource | Operations in `0.1` |
+| --- | --- |
+| `client.models` | `list()` |
+| `client.devices` | `list()`, `get(id)`, `update(id, DevicePatch(...))` |
+| `client.screens` | `list()`, `create(...)`, `delete(id)`, `read_bytes(...)`, `download(...)` |
+| `client.playlists` | `list()`, `get(id)`, `create(...)`, `update(...)`, `delete(id)` |
+| `client.request(...)` | Raw escape hatch for unsupported Server API endpoints |
+
+Device updates deliberately support playlist assignment only. Terminus
+`0.71.0` also lacks a native screen lookup endpoint, so the SDK does not fake
+one by fetching every screen. The
+[SDK specification](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/docs/specs/terminus-sdk.md)
+defines the complete boundary and wire contract.
+
+## Errors and secrets
+
+HTTP failures raise typed `TerminusError` subclasses. Server responses that use
+RFC Problem Details are available as structured `ProblemDetails` on response
+errors. The original `httpx.Response` remains available for debugging, but
+exception strings do not include credentials, tokens, request bodies, or
+response bodies.
+
+TLS certificate verification is enabled by default. For a private certificate
+authority, pass an `ssl.SSLContext`; the examples never disable verification.
+
+## Development
+
+uv owns the development environment and lockfile:
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src examples
+uv build --no-sources
+```
+
+The test suite uses mocked HTTP boundaries. Live server and physical-device
+checks are separate, guarded workflows because they create and delete real
+resources.
+
+Maintainers should follow the
+[`release checklist`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/docs/releasing.md);
+publishing uses a GitHub environment and PyPI Trusted Publishing instead of a
+stored API token.
+
+## License
+
+MIT. See
+[`LICENSE`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/LICENSE).

trmnl_terminus-0.1.0/README.md

@@ -0,0 +1,161 @@
+# TRMNL Terminus Python SDK
+
+`trmnl-terminus` is a small, synchronous Python client for automating a
+self-hosted [Terminus](https://github.com/usetrmnl/terminus) server. It handles
+authentication and token rotation, validates requests and responses, and keeps
+the underlying HTTP contract visible.
+
+## Compatibility
+
+SDK `0.1.x` supports exactly Terminus tag `0.71.0`, commit
+[`e0cf90d8ef6d7bc16dfbac8ebab910a9fda9de56`](https://github.com/usetrmnl/terminus/commit/e0cf90d8ef6d7bc16dfbac8ebab910a9fda9de56).
+It makes no compatibility claim for Terminus `main`, older releases, or later
+releases.
+
+Python 3.12 or newer is required.
+
+## Install
+
+Add the SDK to an uv project:
+
+```sh
+uv add trmnl-terminus
+```
+
+Or install it with pip:
+
+```sh
+python -m pip install trmnl-terminus
+```
+
+To work from source, clone this repository and create its locked environment:
+
+```sh
+git clone https://github.com/hsperker/trmnl-terminus-sdk.git
+cd trmnl-terminus-sdk
+uv sync --locked
+```
+
+## Quick start
+
+Terminus authenticates with an email address and password. Keep both outside
+your source code:
+
+```sh
+export TERMINUS_BASE_URL="https://terminus.example.test"
+export TERMINUS_EMAIL="you@example.test"
+export TERMINUS_PASSWORD="..."
+```
+
+Then inspect your devices without changing the server:
+
+```python
+import os
+
+from pydantic import SecretStr
+
+from trmnl_terminus import Credentials, TerminusClient
+
+credentials = Credentials(
+    email=os.environ["TERMINUS_EMAIL"],
+    password=SecretStr(os.environ["TERMINUS_PASSWORD"]),
+)
+
+with TerminusClient(
+    os.environ["TERMINUS_BASE_URL"],
+    credentials=credentials,
+) as client:
+    for device in client.devices.list():
+        print(device.id, device.label, device.playlist_id)
+```
+
+The client logs in on demand. It rotates access and refresh tokens when needed
+and never writes them to disk unless you supply a `TokenStore`.
+
+## Examples
+
+The repository includes two runnable examples:
+
+| Example | What it proves | Server changes |
+| --- | --- | --- |
+| [`examples/list_resources.py`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/examples/list_resources.py) | Lists models, devices, screens, and playlists | None |
+| [`examples/render_screen.py`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/examples/render_screen.py) | Creates an HTML screen, downloads its rendered image, then deletes the screen | Temporary screen |
+
+Run the read-only example after setting the three variables above:
+
+```sh
+uv run python examples/list_resources.py
+```
+
+Rendering requires an explicit mutation opt-in. Remote-screen deletion runs in
+a `finally` block, so cleanup is attempted even when the image download fails:
+
+```sh
+TERMINUS_ALLOW_MUTATIONS=1 \
+  uv run python examples/render_screen.py rendered-screen.png
+```
+
+To prove the full path on real hardware, use the guarded
+[`physical-device proof workflow`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/scripts/run_device_smoke.py).
+It creates a temporary playlist and screen, assigns them to an existing device,
+waits for visual confirmation, restores the original playlist, and cleans up.
+Read the
+[`real-server smoke guide`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/docs/real-server-smoke.md)
+before running it.
+
+Playlist assignment does not wake a device. The new image appears on its next
+scheduled poll, power cycle, or manual refresh.
+
+## Supported API
+
+| Resource | Operations in `0.1` |
+| --- | --- |
+| `client.models` | `list()` |
+| `client.devices` | `list()`, `get(id)`, `update(id, DevicePatch(...))` |
+| `client.screens` | `list()`, `create(...)`, `delete(id)`, `read_bytes(...)`, `download(...)` |
+| `client.playlists` | `list()`, `get(id)`, `create(...)`, `update(...)`, `delete(id)` |
+| `client.request(...)` | Raw escape hatch for unsupported Server API endpoints |
+
+Device updates deliberately support playlist assignment only. Terminus
+`0.71.0` also lacks a native screen lookup endpoint, so the SDK does not fake
+one by fetching every screen. The
+[SDK specification](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/docs/specs/terminus-sdk.md)
+defines the complete boundary and wire contract.
+
+## Errors and secrets
+
+HTTP failures raise typed `TerminusError` subclasses. Server responses that use
+RFC Problem Details are available as structured `ProblemDetails` on response
+errors. The original `httpx.Response` remains available for debugging, but
+exception strings do not include credentials, tokens, request bodies, or
+response bodies.
+
+TLS certificate verification is enabled by default. For a private certificate
+authority, pass an `ssl.SSLContext`; the examples never disable verification.
+
+## Development
+
+uv owns the development environment and lockfile:
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src examples
+uv build --no-sources
+```
+
+The test suite uses mocked HTTP boundaries. Live server and physical-device
+checks are separate, guarded workflows because they create and delete real
+resources.
+
+Maintainers should follow the
+[`release checklist`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/docs/releasing.md);
+publishing uses a GitHub environment and PyPI Trusted Publishing instead of a
+stored API token.
+
+## License
+
+MIT. See
+[`LICENSE`](https://github.com/hsperker/trmnl-terminus-sdk/blob/main/LICENSE).

trmnl_terminus-0.1.0/docs/real-server-smoke.md

@@ -0,0 +1,135 @@
+# Real-server smoke test
+
+The smoke test creates and deletes screens and playlists. It never changes a
+device or its assigned playlist.
+
+Run it only against a server intended for mutation. Supply configuration through
+the process environment; do not create a repository `.env` file:
+
+```sh
+export TERMINUS_BASE_URL='https://terminus.example.test'
+export TERMINUS_EMAIL='smoke-user@example.test'
+read -rs TERMINUS_PASSWORD
+export TERMINUS_PASSWORD
+export TERMINUS_ALLOW_MUTATION_TESTS=1
+uv run python scripts/run_real_smoke.py
+```
+
+The runner prints no configured URL, email, password, or tokens. It gives every
+resource a random suffix and deletes all created resources even when an assertion
+fails. Cleanup failure makes the run fail.
+
+## Physical-device proof
+
+The guarded device runner temporarily assigns its own playlist and screen to one
+existing device, waits for visual confirmation, then restores the device's original
+playlist assignment:
+
+```sh
+export TERMINUS_BASE_URL='https://terminus.example.test'
+export TERMINUS_EMAIL='device-proof-user@example.test'
+read -rs TERMINUS_PASSWORD
+export TERMINUS_PASSWORD
+export TERMINUS_DEVICE_ID=123
+export TERMINUS_ALLOW_DEVICE_MUTATIONS=1
+uv run python scripts/run_device_smoke.py
+```
+
+Use a positive device ID for a device that already has a playlist. An unassigned
+device cannot be used because SDK v0.1 intentionally cannot restore
+`playlist_id: null`.
+
+Playlist assignment does not wake a physical device. When the runner says the
+temporary display is assigned, use the device's normal manual refresh or power-cycle
+action. Type `seen` only after the device visibly shows the heading
+`SDK DEVICE PROOF`; the prompt times out after ten minutes.
+
+The runner restores the original assignment and verifies it before deleting the
+temporary playlist and screen. Any proof, restoration, or cleanup failure makes the
+run fail. If restoration cannot be verified, deletion is skipped and the uniquely
+SDK-prefixed resources remain for manual recovery. The runner does not print
+configuration values, resource identifiers, labels, HTML, device details, response
+bodies, passwords, or tokens.
+
+## Latest developer evidence
+
+On 2026-09-09, the guarded physical-device proof passed against public Terminus
+commit `2d91851b2c038f9964ffb066e4a765b3e88121d2`. Through the public typed SDK, the
+runner created and attached a temporary screen and playlist, assigned the
+playlist, and verified the assignment by reading it back.
+
+After a manual device wake, the user saw the black `SDK DEVICE PROOF` heading
+centered on a white background within a solid black frame. The runner then
+restored and read back the original assignment, deleted both temporary resources,
+and exited zero. An independent audit through `devices.list()`, `screens.list()`,
+and `playlists.list()` required exactly one device, confirmed a non-null current
+playlist assignment, and found zero screens or playlists with the proof prefix.
+
+That Terminus revision is an untagged commit after 0.71.0. This is developer
+evidence only; it is not the release proof required against a clean 0.71.0
+instance with controlled session settings.
+
+## Developer evidence
+
+An existing server can prove that the user-facing path works in that deployment.
+It cannot prove release compatibility unless its Terminus tag and resolved
+commit are known independently.
+
+The default developer run proves:
+
+- login and raw-token authorization;
+- model listing;
+- playlist and HTML-screen creation;
+- screen-list readback of the created resource;
+- a real rendered-image download;
+- ordered playlist replacement and readback;
+- cleanup.
+
+Set `TERMINUS_REFRESH_WAIT_SECONDS` only when the server has a short access-token
+lifetime. The runner then waits, makes another request, and requires both access
+and refresh tokens to rotate.
+
+Mutation replay is intentionally absent. Terminus 0.71.0 can keep a previously
+issued access token valid after refresh, and without session expiration that
+token is long-lived. The SDK recovers after a mutating 401 but leaves any retry
+to the caller because the server-side conditions for safe automatic replay
+cannot be proven.
+
+## Release evidence
+
+A release run starts with clean storage and a Terminus checkout at the proposed
+tag and resolved commit. Register the first user through Terminus's supported
+registration flow; Terminus verifies the first account automatically. Confirm
+that startup seeded at least one model.
+
+Use matching short values for `API_ACCESS_TOKEN_PERIOD`,
+`SESSION_LIFETIME_LIMIT`, and `SESSION_INACTIVITY_LIMIT`, then set
+`TERMINUS_REFRESH_WAIT_SECONDS` long enough to enter the SDK's two-second refresh
+window. Record the tag, commit, image identifier if used, and smoke result in the
+release evidence. Never record credentials or tokens.
+
+### Terminus 0.71.0 release proof
+
+On 2026-09-08, the upstream `0.71.0` tag independently resolved to commit
+`e0cf90d8ef6d7bc16dfbac8ebab910a9fda9de56`. The official image was
+`ghcr.io/usetrmnl/terminus:0.71.0` with canonical multi-platform index digest
+`sha256:18b672e4958a5a274822b6e34e76b92bcd0a8b483b7728fa559d4fab342262c7`;
+the exercised ARM64 manifest digest was
+`sha256:a5e2f322ea30fbaa5c2630ae02dcbaa6bfc44d889d92228050f4df8d7bb0c462`.
+The image labels reported the same version and commit.
+
+The proof used a uniquely named disposable project, fresh PostgreSQL and Valkey
+volumes, and a localhost-only web binding. The first account was created through
+the CSRF-protected `/register` form, and the SDK returned at least one synchronized
+model. `API_ACCESS_TOKEN_PERIOD`, `SESSION_LIFETIME_LIMIT`, and
+`SESSION_INACTIVITY_LIMIT` were each 60 seconds. With a 49.2-second refresh wait
+and the runner's two-second skew, the unchanged smoke runner reported
+`PASS: real screen, image, playlist, and cleanup` after requiring both access and
+refresh token values to change.
+
+That run covered HTML-screen rendering, a non-empty rendered-image download,
+screen list readback, ordered playlist replacement and readback, and deletion of
+the created screen and playlist. A separate clean-stack pass followed cleanup
+with an API check and found no matching smoke resources. Final host-side
+inspection found zero project containers, networks, volumes, or temporary runtime
+files.

trmnl_terminus-0.1.0/docs/releasing.md

@@ -0,0 +1,59 @@
+# Releasing `trmnl-terminus`
+
+Releases are built and published by
+[`release.yml`](../.github/workflows/release.yml). Do not upload a local build
+or store a PyPI API token in GitHub.
+
+## One-time setup for the first release
+
+1. Create a GitHub environment named `pypi`. Restrict it to protected tags and,
+   if desired, require a maintainer's approval.
+2. In your PyPI account's **Publishing** settings, add a pending GitHub
+   publisher with these exact values:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI project name | `trmnl-terminus` |
+   | GitHub owner | `hsperker` |
+   | GitHub repository | `trmnl-terminus-sdk` |
+   | Workflow filename | `release.yml` |
+   | Environment name | `pypi` |
+
+A pending publisher does not reserve the PyPI name. It becomes a normal
+publisher when the first upload succeeds.
+
+## Release checklist
+
+1. Set the version with `uv version <version>` and commit the updated
+   `pyproject.toml` and `uv.lock`.
+2. Run the same checks as CI:
+
+   ```sh
+   uv sync --locked
+   uv run pytest -q
+   uv run ruff check .
+   uv run ruff format --check .
+   uv run mypy src examples
+   uv build --no-sources
+   ```
+
+3. Merge the release commit to `main` and wait for CI to pass.
+4. Create and push an annotated tag whose value matches `pyproject.toml`:
+
+   ```sh
+   git tag -a v0.1.0 -m v0.1.0
+   git push origin v0.1.0
+   ```
+
+The release workflow checks the tag against the package version, reruns the
+source checks, builds the wheel and source distribution, installs and tests
+both artifacts, generates attestations, and then publishes through the `pypi`
+environment.
+
+After the workflow finishes, verify the project page and install it without a
+source checkout:
+
+```sh
+uv run --no-project --with trmnl-terminus \
+  python -c "import trmnl_terminus; print('install ok')"
+```