autobahn.wamp¶

Submodules¶

Exceptions¶

`ApplicationError`	Base class for all exceptions that can/may be handled
`Error`	Base class for all exceptions related to WAMP.
`InvalidUri`	The URI for a topic, procedure or error is not a valid WAMP URI.
`ProtocolError`	Exception raised when WAMP protocol was violated. Protocol errors
`SerializationError`	Exception raised when the WAMP serializer could not serialize the
`SessionNotReady`	The application tried to perform a WAMP interaction, but the
`TransportLost`	Exception raised when the transport underlying the WAMP session

Classes¶

`CallDetails`	Provides details on a call when an endpoint previously
`CallOptions`	Used to provide options for calling with `autobahn.wamp.interfaces.ICaller.call()`.
`CallResult`	Wrapper for remote procedure call results that contain multiple positional
`CloseDetails`	Provides details for a WAMP session upon close.
`ComponentConfig`	WAMP application component configuration. An instance of this class is
`EventDetails`	Provides details on an event when calling an event handler
`ISession`	Interface for WAMP sessions.
`PublishOptions`	Used to provide options for subscribing in
`RegisterOptions`	Used to provide options for registering in
`SessionDetails`	Provides details for a WAMP session upon open.
`SubscribeOptions`	Used to provide options for subscribing in

Functions¶

`error`(uri)	Decorator for WAMP error classes.
`register`(uri[, options, check_types])	Decorator for WAMP procedure endpoints.
`subscribe`(uri[, options, check_types])	Decorator for WAMP event handlers.

Package Contents¶

exception ApplicationError(error, *args, **kwargs)[source]¶

Bases: Error

Base class for all exceptions that can/may be handled at the application level.

AUTHENTICATION_FAILED = 'wamp.error.authentication_failed'¶: Something failed with the authentication itself, that is, authentication could not run to end.

AUTHORIZATION_FAILED = 'wamp.error.authorization_failed'¶: A Dealer or Broker could not determine if the Peer is authorized to perform a join, call, register, publish or subscribe, since the authorization operation itself failed. E.g. a custom authorizer did run into an error.

CANCELED = 'wamp.error.canceled'¶: A Dealer or Callee canceled a call previously issued (WAMP AP).

CLOSE_REALM = 'wamp.error.close_realm'¶: The Peer want to leave the realm - used as a GOODBYE reason.

ENC_DECRYPT_ERROR = 'wamp.error.encryption.decrypt_error'¶: WAMP-cryptobox application payload end-to-end encryption error.

ENC_NO_PAYLOAD_CODEC = 'wamp.error.no_payload_codec'¶: WAMP message in payload transparency mode received, but no codec set or codec did not decode the payload.

ENC_TRUSTED_URI_MISMATCH = 'wamp.error.encryption.trusted_uri_mismatch'¶: WAMP-cryptobox application payload end-to-end encryption error.

GOODBYE_AND_OUT = 'wamp.error.goodbye_and_out'¶: A Peer acknowledges ending of a session - used as a GOOBYE reply reason.

INVALID_ARGUMENT = 'wamp.error.invalid_argument'¶: A call failed, since the given argument types or values are not acceptable to the called procedure - in which case the Callee may throw this error. Or a Router performing payload validation checked the payload (args / kwargs) of a call, call result, call error or publish, and the payload did not conform.

INVALID_PAYLOAD = 'wamp.error.invalid_payload'¶: The application payload could not be serialized.

INVALID_URI = 'wamp.error.invalid_uri'¶: Peer provided an incorrect URI for a URI-based attribute of a WAMP message such as a realm, topic or procedure.

NOT_AUTHORIZED = 'wamp.error.not_authorized'¶: A call, register, publish or subscribe failed, since the session is not authorized to perform the operation.

NO_AUTH_METHOD = 'wamp.error.no_auth_method'¶: No authentication method the peer offered is available or active.

NO_ELIGIBLE_CALLEE = 'wamp.error.no_eligible_callee'¶: A Dealer could not perform a call, since a procedure with the given URI is registered, but Callee Black- and Whitelisting and/or Caller Exclusion lead to the exclusion of (any) Callee providing the procedure (WAMP AP).

NO_SUCH_PRINCIPAL = 'wamp.error.no_such_principal'¶: A Peer was authenticated for an authid that does not or longer exists.

