Adapter

Structural contract for a device plugin adapter.

Usage

Source

Adapter()

A plugin exposes a no-argument create_plugin() factory (named by the descriptor’s integration.adapter.entry_point) returning an adapter, which the host drives through a strict lifecycle: open binds descriptor and services, execute runs one operation, next_event polls a subscription, and close releases the session. Construction and open stay free of device I/O; each session uses a fresh adapter instance.

Examples

A minimal read-only adapter skeleton:

class DemoAdapter:
    async def open(self, descriptor, services, context): ...
    async def execute(self, request, context): ...
    async def next_event(self, subscription_id, context): ...
    async def close(self, context): ...

See Also

HostServices

scoped services handed over at open.

OperationContext

identity, deadline, and cancellation per operation.

Methods

Name Description
close() Release the adapter session; tolerate repeated calls.
execute() Run one operation and return its result envelope.
next_event() Return the next pending event for a subscription, or None.
open() Bind the adapter to its descriptor and scoped host services.

close()

Release the adapter session; tolerate repeated calls.

Usage

Source

close(context)

execute()

Run one operation and return its result envelope.

Usage

Source

execute(request, context)

Implementations call context.mark_dispatch_started() immediately before the first transmit, honour the context deadline and cancellation, never retry silently, and preserve uncertain outcomes: a failure after dispatch is reported with status "unknown" rather than "error".

Parameters
request: dict[str, Any]

Operation envelope with exactly operation_id, verb and arguments.

context: OperationContext
Identity, deadline, and cancellation state for the operation.
Returns
dict
Result envelope: operation_id, verb, status ("ok", "error" or "unknown") and either data or an error object carrying code, message and dispatch_state.

next_event()

Return the next pending event for a subscription, or None.

Usage

Source

next_event(subscription_id, context)

open()

Bind the adapter to its descriptor and scoped host services.

Usage

Source

open(descriptor, services, context)

Called once per session before any other method. Implementations keep construction and open free of device I/O and defer all transport to the supplied services.

Parameters
descriptor: dict[str, Any]

The plugin’s validated device descriptor.

services: HostServices

Scoped host services for transport, clocks, and evidence.

context: OperationContext
Context for the open operation itself.