wsrpc-aiohttp API

Signatures from version 4.0.4 (source revision b72e09602caff290ec0dfe96ac7888ffcf212a81).

This reference is checked in so builds do not require installing the library or accessing its source repository.

WSRPCBase

class wsrpc_aiohttp.WSRPCBase(loop: asyncio.AbstractEventLoop | None = None, timeout: TimeoutType | None = None, loads: LoadsType = json.loads, dumps: DumpsType = json.dumps)

Common WSRPC abstraction

async close(message=None)

Cancel all pending tasks

async handle_binary(message: aiohttp.WSMessage)
async handle_message(message: aiohttp.WSMessage)
classmethod get_routes()
classmethod get_clients()
property routes

Property which contains the socket routes

property clients

Property which contains the socket clients

prepare_args(args)
static is_route(func)
async handle_method(method, serial, args, kwargs)
async handle_result(serial, result)
async handle_error(serial, error)
async handle_event(event)
resolver(func_name)
async call(func: str, timeout=None, **kwargs)

Method for call remote function

Remote methods allows only kwargs as arguments.

You might use functions as route or classes

async def remote_function(socket: WSRPCBase, *, foo, bar):
    # call function from the client-side
    await socket.proxy.ping()
    return foo + bar

class RemoteClass(WebSocketRoute):

    # this method executes when remote side call route name
    async def init(self):
        # call function from the client-side
        await self.socket.proxy.ping()

    async def make_something(self, foo, bar):
        return foo + bar
async emit(event)
classmethod add_route(route: str, handler: RouteType)

Expose local function through RPC

Parameters:

  • route – Name which function will be aliased for this function. Remote side should call function by this name.

  • handler – Function or Route class (classes based on wsrpc_aiohttp.WebSocketRoute). For route classes the public methods will be registered automatically.

Note

Route classes might be initialized only once for the each socket instance.

A route instance is created lazily for each connection. Calling the bare route name resolves its exposed init method; init is not called automatically before other methods.

add_event_listener(func: EventListenerType)
remove_event_listeners(func)
classmethod remove_route(route: str, fail=True)

Removes route by name. If fail=True an exception will be raised in case the route was not found.

property proxy

Special property which allow run the remote functions by dot notation

# calls remote function with name ping
await client.proxy.ping()

# full equivalent of
await client.call('ping')

WSRPCClient

class wsrpc_aiohttp.WSRPCClient(endpoint: URL | str, loop=None, timeout=None, session: aiohttp.ClientSession | None = None, loads=json.loads, dumps=json.dumps, **kwargs)

WSRPC Client class

async close(message: aiohttp.WSMessage | None = None)

Close the client connect connection

async handle_binary(message: aiohttp.WSMessage)
async handle_message(message: aiohttp.WSMessage)
classmethod get_routes()
classmethod get_clients()
property routes

Property which contains the socket routes

property clients

Property which contains the socket clients

prepare_args(args)
static is_route(func)
async handle_method(method, serial, args, kwargs)
async handle_result(serial, result)
async handle_error(serial, error)
async handle_event(event)
resolver(func_name)
async call(func: str, timeout=None, **kwargs)

Method for call remote function

Remote methods allows only kwargs as arguments.

You might use functions as route or classes

async def remote_function(socket: WSRPCBase, *, foo, bar):
    # call function from the client-side
    await socket.proxy.ping()
    return foo + bar

class RemoteClass(WebSocketRoute):

    # this method executes when remote side call route name
    async def init(self):
        # call function from the client-side
        await self.socket.proxy.ping()

    async def make_something(self, foo, bar):
        return foo + bar
async emit(event)
classmethod add_route(route: str, handler: RouteType)

Expose local function through RPC

Parameters:

  • route – Name which function will be aliased for this function. Remote side should call function by this name.

  • handler – Function or Route class (classes based on wsrpc_aiohttp.WebSocketRoute). For route classes the public methods will be registered automatically.

Note

Route classes might be initialized only once for the each socket instance.

A route instance is created lazily for each connection. Calling the bare route name resolves its exposed init method; init is not called automatically before other methods.

add_event_listener(func: EventListenerType)
remove_event_listeners(func)
classmethod remove_route(route: str, fail=True)

Removes route by name. If fail=True an exception will be raised in case the route was not found.

property proxy

Special property which allow run the remote functions by dot notation

# calls remote function with name ping
await client.proxy.ping()

# full equivalent of
await client.call('ping')
async connect()

Perform connection to the server

WebSocketBase

class wsrpc_aiohttp.WebSocketBase(request)

Base class for aiohttp websocket handler

async close(message=None)

Cancel all pending tasks and stop this socket connection

async handle_binary(message: aiohttp.WSMessage)
async handle_message(message: aiohttp.WSMessage)
classmethod get_routes()
classmethod get_clients()
property routes

Property which contains the socket routes

property clients

Property which contains the socket clients

prepare_args(args)
static is_route(func)
async handle_method(method, serial, args, kwargs)
async handle_result(serial, result)
async handle_error(serial, error)
async handle_event(event)
resolver(func_name)
async call(func: str, timeout=None, **kwargs)

