API reference

Use the quickstart for your first script. This reference is for looking up signatures and return values. Import the public pyaviso module.

For motivation and when-to-use-this guidance on individual surfaces, see the narrative pages. The async client is documented on the Async page; HTTP methods return awaitables on the async client. listen() returns an async iterator directly, without await.

Clients

class pyaviso.AvisoClient(
    *,
    base_url: str | None = None,
    auth: AuthProvider | Anonymous | None = None,
    timeout: float | None = None,
    user_agent: str | None = None,
    state_store: StateStore | None = None,
    heartbeat_interval: float | None = None,
    danger_accept_invalid_certs: bool | None = None,
    flush_cursor_on_exit: bool | None = None,
)

Every argument is optional. What is not given is taken from the environment, then the aviso config file, then the default; see Configuration for the order.

Discover schemas

schema() -> SchemaCatalog
schema_for(event_type) -> SchemaResponse

Receive notifications

listen(event_type=None, *, filter=None, start_from=None, until=None, mode=None, triggers=None, request=None) -> NotificationIterator | FunctionTriggerIterator (without mode, the listener stays live, unless until is given, which ends it like mode="replay_only"; triggers is a Sequence[Trigger]; the returned iterator is also a context manager via with and supports iterator.close() for explicit teardown)

start_from is int | str | None. Integers are exclusive sequence positions; 0 requests retained history after zero. A UTC string such as "2026-06-01T00:00:00Z" selects publication time. None uses saved state if available, otherwise the live edge. An explicit start overrides saved state. The value’s type selects the meaning, so sequence numbers must be unquoted; see Start from a specific position. Use mode="replay_only" with a start position to end at the replay boundary. See State and resume for checkpoint limits.

until is int | str | None: the end point of a replay. An integer is the last sequence to deliver, inclusive; a UTC string ends with the last notification published at or before that time. until implies mode="replay_only" and needs start_from. See Stop at an end point.

listen_many(listeners, *, start_from=None, until=None, mode=None, on_error=None) -> MultiNotificationIterator

listeners maps a name to a dict of listen() keywords (event_type, filter, start_from, until, mode, triggers) or to a WatchRequest. The start_from, until and mode given here apply to dict entries that set none. The loop yields (name, notification). on_error is "raise" (or None, the default), "continue" or a function taking (name, error); see Error handling. Arguments are checked before any listener opens, the shared start_from, until and mode included. A mistake in the structure of listeners (not a mapping, an empty or non-string name, an unknown key, a missing event_type) or an invalid on_error raises TypeError or ValueError. An invalid listen() argument inside an entry raises what listen() would. When the mistake belongs to one entry, the message names that listener.

Publish notifications (providers)

notify(*, event_type, identifier=None, payload=None) -> NotifyResponse
notify_many(notifications, *, concurrency=0) -> list[NotifyResult]

notify_many takes a sequence of notification dicts and returns results in input order. concurrency=0 limits it to 16 in-flight requests. A batch is not atomic; inspect each result. See Publishing.

identifier is a mapping from strings to JSON-compatible Python values. The same applies to each notification passed to notify_many. Structured values such as point-cloud lists are sent as JSON arrays. Cyclic containers are not valid JSON and raise TypeError. Identifier input deeper than 100 nested containers raises ValueError before conversion.

Supply every identifier field defined by the server when publishing, even fields optional in filters. payload=None omits the payload; the schema decides whether a payload is required.

Admin operations (operators)

wipe_stream(stream_name) -> None
wipe_all() -> None
delete_notification(notification_id) -> None

These remove retained data and require appropriate permission. A publish response’s request ID is not a notification ID.

What the client resolved

config -> ResolvedConfig: every setting with its value and source, the credential by kind and source only. Safe to log.
pyaviso.resolve_config(*, base_url=None, auth=None, timeout=None, heartbeat_interval=None, danger_accept_invalid_certs=None) -> ResolvedConfig: the same report for those arguments, without building a client.

ResolvedConfig has base_url (SourcedValue | None), timeout, heartbeat_interval, ca_bundle, danger_accept_invalid_certs (each a SourcedValue with .value and .source), auth (ResolvedAuth | None with .kind, .source and .refused), config_file, credentials_file, and as_dict(). See Configuration.

Constructor options and lifecycle

base_url includes the HTTP or HTTPS scheme; when None it comes from AVISO_BASE_URL or the config file, and ConfigError is raised if neither has one. auth=None searches the environment and the credential files; see Authentication. Pass auth=pyaviso.Anonymous() to send no credentials. state_store=None does not persist checkpoints. flush_cursor_on_exit=False leaves the final pending cursor unflushed; enabling it does not acknowledge completed work. See shutdown behavior.

timeout and heartbeat_interval are seconds. When None, each comes from the config file if it is set there; otherwise timeout imposes no request timeout and heartbeat_interval uses 30 seconds as the expected server heartbeat interval (it does not set the server’s cadence). timeout bounds ordinary requests such as notify and schema; it does not apply to listen, whose stream is meant to stay open. user_agent=None uses aviso/<crate-version>. danger_accept_invalid_certs=None keeps certificate validation enabled unless the config file’s tls: block turns it off.

