awsiot.eventstreamrpc

Classes for building a service that uses the event-stream RPC protocol.

exception awsiot.eventstreamrpc.ConnectionClosedError

Bases: RuntimeError

Connection is closed

exception awsiot.eventstreamrpc.StreamClosedError

Bases: RuntimeError

Stream is closed

exception awsiot.eventstreamrpc.EventStreamError

Bases: RuntimeError

For connection-level errors.

exception awsiot.eventstreamrpc.EventStreamOperationError

Bases: RuntimeError

Base for all errors that come across the wire.

These are not necessarily modeled shapes.

exception awsiot.eventstreamrpc.AccessDeniedError(*args)

Bases: EventStreamOperationError

Access Denied

exception awsiot.eventstreamrpc.UnmappedDataError

Bases: RuntimeError

Received data that does not map to a known model type.

exception awsiot.eventstreamrpc.SerializeError

Bases: RuntimeError

Error serializing data to send.

exception awsiot.eventstreamrpc.DeserializeError

Bases: RuntimeError

Error deserializing received data.

class awsiot.eventstreamrpc.LifecycleHandler

Bases: object

Base class for handling connection events.

Inherit from this class and override methods to handle connection events. All callbacks for this connection will be invoked on the same thread. If the connection attempt fails, no callbacks will be invoked. If the connection attempt succeeds, on_connect() will be the first callback invoked and on_disconnect() will always be the last.

Note that an open network connection MUST be closed via Connection.close() to avoid leaking resources.

on_connect()

Invoked when the connection has been fully established.

This will always be the first callback invoked on the handler. This will not be invoked if the connection attempt failed.

on_disconnect(reason)

Invoked when an open connection has disconnected.

This will always be the last callback invoked on the handler. This will not be invoked if the connection attempt failed.

Parameters:

reason (Exception | None) – Reason will be None if the user initiated the shutdown, otherwise the reason will be an Exception.

on_error(error)

Invoked when a connection-level error occurs.

Parameters:

  • reason – An Exception explaining the error

  • error (Exception) –

Returns:

True if the connection should be terminated as a result of the error, or False if the connection should continute.

Return type:

bool

on_ping(headers, payload)

Invoked when a ping is received.

Parameters:
class awsiot.eventstreamrpc.MessageAmendment(*, headers=None, payload=None)

Bases: object

Data to add to an event-stream message.

Parameters:

  • headers (Sequence[Header] | None) – Headers to add (optional)

  • payload (bytes | None) – Binary payload data (optional)

headers: Sequence[Header] | None

Headers to add

payload: bytes | None

Binary payload data

static create_static_authtoken_amender(authtoken)

Create function that amends payload: b’{“authToken”: “…”}’

Parameters:

authtoken (str) – value of “authToken” in the payload. The same value is always used, even if the amender is called multiple times over the life of the application.

Returns:

The result is appropriate for passing to the Connection’s connect_message_amender init arg.

Return type:

Callable[[], MessageAmendment]

class awsiot.eventstreamrpc.Connection(*, host_name, port, bootstrap, socket_options=None, tls_connection_options=None, connect_message_amender=None)

Bases: object

A client connection to event-stream RPC service.

connect() must be called to open the network connection before interacting with the service.

Note that close() MUST be called to end an open network connection. Failure to do so will result in leaked resources.

Reconnect is possible by calling connect() again after the connection has finished closing/disconnecting.

Parameters:

  • host_name (str) – Remote host name.

  • port (int) – Remote port.

  • bootstrap (ClientBootstrap) – ClientBootstrap to use when initiating socket connection.

  • socket_options (SocketOptions | None) – Optional socket options. If None is provided, the default options are used.

  • tls_connection_options (TlsConnectionOptions | None) – Optional TLS connection options. If None is provided, then the connection will be attempted over plain-text.

  • connect_message_amender (Callable[[], MessageAmendment] | None) – Optional callable that should return a MessageAmendment for the CONNECT message. This callable will be invoked whenever a network connection is being established.

connect(lifecycle_handler)

Asynchronously open a network connection.

Note that close() MUST be called to end a network connection that is open (or in the process of connecting). Failure to do so will result in leaked resources.

Parameters:

lifecycle_handler (LifecycleHandler) – Handler for events over the course of this network connection. See LifecycleHandler for more info. Handler methods will only be invoked if the connect attempt succeeds.

Returns:

A Future which completes when the connection succeeds or fails. If successful, the Future will contain None. Otherwise it will contain an exception explaining the reason for failure.

Return type:

Future

close(reason=None)

Close the connection.

Shutdown is asynchronous. This call has no effect if the connection is already closed or closing.

Parameters:

reason (Exception | None) – If set, the connection will close with this error as the reason (unless it was already closing for another reason).

Returns:

The future which will complete when the shutdown process is done. The future will have an exception if shutdown was caused by an error, or a result of None if the shutdown was clean and user-initiated.

Return type:

Future

class awsiot.eventstreamrpc.Shape

Bases: object

Base class for shapes serialized by a service

exception awsiot.eventstreamrpc.ErrorShape

Bases: Shape, EventStreamOperationError

Base class for all error shapes serialized by a service

class awsiot.eventstreamrpc.ShapeIndex(shape_types)

Bases: object

Catalog of all shapes serialized by this service

Parameters:

shape_types (Sequence[type]) –

find_shape_type(model_name)

Returns Shape type with given model_name, or None

Parameters:

model_name (str) –

Return type:

type

class awsiot.eventstreamrpc.StreamResponseHandler

Bases: object

Base class for all operation stream handlers.

For operations with a streaming response (0+ messages that may arrive after the initial response).

class awsiot.eventstreamrpc.Operation

Bases: object

Base class for an operation.

class awsiot.eventstreamrpc.ClientOperation(stream_handler, shape_index, connection)

Bases: Operation

Base class for a client operation.

Nearly all functions are private/protected. Child classes should rewrite public API to properly document the types they deal with.

Parameters:
class awsiot.eventstreamrpc.Client(connection, shape_index)

Bases: object

Base class for a service client.

Child class should add public API functions for each operation.

Parameters:
close(reason=None)

Close the connection.

Shutdown is asynchronous. This call has no effect if the connection is already closed or closing.

Parameters:

reason (Exception | None) – If set, the connection will close with this error as the reason (unless it was already closing for another reason).

Returns:

The future which will complete when the shutdown process is done. The future will have an exception if shutdown was caused by an error, or a result of None if the shutdown was clean and user-initiated.

Return type:

Future