API Reference¶
The public surface of the dory package. Import the entry point with:
This page documents version 1.2.0 of the dory package (Python 3.10 or newer).
Everything importable from dory¶
| Group | Names |
|---|---|
| Clients | DoryClient, RabbitMQClient, MetadataClient, Authenticator |
| Configuration | Config, DoryConfig |
| Errors | AuthError, MetadataError, SubscriptionRefused, UnknownEventType, LensNotAccessible, InvalidRegion, RegionTooFine, TooManyCells, TooManySensors, QuotaExceeded, BrokerUnavailable, SubscriptionError, SubscriptionTimeout, SubscriptionNotFound |
Two helpers live in submodules and are not re-exported from dory:
| Import | What it is |
|---|---|
from dory.rabbitmq import describe_subscription_error, SUBSCRIPTION_ERROR_MESSAGES |
The plain sentence for each subscription error code. |
from dory.errors import REFUSALS_BY_CODE |
A dict from each refusal code to its exception class, e.g. "TOO_MANY_SENSORS" → TooManySensors. |
DoryClient¶
The main entry point. Constructing it authenticates and fetches platform metadata — the broker connection details and the list of valid event types.
DoryClient(
client_id: str | None = None,
client_secret: str | None = None,
*,
authenticator: Authenticator | None = None,
metadata: dict | None = None,
metadata_client: MetadataClient | None = None,
connection_factory: Callable | None = None,
)
client_id,client_secret— app-client credentials. Fall back toDORY_CLIENT_ID/DORY_CLIENT_SECRETwhen omitted.authenticator,metadata,metadata_client,connection_factory— advanced, keyword-only: offline construction and tests. Omit them all for normal use. Passingmetadataskips the metadata request entirely;connection_factoryreplaces how the broker connection is opened.
Raises
AuthError— no credentials in the arguments or the environment, or the token request fails.MetadataError— the metadata request fails.RuntimeError— the metadata response carries no broker endpoint.
Constructing without network I/O
DoryClient.from_metadata(metadata: dict, authenticator: Authenticator, *, connection_factory=None) -> DoryClient
A classmethod that builds a client from a metadata dict you already hold. It performs no network I/O at construction time.
Properties & methods
| Member | Signature | Description |
|---|---|---|
rabbitmq |
property → RabbitMQClient |
The event client. Created lazily on first access. |
get_metadata() |
(refresh: bool = False) -> dict |
The platform metadata the client was configured from (eventTypes, mqEndpoint, mqPort, mqVhost, mqExchange). Cached at construction; refresh=True re-fetches it, but does not rebuild the broker configuration or the event-type list — construct a new client for that. Raises AuthError / MetadataError. |
get_subscription() |
(subscription_id: str) -> dict |
Shorthand for RabbitMQClient.get_subscription(). |
wait_until_ready() |
(subscription_id: str, timeout: float = 60.0) -> dict |
Shorthand for RabbitMQClient.wait_until_ready(). |
list_subscriptions() |
() -> list[dict] |
Every subscription of this credential that has not been deleted, across sessions: pending (still being provisioned), active, and error (with lastErrorCode saying why). Each dict includes id, name, description, status, queueName, eventTypes, geohashes, coverage (the report once provisioned, else null), lastErrorCode (one of the error codes on an error subscription, else null), boundSensorCount, createdAt, updatedAt, activatedAt. List entries do not carry lensAlias; read one with get_subscription() for that. Raises AuthError (no token) and RuntimeError (the platform answered with an error). |
close() |
() -> None |
Closes the event client, unsubscribing everything created this session. |
RabbitMQClient¶
Accessed via client.rabbitmq. Manages subscriptions and event consumption.
sequenceDiagram
participant App as Your code
participant SDK as RabbitMQClient
participant API as Dory API
participant Q as Delivery queue
App->>SDK: subscribe(event_types, geohash_regions, lens_alias, callback)
SDK->>API: create subscription
API-->>SDK: accepted (202): id, queue name, status "pending"
SDK->>Q: start consuming on a background thread
SDK-->>App: subscription id (returns at once)
App->>SDK: wait_until_ready(id, timeout)
Note over API,Q: the platform matches sensors, starts processors<br/>and binds the queue in the background
Q-->>SDK: event (can arrive before "ready")
SDK-->>App: callback(event)
Q-->>SDK: control message "ready" + coverage report
SDK-->>App: coverage report
Note over SDK,API: if timeout expires first: one get_subscription() call,<br/>then SubscriptionTimeout only if the platform still says neither active nor error
Figure 1. subscribe() returns the id as soon as the platform accepts the request; wait_until_ready() resolves on the ready control message that arrives in the same queue as the events, and asks the platform once only if the wait expires.
subscribe()¶
subscribe(
event_types: list[str],
geohash_regions: list[str],
lens_alias: str,
callback: Callable[[dict], None] | None = None,
name: str | None = None,
) -> str | None
Registers the subscription — the platform accepts it at once — and starts a background consumer on its delivery queue. Returns the subscription id immediately; events begin when provisioning finishes, and may arrive before the ready control message. Call wait_until_ready() for the coverage report.
The annotation stays str | None for compatibility with an older platform that could answer without an id; the current platform always returns one. A region with nothing in it is a live subscription with an empty coverage report, not None.
Arguments
| Argument | Type | Notes |
|---|---|---|
event_types |
list[str] |
At least one. Checked locally against the platform's event-type list when the client fetched one (an unknown type raises ValueError before any request); otherwise the platform refuses with UnknownEventType. |
geohash_regions |
list[str] |
At least one. Each cell is one to nine characters, or ['*'] alone for everywhere your organization can see. |
lens_alias |
str |
The lens to run — one of your organization's own, or a public one. Must not be blank. |
callback |
callable |
Required despite the None default. Receives one argument, the event dict. Control messages never reach it. |
name |
str |
Optional. Shown in the portal and in list_subscriptions(). When omitted the platform assigns Subscription <ISO timestamp>. |
Delivery
- Events are consumed on a background daemon thread, one per subscription.
- Events may arrive before the
readycontrol message — a processor can start publishing before the report is written. - Delivery is at-least-once: key your handling on the event's
message_id. A callback that raises is logged and the message is still acknowledged, so it is not redelivered.
Raises
ValueError— emptyevent_typesorgeohash_regions, a blanklens_alias, nocallback, or an event type not in the platform's list.SubscriptionRefusedand its eight subclasses — one per refusal reason, each carrying.status,.codeand.api_message. See Exceptions.RuntimeError— a refusal with no code. A 404 without a code is still raised asLensNotAccessible.AuthError— no access token can be obtained.
wait_until_ready()¶
Blocks until the platform has provisioned the subscription and returns its coverage report ({} if the platform sent none). Provisioning ends with a ready control message in the subscription's own queue, which the consumer thread records; this call waits for that. If nothing arrives within timeout seconds, the platform is asked once through get_subscription() — a consumer that connected late may have missed the message — and SubscriptionTimeout is raised only if the platform does not report it active or error either. Events that arrive while waiting are delivered normally.
Raises
SubscriptionError— the platform reported the subscription as failed (anerrorcontrol message, orget_subscription()sayserror). Its.codeis one of the subscription error codes.SubscriptionTimeout— still pending aftertimeout, and the platform agrees. It keeps being provisioned in the background: call again, or readget_subscription().SubscriptionNotFound— the subscription is gone (raised by the timeout check, which can also surfaceget_subscription()'sRuntimeErrorandAuthError).ValueError— a blank subscription id.
Ids from another session
For a subscription this process did not create there is no consumer thread to record the ready message, so the call waits the full timeout before its single check with the platform. Use get_subscription() for those.
get_subscription()¶
The pull side: reads one subscription from the platform. The dict includes id, name, description, status (pending / active / error), coverage, lastErrorCode (one of the error codes while status is error, else null), queueName, eventTypes, geohashes, lensAlias, boundSensorCount, createdAt, updatedAt, activatedAt. It carries the error code only, never the platform's internal diagnostic.
It also refreshes the SDK's local view of that subscription, so a later subscription_status() or wait_until_ready() sees what the platform said. For an error subscription the local view's message is describe_subscription_error(lastErrorCode).
Raises
ValueError— a blank subscription id.SubscriptionNotFound— no such subscription is visible to this credential: missing, or another organization's.RuntimeError— any other error from the platform, including a 403 when the subscription belongs to another credential of your organization.AuthError— no access token can be obtained.
subscription_status()¶
What this client has heard about a subscription so far, with no I/O. Returns {"status": ..., "coverage": ..., "error": ...}, where error is {"code": ..., "message": ...} only while status is error and None otherwise. The code and message come from the error control message, or — after get_subscription() — from lastErrorCode and its sentence. Returns None for an id this client has never heard of, and for one it has unsubscribed.
stateDiagram-v2
[*] --> pending: subscribe returned an id
pending --> active: ready control message, or get_subscription reports active
pending --> error: error control message, or get_subscription reports error
active --> active: updated control message replaces the coverage report
pending --> [*]: unsubscribe accepted, or already gone
active --> [*]: unsubscribe accepted, or already gone
error --> [*]: unsubscribe accepted, or already gone
Figure 2. The local status the SDK keeps per subscription and the messages that move it — exactly what subscription_status() returns and what wait_until_ready() waits on.
unsubscribe()¶
Stops the local consumer thread (if this process started one) and asks the platform to delete the subscription. The request is accepted at once: the delivery queue is removed immediately, so no more events arrive; the processors behind it are released in the background. Works on any id this credential owns, including ones from list_subscriptions(). A subscription that is already gone is a successful no-op.
Raises
ValueError— a blank subscription id.RuntimeError— the platform cannot be reached, or refuses (a 403 means the subscription belongs to another credential). In both cases the local entry is kept so you can callunsubscribe()again.AuthError— no access token can be obtained.
close()¶
Best-effort unsubscribe of every subscription created by this client; never raises.
The coverage report¶
Returned by wait_until_ready(), carried by the ready and updated control messages, and stored as coverage on the subscription. It says, per requested event type, whether the subscription is receiving it and if not why, followed by four counts.
{
"event_types": {
"person": { "covered": true },
"vehicle": { "covered": false, "reason": "NO_TEMPLATE_EMITS_IT" }
},
"sensors_matched": 4,
"sensors_served": 4,
"processors_started": 3,
"processors_reused": 1
}
reason |
Meaning |
|---|---|
NO_SENSORS_IN_REGION |
No active sensor your organization can see — its own, or a public one — has an area of view overlapping the region. |
NO_TEMPLATE_EMITS_IT |
No template in the lens with a live version emits that event type. |
NO_COMPATIBLE_SENSOR |
A template emits it, but none runs on the type of sensor the region matched. |
LENS_NOT_ACCESSIBLE |
The lens is no longer usable by your organization — deleted, or made private by its owner. |
| Count | Meaning |
|---|---|
sensors_matched |
Sensors whose area of view overlaps the region. |
sensors_served |
Matched sensors for which at least one processor serves this subscription. |
processors_started |
Processors the platform started for this subscription on the run that produced the report; a re-check counts only what it added. |
processors_reused |
Processors that already existed for the same sensor and template on that run, and are shared with this one. |
The report contains counts only — never sensor names, coordinates or processor identities.
An all-uncovered report is not an error
A region with nothing to serve leaves the subscription active with every type uncovered. The platform re-checks every active subscription hourly and sends an updated control message when coverage changes — when a sensor is installed or published, a template is attached, or the lens is opened again.
Control messages¶
The platform reports a subscription's progress in its own delivery queue, alongside the events. The SDK tells the two apart by the message's AMQP type property and handles control messages itself.
flowchart TB
M["Message from the delivery queue"] --> T{"AMQP type starts with<br/>dory.subscription. ?"}
T -->|"no — an event"| CB["Parse JSON → your callback(event)<br/>acknowledged after it returns, even if it raised"]
T -->|"yes — a control message"| K{"which one?"}
K -->|ready| R["status = active<br/>coverage = report<br/>wait_until_ready() returns the report"]
K -->|updated| U["coverage = new report<br/>status unchanged"]
K -->|error| E["status = error, code + message<br/>wait_until_ready() raises SubscriptionError"]
R --> ACK["acknowledged — never handed to your callback"]
U --> ACK
E --> ACK
Figure 3. Every message on the delivery queue is sorted by its AMQP type property; control messages update the SDK's local view of the subscription and are acknowledged without ever reaching the callback, everything else is an event.
| Control message | Effect on the local view |
|---|---|
ready |
Status becomes active and the coverage report is stored; a pending wait_until_ready() returns it. |
updated |
The coverage report is replaced; status is unchanged. Arrives whenever coverage changes, for example after the hourly re-check. |
error |
Status becomes error with the platform's code and message; a pending wait_until_ready() raises SubscriptionError. |
A control message of an unrecognised kind is acknowledged and ignored. None of them is ever handed to your callback.
Older SDK versions
An SDK older than 1.2.0 keeps receiving events unchanged, but it does not recognise control messages: it sees each one as an ordinary callback call whose payload carries subscription_id and status instead of event data.
Subscription error codes¶
A subscription in error stays that way; the remedy is always to delete it and subscribe again. Why it failed reaches you as a code, in three places: SubscriptionError.code, subscription_status(id)["error"]["code"], and lastErrorCode from get_subscription() and list_subscriptions(). See When a subscription is in error for what to do with each.
| Code | Meaning | Sentence |
|---|---|---|
BROKER_REFUSED |
The message broker refused a request while the subscription was being set up; retrying the same set-up cannot fix it. | "The platform couldn't set up this subscription. Delete it and try again; if it keeps failing, contact support with the subscription ID." |
PROVISIONING_FAILED |
Setting it up kept failing on temporary problems until the platform ran out of attempts. | Same as BROKER_REFUSED. |
QUEUE_ORPHANED |
The delivery queue could not be created, and the platform could not clean up after it. | "This subscription could not be set up. Delete it and subscribe again." |
LEGACY_RESUBSCRIBE |
The subscription was created before the current delivery system. | "This subscription was created before the current delivery system. Delete it and subscribe again." |
from dory.rabbitmq import describe_subscription_error, SUBSCRIPTION_ERROR_MESSAGES
describe_subscription_error(code: str | None) -> str
describe_subscription_error()returns the sentence for a code. An unknown code, orNone, gets theBROKER_REFUSED/PROVISIONING_FAILEDsentence. It never raises.SUBSCRIPTION_ERROR_MESSAGESis thedict[str, str]behind it, keyed by the four codes above.
The error control message carries the same code and sentence, so SubscriptionError.message and the local view's message match these. The portal shows the same codes in its own words.
MetadataClient¶
Importable as from dory import MetadataClient; construct it with an Authenticator. You normally never need it — client.get_metadata() returns the same response, cached.
get() returns platform metadata, including eventTypes (the valid event-type slugs) and the broker connection details (mqEndpoint, mqPort, mqVhost, mqExchange).
Raises: AuthError (no access token can be obtained), MetadataError (the request fails or the platform answers with an error).
Authenticator¶
Handles the OAuth 2.0 client-credentials flow. DoryClient builds one for you; construct it yourself only to share it between clients or to pass it to DoryClient.from_metadata(). See Authentication.
Authenticator(client_id: str | None = None, client_secret: str | None = None)
get_access_token(force_refresh: bool = False) -> str
- The constructor falls back to
DORY_CLIENT_ID/DORY_CLIENT_SECRETand raisesAuthErrorwhen neither source supplies both values. get_access_token()returns a cached token until shortly before it expires, then requests a new one;force_refresh=Truediscards the cached token. RaisesAuthErrorif the token request fails or returns no token.- The token is requested with these scopes:
rabbitmq/read:all,subscriptions/read:self,subscriptions/write:self,subscriptions/delete:self,metadata/read:all.
Configuration¶
The SDK reads its settings from the environment. See Configuration for the setup walkthrough.
| Variable | Required | Default | Purpose |
|---|---|---|---|
DORY_CLIENT_ID |
Yes* | — | App-client id. |
DORY_CLIENT_SECRET |
Yes* | — | App-client secret. |
DORY_COGNITO_DOMAIN |
No | The production platform | Token issuer; /oauth2/token is appended. |
DORY_API_ROOT_URL |
No | The production platform | Base URL of the REST API. |
DORY_HTTP_TIMEOUT |
No | 10 |
Seconds to wait on each HTTP request the SDK makes (token, metadata, subscriptions). Unset, empty, unparseable or non-positive values fall back to the default. |
* Required unless you pass client_id / client_secret to DoryClient(...) or Authenticator(...).
Values are resolved lazily, on every access, so setting a variable after import dory takes effect immediately. A variable that is set but empty counts as unset and falls back to its default. A trailing slash on a URL is stripped.
Config — a lazy facade: each attribute re-reads the environment when accessed. Attributes: COGNITO_DOMAIN, TOKEN_URL, API_ROOT_URL, API_METADATA_ENDPOINT, API_HELLO_ENDPOINT, API_SUBSCRIPTIONS_ENDPOINT, HTTP_TIMEOUT, OAUTH2_SCOPES, ENV_CLIENT_ID, ENV_CLIENT_SECRET; Config.snapshot() returns a DoryConfig.
DoryConfig — an immutable snapshot. DoryConfig.from_env() builds one from the current environment with the fields cognito_domain, api_root_url, http_timeout, and the derived properties token_url, metadata_endpoint, hello_endpoint, subscriptions_endpoint.
Exceptions¶
flowchart LR
EX["Exception"] --> AE["AuthError"]
EX --> ME["MetadataError"]
EX --> RT["RuntimeError"]
EX --> TO["TimeoutError"]
TO --> ST["SubscriptionTimeout<br/>.subscription_id .status"]
RT --> SR["SubscriptionRefused<br/>.status .code .api_message"]
RT --> SE["SubscriptionError<br/>.subscription_id .code .message"]
RT --> SN["SubscriptionNotFound<br/>.subscription_id"]
SR --> C1["UnknownEventType"]
SR --> C2["LensNotAccessible"]
SR --> C3["InvalidRegion"]
SR --> C4["RegionTooFine"]
SR --> C5["TooManyCells"]
SR --> C6["TooManySensors"]
SR --> C7["QuotaExceeded"]
SR --> C8["BrokerUnavailable"]
Figure 4. The class hierarchy that decides which except clause catches what: every refusal and post-acceptance failure is a RuntimeError, but SubscriptionTimeout is a TimeoutError and the auth and metadata errors are plain Exceptions.
| Class | Base | code |
HTTP status | Raised when | Attributes |
|---|---|---|---|---|---|
SubscriptionRefused |
RuntimeError |
any other code, e.g. INVALID_REQUEST |
400 for INVALID_REQUEST |
subscribe() was refused with a code that has no class of its own (a malformed request). |
.status, .code, .api_message |
UnknownEventType |
SubscriptionRefused |
UNKNOWN_EVENT_TYPE |
400 | One or more requested event types are not known to the platform. | as base |
LensNotAccessible |
SubscriptionRefused |
LENS_NOT_ACCESSIBLE |
404 | No lens by that alias is usable from your organization — unknown, or private to another. Both get the same answer. Also raised for a 404 that carries no code. | as base |
InvalidRegion |
SubscriptionRefused |
INVALID_REGION |
400 | A geohash is malformed, or * was mixed with cells. |
as base |
RegionTooFine |
SubscriptionRefused |
REGION_TOO_FINE |
422 | A cell is longer than nine characters. | as base |
TooManyCells |
SubscriptionRefused |
TOO_MANY_CELLS |
422 | More distinct cells than the platform allows, after nested cells collapse into their parent. | as base |
TooManySensors |
SubscriptionRefused |
TOO_MANY_SENSORS |
422 | The region would match more sensors than one subscription may start processors for. Ask for a smaller area. | as base |
QuotaExceeded |
SubscriptionRefused |
QUOTA_EXCEEDED |
422 | Your organization already holds as many live subscriptions as it may. Delete one first. | as base |
BrokerUnavailable |
SubscriptionRefused |
BROKER_UNAVAILABLE |
502 | The message broker did not accept the subscription's queue — retry. Normally nothing is left behind; if the platform could not clean up either, an error subscription with code QUEUE_ORPHANED appears in list_subscriptions(): delete it. |
as base |
SubscriptionError |
RuntimeError |
one of the subscription error codes, or None |
— | wait_until_ready(): the platform reported the subscription as failed after accepting it. |
.subscription_id, .code, .message |
SubscriptionTimeout |
TimeoutError |
— | — | wait_until_ready(): still not active or error after timeout, and the platform agrees. Not a RuntimeError — except RuntimeError does not catch it. |
.subscription_id, .status |
SubscriptionNotFound |
RuntimeError |
— | 404 | get_subscription() (and wait_until_ready() through it): no such subscription is visible to this credential — missing, or another organization's. (Another credential's subscription in your organization is a 403, raised as a plain RuntimeError.) |
.subscription_id |
AuthError |
Exception |
— | — | Credentials are missing, or a token cannot be obtained. | — |
MetadataError |
Exception |
— | — | Platform metadata cannot be retrieved. | — |
ValueError |
— | — | — | Invalid arguments to subscribe() (empty lists, blank lens alias, no callback, an event type not in the platform's list), or a blank id to unsubscribe(), get_subscription(), wait_until_ready(). |
— |
RuntimeError (plain) |
— | — | — | A subscribe() refusal with no code (other than a 404); unsubscribe() when the platform cannot be reached or refuses with anything but 404; get_subscription() on any error but 404; list_subscriptions() on any error; DoryClient(...) when the metadata has no broker endpoint. |
— |
On every refusal class, .code is the class's own code and .status the HTTP status the platform answered with. A class catches its subclasses, so except SubscriptionRefused catches all eight refusals.
Network failures
The token request and the metadata request wrap network failures in AuthError and MetadataError, and unsubscribe() wraps them in RuntimeError. subscribe(), get_subscription() and list_subscriptions() do not: a timeout or a dropped connection there surfaces as the requests library's own exception, such as requests.Timeout.
The platform bounds behind the refusal classes:
- a region cell is at most 9 characters (
RegionTooFine); - at most 64 distinct cells per subscription, after nested cells collapse (
TooManyCells); - at most 200 matched sensors per subscription (
TooManySensors); - at most 100 live subscriptions per organization (
QuotaExceeded).