Welcome to Asynction’s documentation!

Asynction SocketIO Server

The AsynctionSocketIO server is essentially a flask_socketio.SocketIO server with an additional factory classmethod.

class asynction.AsynctionSocketIO(spec: asynction.types.AsyncApiSpec, validation: bool, docs: bool, server_security: Sequence[Mapping[str, Sequence[str]]], default_error_handler: Optional[Callable[[Exception], None]], app: Optional[flask.app.Flask], **kwargs)

Inherits the flask_socketio.SocketIO class.

classmethod from_spec(spec_path: Union[pathlib.Path, Mapping[str, Any]], validation: bool = True, server_name: Optional[str] = None, docs: bool = True, default_error_handler: Optional[Callable[[Exception], None]] = None, app: Optional[flask.app.Flask] = None, **kwargs) → flask_socketio.SocketIO

Create a Flask-SocketIO server from an AsyncAPI spec. This is the single entrypoint to the Asynction server API.

Parameters

  • spec_path – The path where the AsyncAPI YAML specification is located, or a dictionary object of the AsyncAPI data structure

  • validation – When set to False, message payloads, channel bindings and ack callbacks are NOT validated. Defaults to True.

  • server_name – The server to pick from the AsyncAPI servers object. The server object is then used to configure the path kwarg of the SocketIO server.

  • docs – When set to True, HTML rendered documentation is generated and served through the GET {base_path}/docs route of the app. The GET {base_path}/docs/asyncapi.json route is also exposed, returning the raw specification data for programmatic retrieval. Defaults to True.

  • default_error_handler – The error handler that handles any namespace without an explicit error handler. Equivelant of @socketio.on_error_default

  • app – The flask application instance. Defaults to None.

  • kwargs – Flask-SocketIO, Socket.IO and Engine.IO server options.

Returns

A Flask-SocketIO server. The server has all the event and error handlers registered.

Example:

asio = AsynctionSocketIO.from_spec(
    spec_path="./docs/asyncapi.yaml",
    app=flask_app,
    message_queue="redis://localhost:6379",
    # any other kwarg that the flask_socketio.SocketIO constructor accepts
)

Mock Asynction Server

The MockAsynctionSocketIO server is essentially an AsynctionSocketIO server that:

  • Periodically emits events containing payloads of fake data, through tasks running on the background.

  • Listens for all events defined in the given AsyncAPI specification, returning fake acknowledgements where applicable.

class asynction.MockAsynctionSocketIO(*args, custom_formats_sample_size: int, **kwargs)

Inherits the AsynctionSocketIO class.

run(app: flask.app.Flask, host: Optional[str] = None, port: Optional[int] = None, subscription_task_interval: float = 1.0, max_worker_number: int = 8, **kwargs) → None

Run the mock Asynction SocketIO web server.

In addition to the args and kwargs of flask_socketio.SocketIO.run(), this method accepts some extra keyword arguments:

  • subscription_task_interval

  • max_worker_number

Parameters

  • app – The flask application instance.

  • host – The hostname or IP address for the server to listen on. Defaults to 127.0.0.1.

  • port – The port number for the server to listen on. Defaults to 5000.

  • subscription_task_interval – How often (in seconds) a subscription task (thread that emits an event to a connected client) is scheduled. Defaults to 1.0.

  • max_worker_number – The maximum number of workers to be started for the purposes of executing background subscription tasks. Defaults to 8.

  • kwargs – Additional web server options that are propagated to flask_socketio.SocketIO.run(). The web server options are specific to the server used in each of the supported async modes. Refer to the Flask-SocketIO docs for details.

classmethod from_spec(spec_path: Union[pathlib.Path, Mapping[str, Any]], validation: bool = True, server_name: Optional[str] = None, docs: bool = True, default_error_handler: Optional[Callable[[Exception], None]] = None, app: Optional[flask.app.Flask] = None, custom_formats_sample_size: int = 20, **kwargs) → asynction.mock_server.MockAsynctionSocketIO

Create a Flask-SocketIO mock server given an AsyncAPI spec. The server emits events containing payloads of fake data in regular intervals, through background subscription tasks. It also listens for events as per the spec definitions and returns mock aknowledgements where applicable. All event and acknowledgment payloads adhere to the schemata defined within the AsyncAPI spec.

In addition to the args and kwargs of AsynctionSocketIO.from_spec(), this factory method accepts some extra keyword arguments:

  • custom_formats_sample_size

Parameters

  • spec_path – The path where the AsyncAPI YAML specification is located, or a dictionary object of the AsyncAPI data structure

  • validation – When set to False, message payloads, channel bindings and ack callbacks are NOT validated. Defaults to True.

  • server_name – The server to pick from the AsyncAPI servers object. The server object is then used to configure the path kwarg of the SocketIO server.

  • docs – When set to True, HTML rendered documentation is generated and served through the GET {base_path}/docs route of the app. The GET {base_path}/docs/asyncapi.json route is also exposed, returning the raw specification data for programmatic retrieval. Defaults to True.

  • default_error_handler – The error handler that handles any namespace without an explicit error handler. Equivelant of @socketio.on_error_default

  • app – The flask application instance. Defaults to None.

  • custom_formats_sample_size – The ammout of the Faker provider samples to be used for each custom string format. Hypotheses uses these samples to generate fake data. Set to 0 if custom formats are not needed. Defaults to 20.

  • kwargs – Flask-SocketIO, Socket.IO and Engine.IO server options.

Returns

A Flask-SocketIO mock server, emitting events of fake data in regular intervals. The server also has mock event and error handlers registered.

Example:

mock_asio = MockAsynctionSocketIO.from_spec(
    spec_path="./docs/asyncapi.yaml",
    app=flask_app,
    # any other kwarg that the flask_socketio.SocketIO constructor accepts
)

Types

class asynction.SecurityInfo(_typename, _fields=None, /, **kwargs)

Security handler function response type.

One of scopes, scope and one of sub, uid must be present

Subclass this type to add extra fields to a security handler response

scope: str
scopes: Sequence[str]
sub: Any
uid: Any

Exceptions

Asynction’s exceptions to be caught via Flask-SocketIO error handlers.

exception asynction.AsynctionException

The base class for all asynction runtime exceptions.

exception asynction.ValidationException(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)

The base class for all asynction validation exceptions.

exception asynction.PayloadValidationException(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)

Raised when the payload of an incoming or outgoing message fails the schema validation.

exception asynction.BindingsValidationException(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)

Raised when the HTTP bindings of an incoming connection fail the schema validation.

exception asynction.MessageAckValidationException(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)

Raised when the input arguments passed to the ack callback do not adhere to the x-ack args schema.

exception asynction.SecurityException

Raised when an incoming connection fails to meet the requirements of any of the specified security schemes.

Indices and tables