Skip to content

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.

DoryApp().run(MyProcessor)

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.