Skip to content

Getting Started

The Application SDK (dory-consumer-sdk) is a Python library for building apps that consume events from Dory. You authenticate with app-client credentials, subscribe to event types over geographic regions, and receive matching events in real time through a callback. A subscription is accepted at once and provisioned in the background; the SDK tells you when it is ready and what it covers.

Which SDK is this?

This is the SDK for consuming events. If you are building the processors that produce events, you want the Processor SDK instead.

Prerequisites

  • Python 3.10 or newer
  • An app client (client_id + client_secret) for your organization — created in the Portal. Ask your org admin if you don't have access.
  • A lens to subscribe through — one your organization created in the Portal, or a public lens shared by another organization. You'll reference it by its alias.

See Core Concepts if "lens", "region" or "coverage report" are unfamiliar.

Install

The SDK is not on PyPI, so pip install by package name will not find it. Install it from a clone of the backend repository instead:

cd sdk/python
pip install -e .

This installs the dory-consumer-sdk package, which you import as dory, together with its dependencies (pika, requests).

Set your credentials

The SDK reads credentials from the environment by default:

export DORY_CLIENT_ID="your client id"
export DORY_CLIENT_SECRET="your client secret"

(You can also pass them directly to DoryClient(...), but environment variables keep secrets out of your code. See Configuration.)

Your first subscriber

import time
from dory import DoryClient

def handle_event(event: dict):
    # Your app logic — every matching event arrives here as a dict.
    print(f"Event received: {event}")

# Authenticates and loads platform metadata on construction.
client = DoryClient()  # reads DORY_CLIENT_ID / DORY_CLIENT_SECRET from the environment

subscription_id = client.rabbitmq.subscribe(
    event_types=["person", "moving"],   # what  — see client.get_metadata()["eventTypes"]
    geohash_regions=["dhxpfr5"],         # where — 1–9 characters each, or ["*"] for everywhere you can see
    lens_alias="demo-lens",              # how   — your lens, or a public one
    callback=handle_event,
)

# Accepted at once; the platform provisions it in the background.
coverage = client.rabbitmq.wait_until_ready(subscription_id, timeout=120)
print(f"Ready. Coverage: {coverage}")

# Events arrive on a background thread — keep the program alive.
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    pass

client.rabbitmq.unsubscribe(subscription_id)
client.close()

Run it. subscribe() returns the subscription ID straight away. wait_until_ready() then blocks until provisioning finishes and returns the coverage report, which says, for each event type you asked for, whether it is covered and, if not, why. The report also counts how many sensors were matched and served and how many processors were started or reused. After that, events print as the matched sensors see activity. Some may print even before the report does, because delivery can start before provisioning is complete.

An example report:

{
  "event_types": {
    "person": { "covered": true },
    "moving": { "covered": false, "reason": "NO_TEMPLATE_EMITS_IT" }
  },
  "sensors_matched": 3,
  "sensors_served": 3,
  "processors_started": 2,
  "processors_reused": 1
}

An event type that is not covered is not an error, even when no type is covered. The subscription is live. The platform re-checks it every hour and sends an updated message whenever coverage changes. reason names why a type is uncovered right now:

  • NO_SENSORS_IN_REGION: no sensor's area of view overlaps your regions.
  • NO_TEMPLATE_EMITS_IT: no template in the lens produces that type.
  • NO_COMPATIBLE_SENSOR: a template produces it, but not for the kinds of sensor that matched.
  • LENS_NOT_ACCESSIBLE: the lens has since been deleted, or made private by another organization that owns it.

What just happened

