Toggle Light / Dark / Auto color theme

Toggle table of contents sidebar

Client

The client manages gateway connection, state and is used as the main entry point of the application.

class mutiny.Client(*, token: str, session_token: None = '...', api_url: str = '...', gateway_format: Optional[Literal[json, msgpack]] = '...')

class mutiny.Client(*, token: None = '...', session_token: str, api_url: str = '...', gateway_format: Optional[Literal[json, msgpack]] = '...')

Client that connects to the Revolt’s APIs. This class is used to interact with all of the Revolt’s services.

Examples

Creating a client for a bot account:

import os
import mutiny

client = mutiny.Client(token=os.environ["BOT_TOKEN"])

Creating a client for a user account:

import os
import mutiny

client = mutiny.Client(session_token=os.environ["BOT_SESSION_TOKEN"])

Parameters

• token (Optional[str]) – The bot’s token. This should be passed for bot accounts.

• session_token (Optional[str]) – User’s session token. This should be passed for user accounts.

• api_url (str) – The API URL. Used for self-hosted Revolt servers.

• gateway_format (Optional[Literal['json', 'msgpack']]) –

  Format to be used by the gateway. When not passed, the format will be chosen based on the installed dependencies. msgpack is preferred over json.

  Tip

  To use msgpack, you need to install Mutiny with the msgpack extra, e.g.:

  pip install -U mutiny[msgpack]
  

@listen(event_cls: type) → Callable[[EventListener[EventT_contra, T]], EventListener[EventT_contra, T]]

@listen(event_cls: None = None) → Callable[[EventListener[EventT_contra, T]], EventListener[EventT_contra, T]]

Register a function to listen to an event.

Examples

Event listener can be added by defining a single argument function decorated with @client.listen() and with its argument annotated with an appropriate event type:

@client.listen()
async def function(event: mutiny.events.MessageEvent):
    print(f"Received a message: {event.message!r}")

Alternatively, you can omit the type annotation or use an incompatible one if you pass the event class as an argument to the decorator:

@client.listen(mutiny.events.MessageEvent)
async def function(event):
    print(f"Received a message: {event.message!r}")

Parameters

event_cls – Event to listen to. If omitted, the type annotation of the first argument of the passed function will be used.

Returns

The passed function, unchanged.

await wait_for(event_cls, /, *, check=None, timeout=None)

Waits for a matching event to be dispatched.

Parameters

• event_cls (type) – The event to wait for.

• check (Optional[Callable[[mutiny._internal.event_handler.EventT], bool]]) – A predicate to check what to wait for. It will be called with an event of a type event_cls and should return True if the event should match.

• timeout (Optional[int]) – The numbers of seconds to wait for, or None to block until a valid event is received.

Raises

asyncio.TimeoutError – If a timeout occurs.

Returns

An event of a type event_cls.

await start()

Creates a websocket connection and lets the websocket listen to messages from the Revolt’s gateway.

This is a loop that runs the entire event system. Control is not resumed until the WebSocket connection is terminated.

Raises

• InvalidCredentials – If the authentication fails due to invalid credentials.

• OnboardingNotFinished – If the authentication fails due to unfinished onboarding.

• AuthenticationError – If the authentication fails for a different reason.

await login()

Logs in the client. Necessary to make the REST API requests.

This will be called for you if you’re connecting to the gateway using start() and should only need to be called if you only want to make API requests without connecting to the gateway.

await close()

Closes the client and its connections.

This should be called before closing the application.

clear()

Clears all of Client’s state and allows the Client to be used again.

This is a separate action from close() and should only be done if you want to use the Client for a new connection.

Note

For a proper teardown of the client and its connections, you need to call close() after finishing the previous connection and before you call this method.

add_listener(listener, *, event_cls=None)

Register a function to listen to an event.

Examples

Registering a bound method of a class as an event listener:

class CoolClass:
    def __init__(self, client):
        self.client = client

    async def message_listener(self, event: mutiny.events.MessageEvent):
        print(f"Received a message: {event.message!r}")

    def register_listeners(self):
        self.client.add_listener(self.message_listener)

cool_class = CoolClass(client)
cool_class.register_listeners()

Parameters

• listener (event listener) – A function to register as an event listener.

• event_cls (Optional[type]) – Event to listen to. If omitted, the type annotation of the first argument of the passed function will be used.