Method for call remote function

Remote methods allows only kwargs as arguments.

You might use functions as route or classes

async def remote_function(socket: WSRPCBase, *, foo, bar):
    # call function from the client-side
    await socket.proxy.ping()
    return foo + bar

class RemoteClass(WebSocketRoute):

    # this method executes when remote side call route name
    async def init(self):
        # call function from the client-side
        await self.socket.proxy.ping()

    async def make_something(self, foo, bar):
        return foo + bar
async emit(event)
classmethod add_route(route: str, handler: RouteType)

Expose local function through RPC

Parameters:

  • route – Name which function will be aliased for this function. Remote side should call function by this name.

  • handler – Function or Route class (classes based on wsrpc_aiohttp.WebSocketRoute). For route classes the public methods will be registered automatically.

Note

Route classes might be initialized only once for the each socket instance.

A route instance is created lazily for each connection. Calling the bare route name resolves its exposed init method; init is not called automatically before other methods.

add_event_listener(func: EventListenerType)
remove_event_listeners(func)
classmethod remove_route(route: str, fail=True)

Removes route by name. If fail=True an exception will be raised in case the route was not found.

property proxy

Special property which allow run the remote functions by dot notation

# calls remote function with name ping
await client.proxy.ping()

# full equivalent of
await client.call('ping')
classmethod configure(keepalive_timeout=KEEPALIVE_PING_TIMEOUT, client_timeout=CLIENT_TIMEOUT, max_concurrent_requests=MAX_CONCURRENT_REQUESTS, loads=json.loads, dumps=json.dumps)

Configures the handler class

Parameters:

  • dumps – json serializer

  • loads – json deserializer

  • keepalive_timeout – sets timeout of client pong response

  • client_timeout – internal lock timeout

  • max_concurrent_requests – how many concurrent requests might be performed by each client

classmethod freeze()

Freeze all signals

async authorize()

Special method for authorize client. If this method return True then access allowed, otherwise 403 Forbidden will be sent.

This method will be called before socket connection establishment.

By default everyone has access. You have to inherit this class and change this behaviour.

Note

You can validate some headers (self.request.headers) or check cookies (self.reauest.cookies).

classmethod broadcast(func, callback=None, return_exceptions=True, **kwargs)

Call remote function on all connected clients

Parameters:

  • func – Remote route name

  • callback – Function which receive responses

  • return_exceptions – Return exceptions of client calls instead of raise a first one

WebSocketAsync

class wsrpc_aiohttp.WebSocketAsync(request)

Handler class which execute any route as a coroutine

async close(message=None)

Cancel all pending tasks and stop this socket connection

async handle_binary(message: aiohttp.WSMessage)
async handle_message(message: aiohttp.WSMessage)
classmethod get_routes()
classmethod get_clients()
property routes

Property which contains the socket routes

property clients

Property which contains the socket clients

prepare_args(args)
static is_route(func)
async handle_method(method, serial, args, kwargs)
async handle_result(serial, result)
async handle_error(serial, error)
async handle_event(event)
resolver(func_name)
async call(func: str, timeout=None, **kwargs)

Method for call remote function

Remote methods allows only kwargs as arguments.

You might use functions as route or classes

async def remote_function(socket: WSRPCBase, *, foo, bar):
    # call function from the client-side
    await socket.proxy.ping()
    return foo + bar

class RemoteClass(WebSocketRoute):

    # this method executes when remote side call route name
    async def init(self):
        # call function from the client-side
        await self.socket.proxy.ping()

    async def make_something(self, foo, bar):
        return foo + bar
async emit(event)
classmethod add_route(route: str, handler: RouteType)

Expose local function through RPC

Parameters:

  • route – Name which function will be aliased for this function. Remote side should call function by this name.

  • handler – Function or Route class (classes based on wsrpc_aiohttp.WebSocketRoute). For route classes the public methods will be registered automatically.

Note

Route classes might be initialized only once for the each socket instance.

A route instance is created lazily for each connection. Calling the bare route name resolves its exposed init method; init is not called automatically before other methods.

add_event_listener(func: EventListenerType)
remove_event_listeners(func)
classmethod remove_route(route: str, fail=True)

Removes route by name. If fail=True an exception will be raised in case the route was not found.

property proxy

Special property which allow run the remote functions by dot notation

# calls remote function with name ping
await client.proxy.ping()

# full equivalent of
await client.call('ping')
classmethod configure(keepalive_timeout=KEEPALIVE_PING_TIMEOUT, client_timeout=CLIENT_TIMEOUT, max_concurrent_requests=MAX_CONCURRENT_REQUESTS, loads=json.loads, dumps=json.dumps)

Configures the handler class

Parameters:

  • dumps – json serializer

  • loads – json deserializer

  • keepalive_timeout – sets timeout of client pong response

  • client_timeout – internal lock timeout

  • max_concurrent_requests – how many concurrent requests might be performed by each client

classmethod freeze()

Freeze all signals

async authorize()

Special method for authorize client. If this method return True then access allowed, otherwise 403 Forbidden will be sent.