sequenceDiagram
    participant App as Your app (SDK)
    participant API as Dory API
    participant Q as Your delivery queue
    participant Prov as Dory provisioning (background)
    participant Proc as Processors

    App->>API: subscribe(event_types, regions, lens_alias)
    API->>Q: create the delivery queue
    API->>Prov: request provisioning
    API-->>App: accepted — subscription ID, status: pending
    Note over App,Q: subscribe() returns here and the SDK starts consuming the queue at once
    Prov->>Proc: match sensors by area of view, start or reuse one processor per sensor × template
    Prov->>Q: bind processors to the queue
    Prov->>Q: control message: ready {coverage report}
    Q-->>App: ready → wait_until_ready() returns the coverage report (status: active)
    Note over Proc,App: events can arrive before ready — control messages never reach your callback
    loop while subscribed
        Proc->>Q: event
        Q-->>App: callback(event)
    end
    App->>API: unsubscribe(subscription_id) — the SDK stops its consumer first
    API->>Q: delete the queue — delivery stops at once
    API-->>App: accepted — status: deleting
    Prov->>Proc: shortly after, release processors no other subscription uses
  1. DoryClient() authenticated with your credentials and fetched platform metadata (valid event types and the broker endpoint). See Authentication.
  2. subscribe(...) asked the platform for a subscription.

    • The SDK first checked your event types against the metadata. The platform then validated the request, accepted it (status pending), created its delivery queue and returned the subscription ID at once. The SDK started consuming the queue immediately.
    • Provisioning then happened in the background. The platform matched every active sensor whose area of view overlaps your regions. That includes your organization's own sensors and any public ones, and a camera watching the block counts even if it stands outside it.
    • It then chose the templates from your lens that produce the event types you asked for. It started one processor per sensor × template, or reused one that another subscription already runs, and bound those processors to your queue.

    See Managing Subscriptions, and Core Concepts for how regions are written. 3. wait_until_ready(...) blocked until the platform's ready control message arrived in your delivery queue, then returned the coverage report. The subscription is now active. Events may already have arrived before that message. Delivery is at-least-once, so key on the event's message_id if duplicates matter to you. 4. Each event was delivered to your callback as a parsed JSON object. Your regions choose which sensors are watched; they do not filter individual events. Every event of your requested types from those sensors' processors is delivered, whatever position the event carries. The platform's own control messages (ready / updated / error) travel in the same queue, but the SDK handles them and they never reach your callback. See Consuming Events. 5. unsubscribe(...) stopped the SDK's background consumer, then asked the platform to delete the subscription. The platform accepted the request (status deleting) and removed the delivery queue within it, so delivery stopped at once. Shortly after, in the background, it released the processors no other subscription was using. close() does the same for every subscription this client created and has not yet deleted.

If something goes wrong

What you see Why What to do
LensNotAccessible The alias has a typo, or the lens is private to another organization. Check the alias on the portal's Lenses page, or use a public lens.
ValueError: Unknown event type(s), or UnknownEventType if the platform refused it The platform does not know that event type. Check client.get_metadata()["eventTypes"].
InvalidRegion A region is not a valid geohash, or "*" was mixed with cells. Pass cells only, or ["*"] on its own.
RegionTooFine, TooManyCells, TooManySensors, QuotaExceeded The request is over a platform bound: a cell longer than nine characters, more than 64 distinct cells, more than 200 matched sensors, or more than 100 live subscriptions in your organization. Use shorter cells, fewer cells or a smaller area, or first delete a subscription you no longer need.
BrokerUnavailable The platform's broker did not accept the subscription's queue. Nothing was left behind. Try again.
wait_until_ready() returns a report with every type uncovered Nothing matched in your regions produces those types right now. Nothing to fix: reason says why. The subscription is live and fills in as sensors, lenses and templates change.
SubscriptionTimeout The subscription is still being provisioned in the background. The SDK asks the platform once before raising, so a ready message it missed does not cause a false alarm. Call wait_until_ready() again, or read client.get_subscription(subscription_id).
SubscriptionError The platform could not set up the subscription. The error's code says why, and its message says what to do. Delete it with client.rabbitmq.unsubscribe(subscription_id) and subscribe again. If it keeps failing, contact support with the subscription ID.

Every refusal from the platform that carries a reason code is a SubscriptionRefused, which is a RuntimeError; any other platform failure is a plain RuntimeError, and SubscriptionError is a RuntimeError too. There are two exceptions:

  • The SDK's own checks run before anything is sent: an empty event-type or region list, a missing lens alias or callback, or an unknown event type. These raise ValueError.
  • SubscriptionTimeout is a TimeoutError, because the subscription is still being provisioned.

The shipped example catches RuntimeError first and then any other exception. The full list is in Managing Subscriptions.

Subscriptions outlive your process

If your script is killed before unsubscribe() — a Ctrl-C at the wrong moment, a crash — the subscription stays live on the platform. Any later process using the same app client can find it with client.list_subscriptions() and delete it with client.rabbitmq.unsubscribe(subscription_id). The app client's details dialog in the Portal also lists its subscriptions, and lets anyone allowed to delete subscriptions remove them.

Where to go next