aiocoap.interfaces module

This module provides interface base classes to various aiocoap services, especially with respect to request and response handling.

class aiocoap.interfaces.MessageInterface

Bases: object

A MessageInterface is an object that can exchange addressed messages over unreliable transports. Implementations send and receive messages with message type and message ID, and are driven by a Context that deals with retransmission.

Usually, an MessageInterface refers to something like a local socket, and send messages to different remote endpoints depending on the message’s addresses. Just as well, a MessageInterface can be useful for one single address only, or use various local addresses depending on the remote address.


Send a given Message object


Return a value suitable for the message’s remote property based on its .opt.uri_host or .unresolved_remote.

May return None, which indicates that the MessageInterface can not transport the message (typically because it is of the wrong scheme).


Deactivate the complete transport, usually irrevertably. When the coroutine returns, the object must have made sure that it can be destructed by means of ref-counting or a garbage collector run.

class aiocoap.interfaces.EndpointAddress

Bases: object

An address that is suitable for routing through the application to a remote endpoint.

Depending on the MessageInterface implementation used, an EndpointAddress property of a message can mean the message is exchanged “with [2001:db8::2:1]:5683, while my local address was [2001:db8:1::1]:5683” (typical of UDP6), “over the connected <Socket at 0x1234>, whereever that’s connected to” (simple6 or TCP) or “with participant 0x01 of the OSCAP key 0x…, routed over <another EndpointAddress>”.

EndpointAddresses are only concstructed by MessageInterface objects, either for incoming messages or when populating a message’s .remote in MessageInterface.determine_remote().

There is no requirement that those address are always identical for a given address. However, incoming addresses must be hashable and hash-compare identically to requests from the same context. The “same context”, for the purpose of EndpointAddresses, means that the message must be eligible for request/response, blockwise (de)composition and observations. (For example, in a DTLS context, the hash must change between epochs due to RFC7252 Section 9.1.2).

So far, it is required that hash-identical objects also compare the same. That requirement might go away in future to allow equality to reflect finer details that are not hashed. (The only property that is currently known not to be hashed is the local address in UDP6, because that is unknown in initially sent packages, and thus disregarded for comparison but needed to round-trip through responses.)


The authority component of URIs that this endpoint represents


The base URI for this endpoint (typically scheme plus .hostinfo)


True if the remote address is a multicast address, otherwise false.


True if the local address is a multicast address, otherwise false.

maximum_block_size_exp = 6

The maximum negotiated block size that can be sent to this remote.

maximum_payload_size = 1024

The maximum payload size that can be sent to this remote. Only relevant if maximum_block_size_exp is 7. This will be removed in favor of a maximum message size when the block handlers can get serialization length predictions from the remote. Must be divisible by 1024.

class aiocoap.interfaces.MessageManager

Bases: object

The interface an entity that drives a MessageInterface provides towards the MessageInterface for callbacks and object acquisition.


Callback to be invoked with an incoming message

dispatch_error(errno, remote)

Callback to be invoked when the operating system indicated an error condition from a particular remote.

This interface is likely to change soon to something that is not limited to errno-style errors, and might allow transporting additional data.


A CredentialsMap that transports should consult when trying to establish a security context

class aiocoap.interfaces.TokenInterface

Bases: object

send_message(message) → Union[Callable[[], NoneType], NoneType]

Send a message. If it returns a a callable, the caller is asked to call in case it no longer needs the message sent, and to dispose of if it doesn’t intend to any more.


Return True if the message is recognized to already have a .remote managedy by this TokenInterface, or return True and set a .remote on message if it should (by its unresolved remote or Uri-* options) be routed through this TokenInterface, or return False otherwise.

class aiocoap.interfaces.TokenManager

Bases: object

class aiocoap.interfaces.RequestInterface

Bases: object

request(request: PlumbingRequest)
class aiocoap.interfaces.RequestProvider

Bases: object


Create and act on a a Request object that will be handled according to the provider’s implementation.

class aiocoap.interfaces.Request

Bases: object

A CoAP request, initiated by sending a message. Typically, this is not instanciated directly, but generated by a RequestProvider.request() method.

response = 'A future that is present from the creation of the object and fullfilled with the response message.'
class aiocoap.interfaces.Resource

Bases: object

Interface that is expected by a protocol.Context to be present on the serversite, which renders all requests to that context.


Indicator to the protocol.Responder about whether it should assemble request blocks to a single request and extract the requested blocks from a complete-resource answer (True), or whether the resource will do that by itself (False).


Return a message that can be sent back to the requester.

This does not need to set any low-level message options like remote, token or message type; it does however need to set a response code.

The aiocoap.message.NoResponse sentinel can be returned if the resources wishes to suppress an answer on the request/response layer. (An empty ACK is sent responding to a CON request on message layer nevertheless.)

class aiocoap.interfaces.ObservableResource

Bases: aiocoap.interfaces.Resource

Interface the protocol.ServerObservation uses to negotiate whether an observation can be established based on a request.

This adds only functionality for registering and unregistering observations; the notification contents will be retrieved from the resource using the regular render() method from crafted (fake) requests.

add_observation(request, serverobservation)

Before the incoming request is sent to render(), the add_observation() method is called. If the resource chooses to accept the observation, it has to call the serverobservation.accept(cb) with a callback that will be called when the observation ends. After accepting, the ObservableResource should call serverobservation.trigger() whenever it changes its state; the ServerObservation will then initiate notifications by having the request rendered again.