This method will be called before socket connection establishment.

By default everyone has access. You have to inherit this class and change this behaviour.

Note

You can validate some headers (self.request.headers) or check cookies (self.reauest.cookies).

classmethod broadcast(func, callback=None, return_exceptions=True, **kwargs)

Call remote function on all connected clients

Parameters:

  • func – Remote route name

  • callback – Function which receive responses

  • return_exceptions – Return exceptions of client calls instead of raise a first one

WebSocketThreaded

class wsrpc_aiohttp.WebSocketThreaded(request)

Handler class which execute any route in the default thread-pool of current event loop

async close(message=None)

Cancel all pending tasks and stop this socket connection

async handle_binary(message: aiohttp.WSMessage)
async handle_message(message: aiohttp.WSMessage)
classmethod get_routes()
classmethod get_clients()
property routes

Property which contains the socket routes

property clients

Property which contains the socket clients

prepare_args(args)
static is_route(func)
async handle_method(method, serial, args, kwargs)
async handle_result(serial, result)
async handle_error(serial, error)
async handle_event(event)
resolver(func_name)
async call(func: str, timeout=None, **kwargs)

Method for call remote function

Remote methods allows only kwargs as arguments.

You might use functions as route or classes

async def remote_function(socket: WSRPCBase, *, foo, bar):
    # call function from the client-side
    await socket.proxy.ping()
    return foo + bar

class RemoteClass(WebSocketRoute):

    # this method executes when remote side call route name
    async def init(self):
        # call function from the client-side
        await self.socket.proxy.ping()

    async def make_something(self, foo, bar):
        return foo + bar
async emit(event)
classmethod add_route(route: str, handler: RouteType)

Expose local function through RPC

Parameters:

  • route – Name which function will be aliased for this function. Remote side should call function by this name.

  • handler – Function or Route class (classes based on wsrpc_aiohttp.WebSocketRoute). For route classes the public methods will be registered automatically.

Note

Route classes might be initialized only once for the each socket instance.

A route instance is created lazily for each connection. Calling the bare route name resolves its exposed init method; init is not called automatically before other methods.

add_event_listener(func: EventListenerType)
remove_event_listeners(func)
classmethod remove_route(route: str, fail=True)

Removes route by name. If fail=True an exception will be raised in case the route was not found.

property proxy

Special property which allow run the remote functions by dot notation

# calls remote function with name ping
await client.proxy.ping()

# full equivalent of
await client.call('ping')
classmethod configure(keepalive_timeout=KEEPALIVE_PING_TIMEOUT, client_timeout=CLIENT_TIMEOUT, max_concurrent_requests=MAX_CONCURRENT_REQUESTS, loads=json.loads, dumps=json.dumps)

Configures the handler class

Parameters:

  • dumps – json serializer

  • loads – json deserializer

  • keepalive_timeout – sets timeout of client pong response

  • client_timeout – internal lock timeout

  • max_concurrent_requests – how many concurrent requests might be performed by each client

classmethod freeze()

Freeze all signals

async authorize()

Special method for authorize client. If this method return True then access allowed, otherwise 403 Forbidden will be sent.

This method will be called before socket connection establishment.

By default everyone has access. You have to inherit this class and change this behaviour.

Note

You can validate some headers (self.request.headers) or check cookies (self.reauest.cookies).

classmethod broadcast(func, callback=None, return_exceptions=True, **kwargs)

Call remote function on all connected clients

Parameters:

  • func – Remote route name

  • callback – Function which receive responses

  • return_exceptions – Return exceptions of client calls instead of raise a first one

Route

class wsrpc_aiohttp.Route(socket: SocketT)
property socket
property loop

AllowedRoute

class wsrpc_aiohttp.AllowedRoute(socket: SocketT)
property socket
property loop

PrefixRoute

class wsrpc_aiohttp.PrefixRoute(socket: SocketT)
property socket
property loop

WebSocketRoute

class wsrpc_aiohttp.WebSocketRoute(socket: SocketT)
property socket
property loop
classmethod noproxy(func)

ClientException

class wsrpc_aiohttp.ClientException(payload)

WSRPCError

class wsrpc_aiohttp.WSRPCError

Serialization

wsrpc_aiohttp.STATIC_DIR

Installed JavaScript clients and TypeScript declarations.

wsrpc_aiohttp.serializer(value)

singledispatch wrapped function. You might register custom types if you want pass it to the remote side.

from wsrpc_aiohttp import serializer

class MyObject:
    def __init__(self):
        self.foo = 'bar'

@serializer.register(MyObject)
def _(value: MyObject) -> dict:
    return {'myObject': {'foo': value.foo}}
wsrpc_aiohttp.websocket.decorators.proxy(func: Callable[P, T])
wsrpc_aiohttp.websocket.decorators.noproxy(func: Callable[P, T])
wsrpc_aiohttp.signal.receiver(s: Signal[P])
class wsrpc_aiohttp.signal.Signal
connect(receiver: Callable[P, Coroutine[Any, Any, Any]])
call(*args: P.args, **kwargs: P.kwargs)
copy()
property is_frozen
freeze()