NO_SUCH_PROCEDURE = 'wamp.error.no_such_procedure'¶: A Dealer could not perform a call, since not procedure is currently registered under the given URI.

NO_SUCH_REALM = 'wamp.error.no_such_realm'¶: Peer wanted to join a non-existing realm (and the Router did not allow to auto-create the realm).

NO_SUCH_REGISTRATION = 'wamp.error.no_such_registration'¶: A Dealer could not perform a unregister, since the given registration is not active.

NO_SUCH_ROLE = 'wamp.error.no_such_role'¶: A Peer was to be authenticated under a Role that does not (or no longer) exists on the Router. For example, the Peer was successfully authenticated, but the Role configured does not exists - hence there is some misconfiguration in the Router.

NO_SUCH_SESSION = 'wamp.error.no_such_session'¶: A router could not perform an operation, since a session ID specified was non-existant.

NO_SUCH_SUBSCRIPTION = 'wamp.error.no_such_subscription'¶: A Broker could not perform a unsubscribe, since the given subscription is not active.

PAYLOAD_SIZE_EXCEEDED = 'wamp.error.payload_size_exceeded'¶: The application payload could not be transported becuase the serialized/framed payload exceeds the transport limits.

PROCEDURE_ALREADY_EXISTS = 'wamp.error.procedure_already_exists'¶: A procedure could not be registered, since a procedure with the given URI is already registered.

PROCEDURE_EXISTS_INVOCATION_POLICY_CONFLICT = 'wamp.error.procedure_exists_with_different_invocation_policy'¶: A procedure could not be registered, since a procedure with the given URI is already registered, and the registration has a conflicting invocation policy.

SYSTEM_SHUTDOWN = 'wamp.error.system_shutdown'¶: The Peer is shutting down completely - used as a GOODBYE (or ABORT) reason.

TIMEOUT = 'wamp.error.timeout'¶: A pending (in-flight) call was timed out.

TYPE_CHECK_ERROR = 'wamp.error.type_check_error'¶: WAMP procedure called with wrong argument types or subscription published with wrong argument types.

__str__()[source]¶: Return str(self).

__unicode__()[source]¶

callee¶

callee_authid¶

callee_authrole¶

enc_algo¶

error¶

error_message()[source]¶

Get the error message of this exception.

Returns:: The error message.
Return type:: str

forward_for¶

kwargs¶

class CallDetails(registration, progress=None, caller=None, caller_authid=None, caller_authrole=None, procedure=None, transaction_hash=None, enc_algo=None, forward_for=None)[source]¶

Bases: object

Provides details on a call when an endpoint previously registered is being called and opted to receive call details.

