API Reference¶
A focused index of the Dory Processor SDK's public surface — the classes, methods, and helpers you actually call or override. Names without an explicit module are exported from the top-level dory package. Each entry links to the topic page with full detail.
Writing a processor¶
You build a processor by subclassing BaseProcessor and implementing run(). The other lifecycle methods are optional — they have sensible defaults. See Core Concepts.
from dory import DoryApp, BaseProcessor, stateful
class MyProcessor(BaseProcessor):
counter = stateful(0) # auto-saved/restored across migration
async def run(self):
async for _ in self.run_loop(interval=1):
self.counter += 1
if __name__ == "__main__":
DoryApp().run(MyProcessor)
BaseProcessor¶
BaseProcessor(context=None) — base class for every processor. The context is injected for you by DoryApp; subclasses normally don't define __init__.
| Method | Signature | When |
|---|---|---|
run |
async def run(self) -> None |
Required. Your main loop. Runs after startup and state restore. |
startup |
async def startup(self) -> None |
Optional. Initialize resources (load a model, open connections). Default: no-op. |
shutdown |
async def shutdown(self) -> None |
Optional. Clean up on graceful shutdown. Default: no-op. |
get_state |
def get_state(self) -> dict |
Optional. Return a JSON-serializable state dict to migrate. Default: collects stateful attributes. |
restore_state |
async def restore_state(self, state: dict) -> None |
Optional. Restore from a prior state dict. Default: restores stateful attributes. |
Helpers available on self:
| Method | Signature | Purpose |
|---|---|---|
run_loop |
run_loop(interval=1.0, check_migration=True) |
Async iterator that yields an iteration count until shutdown is requested. The clean way to write a loop. |
is_shutting_down |
is_shutting_down() -> bool |
True once a graceful shutdown has begun. |
span |
span(name, attributes=None) |
Context manager that records an OpenTelemetry span around a block. Always safe to call — a no-op when tracing is inactive. See Observability. |
publish |
async def publish(self, event_type, location, payload, *, headers=None, exchange=None) -> None |
Publish one event; await it. event_type is an event type slug your template version declares. location is a GeoPoint, which the SDK encodes into the routing key. payload is a dict sent exactly as passed, so pass MessageEnvelope(payload=...).to_dict(). headers are sent alongside the trace context. Leave exchange unset. Raises ValueError for an empty event type or an out-of-range coordinate, and RuntimeError when no publisher is configured (a local run without the platform). See Output & Events. |
Optional fault-handling hooks — override to customize recovery; each has a safe default:
| Hook | Signature | Default |
|---|---|---|
on_state_restore_failed |
async def on_state_restore_failed(self, error) -> bool |
Return True to start from a clean baseline, False to crash. Default: True. |
on_rapid_restart_detected |
async def on_rapid_restart_detected(self, restart_count) -> bool |
Handle a restart loop. Default: True (continue). |
on_health_check_failed |
async def on_health_check_failed(self, error) -> bool |
Return True to retry the health check. Default: False. |
reset_caches |
def reset_caches(self) -> None |
Clear in-memory caches on a clean reset. Default: no-op. |
ExecutionContext¶
Passed to your processor as self.context. Read pod metadata and check lifecycle state through it.
| Member | Signature | Purpose |
|---|---|---|
pod_name, pod_namespace, processor_id |
attributes | Identity of the running pod. |
is_migrating, previous_pod_name, attempt_number |
attributes | Migration / restart context. |
is_shutdown_requested |
is_shutdown_requested() -> bool |
Poll this in a custom loop to exit gracefully. |
is_migration_imminent |
is_migration_imminent() -> bool |
True shortly before a forced shutdown. |
config |
config() -> dict |
App configuration from the environment (credentials excluded). A method, not a property. |
get_env |
get_env(key, default=None) -> str | None |
Read a single env var, including credentials. |
logger |
logger() -> Logger |
Logger pre-tagged with pod context. |
DoryApp¶
DoryApp(config_file=None, log_level=None) — the entry point. Call .run(ProcessorClass) to boot the processor and block until shutdown.
DoryConfig¶
DoryConfig(startup_timeout_sec=30, shutdown_timeout_sec=30, health_port=8080, state_backend="configmap", log_level="INFO") — the typed config schema. See Configuration.
State¶
stateful is the simple way to persist class attributes across a migration; the lower-level types are exported for advanced use. See State Management.
| Symbol | Signature | Purpose |
|---|---|---|
stateful |
stateful(default) |
Class-attribute descriptor; the value is auto-saved and restored across migration. |
StatefulVar |
type | The descriptor type produced by stateful. |
Resilience¶
Helpers for tolerating flaky dependencies. See Resilience.
| Symbol | Purpose |
|---|---|
CircuitBreaker |
Fail-fast wrapper around a flaky dependency. |
CircuitState |
CLOSED / OPEN / HALF_OPEN. |
CircuitOpenError |
Raised when calling through an open breaker. |
retry_with_backoff |
Decorator that retries an async function with exponential backoff. |
RetryPolicy |
Retry configuration (attempts, delays). |
RetryBudget |
Caps the share of requests retried within a time window, to avoid retry storms. |
These are imported from dory.resilience.
Observability¶
| Symbol | Module | Purpose |
|---|---|---|
get_logger |
dory.logging |
Structured logger that matches the SDK's log format. |
MetricsCollector |
dory.metrics |
Record custom metrics — set_gauge(name, value, labels=None) and inc_counter(name, value=1.0, labels=None). |
See Observability. For spans, use self.span(...) on your processor (above).
Edge & failover¶
Building blocks for active/standby edge deployments. Node-level failover itself is the orchestrator's job — see Edge & Failover and Orchestrator edge failover.
| Symbol | Signature | Purpose |
|---|---|---|
FencingManager |
FencingManager(config=None) |
Epoch-based fencing lock that prevents split-brain. |
FencingConfig |
FencingConfig(acquire_timeout_sec=10.0, lock_ttl_sec=60.0, refresh_interval_sec=15.0, backend="redis", redis_url=None, key_prefix="dory:fencing") |
Fencing settings. |
FencingToken |
dataclass | A held lock; is_valid(current_epoch). |
RoleManager |
RoleManager(processor_id, node_id, fencing_config=None, start_as_standby=False) |
PRIMARY/STANDBY state machine. |
ProcessorRole |
enum | INITIALIZING, PRIMARY, STANDBY, DRAINING, FENCED, STOPPED. |
RoleTransition |
dataclass | A record of a role change. |
HeartbeatManager |
HeartbeatManager(config=None) |
Liveness reporter; .status is a property. |
HeartbeatConfig |
HeartbeatConfig(interval_sec=10.0, ...) |
Heartbeat settings. |
ConnectivityStatus |
enum | Connectivity verdict reported by HeartbeatManager.status. |
EdgeHealthReporter |
EdgeHealthReporter(heartbeat_manager=None, role_manager=None) |
Aggregates edge health. |
Edge errors: FencingError (base), FenceViolation (token went stale mid-operation), StaleEpochError.
Output & location¶
The types you pass to self.publish(...), and the helpers that produce a location. See Output & Events.
| Symbol | Module | Signature | Purpose |
|---|---|---|---|
GeoPoint |
dory.geo |
GeoPoint(lat, lng) |
The location argument of publish. It is the only source of the location in the routing key. |
MessageEnvelope |
dory.output |
MessageEnvelope(payload=...), then .to_dict() |
The standard envelope. You supply payload; it fills in schema_version, message_id and timestamp. Build a new one for every event. |
CameraGeolocalizer |
dory.geo |
CameraGeolocalizer(reference_points, method=GeoMethod.HOMOGRAPHY) |
Estimates where a detection is from calibration points: at least four with HOMOGRAPHY, three with TRILATERATION. .estimate(box) returns a GeoPoint; .estimate_batch(boxes) returns a list. |
ReferencePoint |
dory.geo |
ReferencePoint(image_x, image_y, lat, lng) |
One calibration point linking a pixel to a coordinate. |
BoundingBox |
dory.geo |
BoundingBox(left, top, width, height) |
A detection box in pixels. Its bottom-centre is the point projected. |
GeoMethod |
dory.geo |
enum | HOMOGRAPHY (flat ground) or TRILATERATION (scattered points). |
estimate_location, estimate_locations_batch |
dory.geo |
(box or boxes, reference_points, method=GeoMethod.HOMOGRAPHY) |
One-call forms of CameraGeolocalizer. For repeated estimates from one camera, build the geolocalizer once. |
Routing helpers¶
publish builds the routing key for you, as ‹processor id›.‹event type›.‹geohash of your location, one character per segment›. You never build it yourself. dory.output also exports two routing helpers, and neither produces the key publish sends:
| Symbol | Signature | Purpose |
|---|---|---|
build_routing_key |
build_routing_key(event_type, segment_length=1) -> str |
Builds a key from the environment: the processor id and the sensor's geohash from DORY_GEOHASH, not from a location you pass. Each part is left out when it isn't set. |
get_geohash |
get_geohash(precision=9) |
Returns the sensor's geohash from DORY_GEOHASH (or from DORY_LATITUDE + DORY_LONGITUDE in local development), or None when neither is set. Cached after the first call. |
Subscriptions never filter on a key's geohash segments. A subscriber's queue is bound by processor and event type only. See Who receives an event.
Errors¶
These exceptions (and the edge errors above) subclass DoryError; the resilience errors such as CircuitOpenError do not. See Core Concepts.
| Symbol | Raised when |
|---|---|
DoryError |
Base for all SDK errors. |
DoryStartupError |
Startup failed (startup() raised or timed out). |
DoryShutdownError |
Graceful shutdown timed out. |
DoryStateError |
State save/restore failed. |
DoryConfigError |
Invalid configuration. |
Simple API¶
For minimal processors that don't need a class. See Getting Started.
| Symbol | Module | Purpose |
|---|---|---|
processor |
dory.simple |
Decorator that turns an async function into a processor. |
state |
dory.simple |
Declare an auto-persisted variable — state(default). |
run_processor |
dory.simple |
Run a function as a processor without the decorator. |
from dory.simple import processor, state
counter = state(0)
@processor
async def tick(ctx):
async for _ in ctx.run_loop(interval=1):
counter.value += 1
Note
The installed package version is available as dory.__version__. The envelope and location types are not exported from the top-level dory package: import them from dory.output and dory.geo, as in Output & location.