Configuration¶
The SDK takes your credentials and, optionally, overrides for the platform endpoints and for the HTTP timeout it applies to every request it makes. The broker connection details and the list of valid event types are fetched from the platform when the client is constructed; they are never read from the environment.
flowchart LR
subgraph yours["Set by you"]
env["Environment variables<br/>DORY_CLIENT_ID · DORY_CLIENT_SECRET<br/>DORY_COGNITO_DOMAIN · DORY_API_ROOT_URL · DORY_HTTP_TIMEOUT"]
args["DoryClient(client_id=…, client_secret=…)"]
end
subgraph fetched["Fetched from the platform"]
meta["Metadata<br/>broker endpoint · port · vhost · exchange<br/>valid event types"]
end
client(["DoryClient()"])
args -->|"credentials only — win over the environment"| client
env -->|"read when used, not at import — empty counts as unset"| client
client -->|"fetched once, at construction"| meta
meta -->|"broker settings and event-type list, kept for the client's life"| client
Environment variables¶
| Variable | Required | Default | Purpose |
|---|---|---|---|
DORY_CLIENT_ID |
Yes* | — | App-client ID (M2M credential) |
DORY_CLIENT_SECRET |
Yes* | — | App-client secret |
DORY_COGNITO_DOMAIN |
No | The production platform | OAuth token issuer (/oauth2/token is appended) |
DORY_API_ROOT_URL |
No | The production platform | Base URL for the Dory REST API (/metadata and /subscriptions are appended) |
DORY_HTTP_TIMEOUT |
No | 10 |
Seconds to wait on any single HTTP request the SDK makes (token, metadata, subscriptions). Decimals allowed; an empty, non-numeric, zero or negative value means the default. |
* Required unless you pass client_id / client_secret directly to DoryClient(...).
With neither endpoint variable set, the SDK talks to the production platform. Set them only when you have been given the addresses of another environment.
export DORY_CLIENT_ID="your client id"
export DORY_CLIENT_SECRET="your client secret"
# Override endpoints only if you target a non-default environment:
# export DORY_API_ROOT_URL="https://api.example.org/v1"
# export DORY_COGNITO_DOMAIN="https://auth.example.org"
# Give a slow network more time per request (seconds, default 10):
# export DORY_HTTP_TIMEOUT="30"
How values are resolved¶
- Constructor argument, then environment, then default. A
client_id/client_secretpassed toDoryClient(...)wins over the environment variable. The endpoints and the timeout have no constructor argument: the environment variable if set, else the built-in default. - Read when used, not at import. Nothing is frozen when you
import dory, so a variable set any time before the client is constructed is honoured — from a.envloader or a test fixture, say. Credentials are read once, when the client is constructed; the endpoint and timeout variables are re-read on every request, so a change made later applies to the next call. - Empty counts as unset. A variable set to the empty string falls back to the default — or, for a credential, is treated as missing.
- A trailing
/is stripped fromDORY_COGNITO_DOMAINandDORY_API_ROOT_URLbefore/oauth2/token,/metadataand/subscriptionsare appended, so both spellings work. - A timeout that cannot be used is ignored.
DORY_HTTP_TIMEOUTaccepts a positive number of seconds, decimals included (2.5). Anything else — empty, non-numeric,0or negative — means the default of 10, so a typo cannot turn every request into an instant failure.
Credentials in code (alternative)¶
Prefer environment variables so secrets don't live in source control. Only the credentials can be passed this way — the endpoints and the timeout are set through the environment alone.
Timeouts¶
A subscriber meets three timeouts: one you configure through the environment, one that is fixed, and one you pass as an argument on each call.
| Timeout | Set by | Default | What it bounds |
|---|---|---|---|
| HTTP request | DORY_HTTP_TIMEOUT |
10 s | Every single HTTP request the SDK makes: the token request, the metadata fetch during construction, and each create, read, list and delete of a subscription. |
| Broker connection | fixed | 10 s | Opening the connection each subscription's consumer uses to read your delivery queue — a 10-second socket timeout and a single connection attempt. Not configurable. |
wait_until_ready(subscription_id, timeout=60.0) |
the timeout argument |
60 s | How long to wait for the platform's ready or error control message. When it expires, the SDK checks with the platform once: it returns the coverage report if the subscription is now active, raises SubscriptionError if it is in error, raises SubscriptionNotFound if it is gone, and otherwise raises SubscriptionTimeout. |
sequenceDiagram
participant App as Your app
participant SDK as DoryClient
participant Token as Token endpoint
participant API as Dory API
participant MQ as Delivery queue
App->>SDK: DoryClient()
SDK->>Token: request access token — DORY_HTTP_TIMEOUT (default 10 s)
Token-->>SDK: token
SDK->>API: fetch metadata — DORY_HTTP_TIMEOUT
API-->>SDK: broker settings + event types
App->>SDK: rabbitmq.subscribe(...)
SDK->>API: create subscription — DORY_HTTP_TIMEOUT
API-->>SDK: accepted (status pending) + subscription id
SDK-->>App: subscription id
SDK->>MQ: connect, on a background thread — 10 s socket timeout, one attempt (fixed)
App->>SDK: wait_until_ready(id, timeout=60)
MQ-->>SDK: ready control message
Note over SDK,API: if the timeout expires first, the SDK reads the subscription once — DORY_HTTP_TIMEOUT
SDK-->>App: coverage report
When the HTTP timeout fires, the call fails instead of hanging. Which error you see depends on the call:
| Call | What is raised |
|---|---|
| The token request | AuthError, from whichever call needed the token — so DoryClient() fails at construction rather than blocking forever against an unreachable network |
| The metadata fetch | MetadataError — at construction, or from get_metadata(refresh=True) |
unsubscribe() |
RuntimeError telling you to call unsubscribe() again; the local consumer has already been stopped and the local entry is kept |
subscribe(), get_subscription(), list_subscriptions(), and the check wait_until_ready() makes when its own timeout expires |
The underlying requests timeout error (requests.exceptions.Timeout) is raised as is |
When the broker connection times out, the SDK prints an error and that subscription's consumer thread ends — it does not retry. The subscription itself still exists on the platform, so unsubscribe it and subscribe again — the SDK cannot reattach a consumer to an existing subscription, so restarting the process without unsubscribing leaves the old one in place; see Consuming Events.
When wait_until_ready() times out, provisioning has not stopped — the platform keeps working on the subscription in the background. The SDK checks with the platform once before raising, because the ready message may never have reached this client: its consumer may have failed to connect, or the subscription was made by another process. SubscriptionTimeout (a TimeoutError, not a RuntimeError) means the platform did not report the subscription active or error either. Call wait_until_ready() again, or read client.get_subscription(subscription_id). See Managing Subscriptions.
Give a large region more time
Provisioning uses (or starts) one processor per matched sensor and template, so the work grows with the number of sensors a region matches. Pass a larger timeout for a large region — the SDK's own example uses timeout=120.
Fetched automatically¶
When you construct DoryClient, the SDK calls the platform's metadata endpoint once and reads:
- the broker endpoint, port, vhost, and exchange used for event delivery, and
- the list of valid event types (used to validate
subscribe()calls before any request is made).
Both are kept for the life of the client. If the response is incomplete:
- No broker endpoint — construction fails with an error; nothing can be delivered without one.
- Port, vhost or exchange missing — the SDK assumes port
5671, vhost/and exchangeevents. - No event types — the SDK prints a warning and skips its local validation;
subscribe()then relies on the platform, which still refuses an unknown type withUnknownEventType.
You can inspect the response yourself:
metadata = client.get_metadata()
print(metadata["eventTypes"])
print(metadata["mqEndpoint"], metadata["mqPort"], metadata["mqVhost"], metadata["mqExchange"])
get_metadata() returns the response cached at construction. get_metadata(refresh=True) re-fetches it from the platform but does not rebuild the client's broker settings or event-type list — construct a new client for that.
Inspecting the effective configuration¶
from dory import Config
print(Config.COGNITO_DOMAIN, Config.API_ROOT_URL, Config.TOKEN_URL, Config.HTTP_TIMEOUT)
snapshot = Config.snapshot() # a frozen DoryConfig
print(snapshot.cognito_domain, snapshot.api_root_url, snapshot.http_timeout)
print(snapshot.token_url, snapshot.metadata_endpoint, snapshot.subscriptions_endpoint)
Config.X re-reads the environment on every access, so it follows later changes. Config.snapshot() returns a frozen DoryConfig — cognito_domain, api_root_url and http_timeout, plus the derived token_url, metadata_endpoint and subscriptions_endpoint — that keeps the values it was built with. Both Config and DoryConfig are importable from dory.
Advanced: reusing fetched metadata¶
from dory import Authenticator, DoryClient
client = DoryClient.from_metadata(metadata, Authenticator(client_id, client_secret))
DoryClient.from_metadata(...) builds a client from a metadata response you fetched earlier — the dict client.get_metadata() returns — so construction makes no network call; the same fallbacks for an incomplete response apply, and the first call that needs a token requests one then. Useful when you cache the platform's metadata yourself.
Dependencies¶
Python 3.10 or newer. The SDK requires pika>=1.3.0 (RabbitMQ client) and requests>=2.28.0 (HTTP); both install automatically with pip install -e . from a clone of the repository — the package is not on PyPI (see Getting Started).
Related pages¶
- Authentication
- Getting Started
- Managing Subscriptions —
wait_until_ready()and the subscription lifecycle - Consuming Events — the broker connection each subscription opens
- API Reference