Use with client.listen(...) to close a synchronous listener. The synchronous client’s own __enter__ / __exit__ do not close its listeners. The async client is not an async context manager; use async with on its iterator.

pyaviso.AsyncAvisoClient is the same shape. notify / schema / notify_many / schema_for / wipe_* / delete_notification return awaitables; listen returns an AsyncNotificationIterator.

Value types

pyaviso.Notification(event_type, sequence, identifier, payload, cloudevent=None)

Properties: event_type, sequence, identifier, payload, cloudevent. Method: as_dict(). Unhashable (the payload may be a dict).

str(notification) formats the original cloudevent as indented JSON. For a manually constructed notification without cloudevent, it formats event_type, sequence, identifier, and payload instead. as_dict() returns the client convenience fields, including cloudevent when present. repr(notification) remains a compact debugging summary. Identifier values retain the JSON shape emitted by the server.

pyaviso.NotifyResponse(status, request_id, processed_at)

Properties: status, request_id, processed_at. Method: as_dict().

pyaviso.NotifyResult (returned by notify_many)

Properties: zero-based index, boolean ok, response (NotifyResponse on success, otherwise None) and error (exception on failure, otherwise None).

pyaviso.SchemaCatalog

Properties: status, event_types, total_schemas, schema. Method: as_dict(). The schema property is a dict keyed by event type, whose values match the per-event-type schema below.

pyaviso.SchemaResponse

Properties: status, event_type, schema. Method: as_dict(). The schema is a dict with two keys: payload (a {"required": bool} shape) and identifier (a dict keyed by identifier field name, each value naming the validator type, the required flag (which gates whether a filter or watch call must include the field, not whether a notify call must), and any type-specific metadata).

Watch shape

pyaviso.WatchRequest

Constructors:

WatchRequest.watch(event_type)
WatchRequest.watch_from(event_type, start_from)
WatchRequest.replay_only(event_type, start_from, *, until=None)

Builders: .with_filter(dict), .with_triggers(list). Properties: event_type, mode.

pyaviso.WatchMode is a str + Enum with members WATCH = "watch" and REPLAY_ONLY = "replay_only".

pyaviso.NotificationIterator and pyaviso.AsyncNotificationIterator: returned by listen. The sync one implements __iter__ / __next__ / run / close; the async one implements __aiter__ / __anext__ / run / aclose. Both are iterator context managers: with closes the sync iterator; async with awaits async closure. A loop break alone does not close an iterator you still hold. run() (awaited on the async one) reads the stream to its end, running its triggers, then closes it. When the triggers include Trigger.function, listen returns a pyaviso.FunctionTriggerIterator (or pyaviso.AsyncFunctionTriggerIterator) with the same methods.

pyaviso.MultiNotificationIterator and pyaviso.AsyncMultiNotificationIterator: returned by listen_many, with the same methods as above, yielding (name, notification), plus errors: a list of pyaviso.ListenFailure, each with listener (the name), kind (a pyaviso.ListenFailureKind, LISTENER or TRIGGER) and error. A listener or function failure raised from the loop carries error.listener. When every listener has failed, the loop raises AvisoError with a failures list. Every AvisoError has both attributes; they are None when not set.

Triggers

pyaviso.Trigger with class-method constructors:

Trigger.echo(*, retries=0, required=True, label=None)
Trigger.log(path, *, retries=0, required=True)
Trigger.command(cmd, *, env=None, working_dir=None, retries=0, required=True, timeout=None, fail_fast=True) (Unix only)
Trigger.webhook(url, *, method=None, headers=None, body_template=None, retries=0, required=True, timeout=30.0, fail_fast=True)
Trigger.teams(url, *, retries=0, required=True, timeout=30.0, fail_fast=True)
Trigger.post(url, *, retries=0, required=True, timeout=30.0, fail_fast=True)
Trigger.function(func, *, retries=0, required=True, label=None): calls func(notification) in the reading thread or event loop; see Function

Chainable setters: .retries(n), .required(on), .timeout(seconds), .fail_fast(on), .label(name).

Setters return new values. Webhook method=None means POST. Timeout and fail-fast setters affect only command and HTTP triggers, and raise ValueError on a function trigger; label affects echo and names a function trigger in its errors. Echo and log output the smaller notification view, while post forwards the original CloudEvent. See Triggers.

pyaviso.HttpMethod is a str + Enum with members POST, GET, PUT, PATCH, DELETE.

pyaviso.TransportError
pyaviso.HttpError (attrs: status, body, request_id)
pyaviso.AuthError
pyaviso.DecodeError
pyaviso.MalformedEventError
pyaviso.HistoryGapError (attrs: reason, max_allowed, expected, observed)
pyaviso.StreamProtocolError (attrs: message, request_id)
pyaviso.ConfigError
pyaviso.StateStoreError
pyaviso.TriggerError (attrs: trigger_kind, error_kind, path, exit_code, stderr_tail, status, body_tail, reason, timeout_seconds, context, field, template_kind)

Version

pyaviso.__version__ is the Python distribution version. pyaviso.VERSION is the Rust crate version. They are pinned to the same value via maturin’s dynamic = ["version"].

aviso-client