ECNClient

Part of Client & lifecycle in the Python API reference.

Related guidance: concepts/lifecycle, getting-started/preflight, how-to/cleanup.

Runnable examples: preflight.py.

from picogrid_ecn_client import ECNClient

Manage one explicitly configured MQTT v5 ECN connection.

class ECNClient: ...

Source · client.py

Use ECNClient with async with to manage its asynchronous lifecycle.

__init__

Create a client without connecting or installing subscriptions.

def __init__(config: ECNConfig) -> None

Parameters

Name	Type	Default	Description
config	ECNConfig	—	Frozen connection and operation configuration.

Source · client.py

config

Return the frozen configuration supplied at construction.

config: ECNConfig

Source · client.py

entities

Return the stable typed entity interface.

entities: Entities

Source · client.py

locations

Return the stable typed location interface.

locations: Locations

Source · client.py

tasks

Return the stable typed task interface.

tasks: Tasks

Source · client.py

clock

Return the ECN-relative clock diagnostic interface.

clock: Clock

Source · client.py

is_ready

Return whether MQTT and every still-required subscription are ready.

is_ready: bool

Source · client.py

status

Return a secret-safe snapshot of the current connection state.

status: ConnectionStatus

Source · client.py

wait_until_ready

Wait for strict readiness within one caller-supplied deadline.

async def wait_until_ready(*, timeout: float) -> ConnectionStatus

Parameters

Name	Type	Default	Description
timeout	float	—	Positive finite maximum wait in seconds.

Returns

Type	Description
ConnectionStatus	The first strictly ready connection snapshot.

Raises

Exception	Description
AuthenticationError	If credentials are unavailable or rejected.
AuthorizationError	If connection or required-subscription access is denied.
ConfigurationError	If unchanged local configuration is invalid.
ConnectionError	If recovery becomes terminal for another connection reason.
NotReadyError	If the client has not started or is closing/closed.
ProtocolError	If recovery terminates on a protocol violation.
ResourceLimitError	If the broker rejects a required resource.
TimeoutError	If the caller’s deadline expires first.
ValidationError	If timeout is not positive and finite.

Source · client.py

connection_events

Return a capacity-one latest-value stream of redacted connection status.

def connection_events() -> EventStream[ConnectionStatus]

Raises

Exception	Description
NotReadyError	If client closing has begun or the client is closed.

Source · client.py

notify_credentials_changed

Wake credential-blocked recovery after an atomic credential repair.

def notify_credentials_changed() -> None

Source · client.py

request_retry

Wake scheduled transient recovery or revive transient retry exhaustion.

def request_retry() -> None

Source · client.py

start

Connect to MQTT v5 and wait for readiness.

async def start() -> None

Raises

Exception	Description
AuthenticationError	If authentication material or broker authentication is rejected.
AuthorizationError	If the broker rejects connection authorization.
ConfigurationError	If local MQTT or TLS verification configuration is invalid.
ConnectionError	If MQTT readiness fails or times out.
NotReadyError	If the client is closing or already closed.
ProtocolError	If MQTT readiness terminates on a protocol violation.
ResourceLimitError	If the broker rejects a required connection resource.

Source · client.py

preflight

Run read-only checks and caller-requested subscription probes.

async def preflight(
    *,
    subscription_probes: Collection[SubscriptionProbe] = (),
) -> PreflightReport

Parameters

Name	Type	Default	Description
subscription_probes	Collection[SubscriptionProbe]	()	Exact bounded subscription probes to request.

Returns

Type	Description
PreflightReport	A secret-safe report of the completed checks.

Raises

Exception	Description
TimeoutError	If closing the probe transport exceeds the configured shutdown timeout. Check failures are reported in the returned report rather than raised.

Source · client.py

close

Close the client and remove owned resources.

async def close() -> None

Raises

Exception	Description
ConnectionError	If a component fails during cleanup.
TimeoutError	If cleanup exceeds the shutdown timeout in seconds.

Source · client.py

__aenter__

Start the client and return it after readiness.

async def __aenter__() -> ECNClient

Returns

Type	Description
ECNClient	This client, ready for entity, location, and task work.

Raises

Exception	Description
AuthenticationError	If authentication material or broker authentication is rejected.
AuthorizationError	If the broker rejects connection authorization.
ConfigurationError	If local MQTT or TLS verification configuration is invalid.
ConnectionError	If MQTT readiness fails or times out.
NotReadyError	If the client is closing or already closed.
ProtocolError	If MQTT readiness terminates on a protocol violation.
ResourceLimitError	If the broker rejects a required connection resource.

Source · client.py

__aexit__

Close the client when leaving the asynchronous context.

async def __aexit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None

Parameters

Name	Type	Default	Description
exc_type	type[BaseException] | None	—	Type of the propagated exception, or None.
exc_value	BaseException | None	—	Propagated exception instance, or None.
traceback	TracebackType | None	—	Traceback for the propagated exception, or None.

Raises

Exception	Description
ConnectionError	If a component fails during cleanup.
TimeoutError	If cleanup exceeds the shutdown timeout in seconds.

Source · client.py