Skip to content

API Reference

The public surface of the dory package. Import the entry point with:

from dory import DoryClient

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 to DORY_CLIENT_ID / DORY_CLIENT_SECRET when omitted.
  • authenticator, metadata, metadata_client, connection_factory — advanced, keyword-only: offline construction and tests. Omit them all for normal use. Passing metadata skips the metadata request entirely; connection_factory replaces 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 ready control 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 — empty event_types or geohash_regions, a blank lens_alias, no callback, or an event type not in the platform's list.
  • SubscriptionRefused and its eight subclasses — one per refusal reason, each carrying .status, .code and .api_message. See Exceptions.
  • RuntimeError — a refusal with no code. A 404 without a code is still raised as LensNotAccessible.
  • AuthError — no access token can be obtained.

wait_until_ready()

wait_until_ready(subscription_id: str, timeout: float = 60.0) -> dict

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 (an error control message, or get_subscription() says error). Its .code is one of the subscription error codes.
  • SubscriptionTimeout — still pending after timeout, and the platform agrees. It keeps being provisioned in the background: call again, or read get_subscription().
  • SubscriptionNotFound — the subscription is gone (raised by the timeout check, which can also surface get_subscription()'s RuntimeError and AuthError).
  • 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()

get_subscription(subscription_id: str) -> dict

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()

subscription_status(subscription_id: str) -> dict | None

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()

unsubscribe(subscription_id: str) -> None

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 call unsubscribe() again.
  • AuthError — no access token can be obtained.

close()

close() -> None

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, or None, gets the BROKER_REFUSED / PROVISIONING_FAILED sentence. It never raises.
  • SUBSCRIPTION_ERROR_MESSAGES is the dict[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.

MetadataClient(authenticator: Authenticator)
get() -> dict

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_SECRET and raises AuthError when neither source supplies both values.
  • get_access_token() returns a cached token until shortly before it expires, then requests a new one; force_refresh=True discards the cached token. Raises AuthError if 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).