__slots__ = ('registration', 'progress', 'caller', 'caller_authid', 'caller_authrole', 'procedure',...¶

__str__()[source]¶

caller = None¶

caller_authid = None¶

caller_authrole = None¶

enc_algo = None¶

forward_for = None¶

procedure = None¶

progress = None¶

registration¶

transaction_hash = None¶

class CallOptions(on_progress=None, timeout=None, transaction_hash=None, caller=None, caller_authid=None, caller_authrole=None, forward_for=None, correlation_id=None, correlation_uri=None, correlation_is_anchor=None, correlation_is_last=None, details=None)[source]¶

Bases: object

Used to provide options for calling with autobahn.wamp.interfaces.ICaller.call().

__slots__ = ('on_progress', 'timeout', 'transaction_hash', 'caller', 'caller_authid', 'caller_authrole',...¶

__str__()[source]¶

caller = None¶

caller_authid = None¶

caller_authrole = None¶

correlation_id = None¶

correlation_is_anchor = None¶

correlation_is_last = None¶

correlation_uri = None¶

details = None¶

forward_for = None¶

message_attr()[source]¶: Returns options dict as sent within WAMP messages.

on_progress = None¶

timeout = None¶

transaction_hash = None¶

class CallResult(*results, **kwresults)[source]¶

Bases: object

Wrapper for remote procedure call results that contain multiple positional return values or keyword-based return values.

__slots__ = ('results', 'kwresults', 'enc_algo', 'callee', 'callee_authid', 'callee_authrole', 'forward_for')¶

__str__()[source]¶

callee¶

callee_authid¶

callee_authrole¶

enc_algo¶

forward_for¶

kwresults¶

results = ()¶

class CloseDetails(reason=None, message=None)[source]¶

Bases: object

Provides details for a WAMP session upon close.

REASON_DEFAULT = 'wamp.close.normal'¶

REASON_TRANSPORT_LOST = 'wamp.close.transport_lost'¶

__slots__ = ('reason', 'message')¶

__str__()[source]¶

marshal()[source]¶

message = None¶

reason = None¶

class ComponentConfig(realm=None, extra=None, keyring=None, controller=None, shared=None, runner=None)[source]¶

Bases: object

WAMP application component configuration. An instance of this class is provided to the constructor of autobahn.wamp.protocol.ApplicationSession.

__slots__ = ('realm', 'extra', 'keyring', 'controller', 'shared', 'runner')¶

__str__()[source]¶

controller = None¶

extra = None¶

keyring = None¶

realm = None¶

runner = None¶

shared = None¶

exception Error[source]¶

Bases: RuntimeError

Base class for all exceptions related to WAMP.

class EventDetails(subscription, publication, publisher=None, publisher_authid=None, publisher_authrole=None, topic=None, retained=None, transaction_hash=None, enc_algo=None, forward_for=None)[source]¶

Bases: object

Provides details on an event when calling an event handler previously registered.

__slots__ = ('subscription', 'publication', 'publisher', 'publisher_authid', 'publisher_authrole', 'topic',...¶

__str__()[source]¶

enc_algo = None¶

forward_for = None¶

publication¶

publisher = None¶

publisher_authid = None¶

publisher_authrole = None¶

retained = None¶

subscription¶

topic = None¶

transaction_hash = None¶

class ISession[source]¶

Bases: _ABC

Interface for WAMP sessions.

abstractmethod call(procedure: str, *args, **kwargs) → Any | autobahn.wamp.types.CallResult[source]¶

Call a remote procedure.

This will return a Deferred/Future, that when resolved, provides the actual result returned by the called remote procedure.

If the result is a single positional return value, it’ll be returned “as-is”.
If the result contains multiple positional return values or keyword return values, the result is wrapped in an instance of autobahn.wamp.types.CallResult.
If the call fails, the returned Deferred/Future will be rejected with an instance of autobahn.wamp.exception.ApplicationError.

If kwargs contains an options keyword argument that is an instance of autobahn.wamp.types.CallOptions, this will provide specific options for the call to perform.

When the Caller and Dealer implementations support canceling of calls, the call may be canceled by canceling the returned Deferred/Future.

Parameters:

procedure – The URI of the remote procedure to be called, e.g. "com.myapp.hello".
args – Any positional arguments for the call.
kwargs – Any keyword arguments for the call.

Returns:

A Deferred/Future for the call result.

property config: autobahn.wamp.types.ComponentConfig¶

Abstractmethod:

Configuration for session.

abstractmethod define(exception: Exception, error: str | None = None)[source]¶

Defines an exception for a WAMP error in the context of this WAMP session.

Parameters:

exception – The exception class to define an error mapping for.
error – The URI (or URI pattern) the exception class should be mapped for. Iff the exception class is decorated, this must be None.

abstractmethod disconnect()[source]¶: Close the underlying transport.

abstractmethod get_payload_codec() → IPayloadCodec | None[source]¶

Get the current payload codec (if any) for the session.

Payload codecs are used with WAMP payload transparency mode.

Returns:: The current payload codec or None if no codec is active.

abstractmethod is_attached() → bool[source]¶: Check if the session has currently joined a realm.

abstractmethod is_connected() → bool[source]¶: Check if the underlying transport is connected.

abstractmethod join(realm: str, authmethods: List[str] | None = None, authid: str | None = None, authrole: str | None = None, authextra: Dict[str, Any] | None = None, resumable: bool | None = None, resume_session: int | None = None, resume_token: str | None = None)[source]¶: Attach the session to the given realm. A session is open as soon as it is attached to a realm.

abstractmethod leave(reason: str | None = None, message: str | None = None)[source]¶

Actively close this WAMP session.

Parameters:

reason – An optional URI for the closing reason. If you want to permanently log out, this should be wamp.close.logout.
message – An optional (human-readable) closing message, intended for logging purposes.

Returns:

may return a Future/Deferred that fires when we’ve disconnected

abstractmethod onChallenge(challenge: autobahn.wamp.types.Challenge) → str[source]¶

Callback fired when the peer demands authentication.

May return a Deferred/Future.

Parameters:: challenge – The authentication challenge.

abstractmethod onConnect()[source]¶: Callback fired when the transport this session will run over has been established.

abstractmethod onDisconnect()[source]¶: Callback fired when underlying transport has been closed.

abstractmethod onJoin(details: autobahn.wamp.types.SessionDetails)[source]¶

Callback fired when WAMP session has been established.

May return a Deferred/Future.

Parameters:: details – Session information.

abstractmethod onLeave(details: autobahn.wamp.types.CloseDetails)[source]¶

Callback fired when WAMP session has is closed

Parameters:: details – Close information for session.

abstractmethod onUserError(fail, msg)[source]¶

This is called when we try to fire a callback, but get an exception from user code – for example, a registered publish callback or a registered method. By default, this prints the current stack-trace and then error-message to stdout.

ApplicationSession-derived objects may override this to provide logging if they prefer. The Twisted implemention does this. (See autobahn.twisted.wamp.ApplicationSession)

Parameters:

fail (instance implementing txaio.IFailedFuture) – The failure that occurred.
msg (str) – an informative message from the library. It is suggested you log this immediately after the exception.

abstractmethod onWelcome(welcome: autobahn.wamp.message.Welcome) → str | None[source]¶

Callback fired after the peer has successfully authenticated. If this returns anything other than None/False, the session is aborted and the return value is used as an error message.

May return a Deferred/Future.

Note

Before we let user code see the session – that is, before we fire “join” we give authentication instances a chance to abort the session. Usually this would be for “mutual authentication” scenarios. For example, WAMP-SCRAM uses this to confirm the server-signature.

Parameters:: welcome – The WELCOME message received from the server
Returns:: None, or an error message (using a fixed error URI wamp.error.cannot_authenticate).

abstractmethod publish(topic: str, *args, **kwargs) → autobahn.wamp.types.Publication | None[source]¶

Publish an event to a topic.

If kwargs contains an options keyword argument that is an instance of autobahn.wamp.types.PublishOptions, this will provide specific options for the publish to perform.

Note

By default, publications are non-acknowledged and the publication can fail silently, e.g. because the session is not authorized to publish to the topic.

When publication acknowledgement is requested via options.acknowledge == True, this function returns a Deferred/Future:

If the publication succeeds the Deferred/Future will resolve to an object that implements autobahn.wamp.interfaces.IPublication.
If the publication fails the Deferred/Future will reject with an instance of autobahn.wamp.exception.ApplicationError.

Parameters:

topic – The URI of the topic to publish to, e.g. "com.myapp.mytopic1".
args – Arbitrary application payload for the event (positional arguments).
kwargs – Arbitrary application payload for the event (keyword arguments).

Returns:

Acknowledgement for acknowledge publications - otherwise nothing.

When endpoint is a callable (function, method or object that implements __call__), then procedure must be provided and an instance of twisted.internet.defer.Deferred (when running on Twisted) or an instance of asyncio.Future (when running on asyncio) is returned.

If the registration succeeds the returned Deferred/Future will resolve to an object that implements autobahn.wamp.interfaces.IRegistration.
If the registration fails the returned Deferred/Future will reject with an instance of autobahn.wamp.exception.ApplicationError.

When endpoint is an object, then each of the object’s methods that is decorated with autobahn.wamp.register() is automatically registered and a (single) DeferredList or Future is returned that gathers all individual underlying Deferreds/Futures.

Parameters:

endpoint – The endpoint called under the procedure.
procedure – When endpoint is a callable, the URI (or URI pattern) of the procedure to register for. When endpoint is an object, the argument is ignored (and should be None).
options – Options for registering.
prefix – if not None, this specifies a prefix to prepend to all URIs registered for this class. So if there was an @wamp.register(‘method_foo’) on a method and prefix=’com.something.’ then a method ‘com.something.method_foo’ would ultimately be registered.
check_types – Enable automatic type checking against (Python 3.5+) type hints specified on the endpoint callable. Types are checked at run-time on each invocation of the endpoint callable. When a type mismatch occurs, the error is forwarded to the callee code in onUserError override method of autobahn.wamp.protocol.ApplicationSession. An error of type autobahn.wamp.exception.TypeCheckError is also raised and returned to the caller (via the router).

Returns:

A registration or a list of registrations (or errors)

property session_details: autobahn.wamp.types.SessionDetails | None¶

Abstractmethod:

Return details about the session, the same as initially provided to the ISession.onJoin() callback on an implementation.

abstractmethod set_payload_codec(payload_codec: IPayloadCodec | None)[source]¶

Set a payload codec on the session. To remove a previously set payload codec, set the codec to None.

Payload codecs are used with WAMP payload transparency mode.

Parameters:: payload_codec – The payload codec that should process application payload of the given encoding.

abstractmethod subscribe(handler: Callable | Any, topic: str | None = None, options: autobahn.wamp.types.SubscribeOptions | None = None, check_types: bool | None = None) → autobahn.wamp.types.Subscription | List[autobahn.wamp.types.Subscription][source]¶

Subscribe to a topic for receiving events.

When handler is a callable (function, method or object that implements __call__), then topic must be provided and an instance of twisted.internet.defer.Deferred (when running on Twisted) or an instance of asyncio.Future (when running on asyncio) is returned.

If the subscription succeeds the Deferred/Future will resolve to an object that implements autobahn.wamp.interfaces.ISubscription.
If the subscription fails the Deferred/Future will reject with an instance of autobahn.wamp.exception.ApplicationError.

When handler is an object, then each of the object’s methods that is decorated with autobahn.wamp.subscribe() is automatically subscribed as event handlers, and a list of Deferreds/Futures is returned that each resolves or rejects as above.

Parameters:

handler – The event handler to receive events.
topic – When handler is a callable, the URI (or URI pattern) of the topic to subscribe to. When handler is an object, this value is ignored (and should be None).
options – Options for subscribing.
check_types – Enable automatic type checking against (Python 3.5+) type hints specified on the endpoint callable. Types are checked at run-time on each invocation of the endpoint callable. When a type mismatch occurs, the error is forwarded to the subscriber code in onUserError override method of autobahn.wamp.protocol.ApplicationSession.

Returns:

A single Deferred/Future or a list of such objects

property transport: ITransport | None¶

Abstractmethod:

When the transport this session is attached to is currently open, this property can be read from. The property should be considered read-only. When the transport is gone, this property is set to None.

exception InvalidUri[source]¶

Bases: Exception

The URI for a topic, procedure or error is not a valid WAMP URI.

exception ProtocolError[source]¶

Bases: Error

Exception raised when WAMP protocol was violated. Protocol errors are fatal and are handled by the WAMP implementation. They are not supposed to be handled at the application level.

class PublishOptions(acknowledge=None, exclude_me=None, exclude=None, exclude_authid=None, exclude_authrole=None, eligible=None, eligible_authid=None, eligible_authrole=None, retain=None, forward_for=None, transaction_hash=None, correlation_id=None, correlation_uri=None, correlation_is_anchor=None, correlation_is_last=None)[source]¶

Bases: object

Used to provide options for subscribing in autobahn.wamp.interfaces.IPublisher.publish().

__slots__ = ('acknowledge', 'exclude_me', 'exclude', 'exclude_authid', 'exclude_authrole', 'eligible',...¶

__str__()[source]¶

acknowledge = None¶

correlation_id = None¶

correlation_is_anchor = None¶

correlation_is_last = None¶

correlation_uri = None¶

eligible = None¶

eligible_authid = None¶

eligible_authrole = None¶

exclude = None¶

exclude_authid = None¶

exclude_authrole = None¶

exclude_me = None¶

forward_for = None¶

message_attr()[source]¶: Returns options dict as sent within WAMP messages.

retain = None¶

transaction_hash = None¶

class RegisterOptions(match=None, invoke=None, concurrency=None, force_reregister=None, forward_for=None, details=None, details_arg=None, correlation_id=None, correlation_uri=None, correlation_is_anchor=None, correlation_is_last=None)[source]¶

Bases: object

Used to provide options for registering in autobahn.wamp.interfaces.ICallee.register().

__slots__ = ('match', 'invoke', 'concurrency', 'force_reregister', 'forward_for', 'details', 'details_arg',...¶

__str__()[source]¶

concurrency = None¶

correlation_id = None¶

correlation_is_anchor = None¶

correlation_is_last = None¶

correlation_uri = None¶

details = None¶

force_reregister = None¶

forward_for = None¶

invoke = None¶

match = None¶

message_attr()[source]¶: Returns options dict as sent within WAMP messages.

exception SerializationError[source]¶

Bases: Error

Exception raised when the WAMP serializer could not serialize the application payload (args or kwargs for CALL, PUBLISH, etc).

Bases: object

Provides details for a WAMP session upon open.