IPC Server Tools

discord_tools provides a simple IPC handler. This section outlines everything about it.

Models

ClientSession

Attributes
Methods
class discord_tools.ipc.ClientSession(host='localhost', port=..., multicast_port=20000, secret_key=..., *, session=...)[source]

A simple wrapper around an ClientSession for easy handling with an IPC server.

Added in version 1.0.

async with x

Asynchronously starts this client session.

Parameters:

  • host (str) – The host to connect to. Defaults to localhost.

  • port (int) – The port to connect to. If missing, uses the multicast port.

  • multicast_port (int) – The multicast port to connect to. Defaults to 20000.

  • secret_key (str) – The secret key to use on the Authorization header on request. This must have the same value as Server.secret_key.

  • session (ClientSession) – The session to use with this handler. If not provided creates a new one.

property resolved_port

Returns the resolved port to connect to, this is either the port parameter or the multicast_port parameter if no value was provided on the previous one.

Type:

int

property secret_key

The secret key to use on authorization, or None.

Type:

Optional[str]

property url

Returns the URL of the websocket.

Type:

str

await request(route, /, **data)[source]

Makes a request to the IPC server.

Parameters:

  • route (Union[str, Route]) – The route to perform the request to.

  • **data (Any) – The data to send to the endpoint.

Return type:

dict[str, Any]

Server

Attributes
Methods
class discord_tools.ipc.Server(client, host='localhost', port=8000, secret_key=..., multicast=True, multicast_port=20000)[source]

The server used for the IPC.

Added in version 1.0.

Parameters:

  • client (Client) – The client associated to this server.

  • host (str) – The host to run the server on. Defaults to localhost.

  • port (int) – The port to run the server on. Defaults to 8000.

  • secret_key (str) – The secret key to check for on the Authorization header on requests. This can be used to limit requests to your bot, you must have the same secret key on the client.

  • multicast (bool) – Whether to enable multicasting. Defaults to True.

  • multicast_port (int) – The port to run the multicasting server on. Defaults to 20000.

property secret_key

Returns the secret key required for requests handling, or None.

Type:

Optional[str]

property ws_url

Returns the websocket URL of this server.

Type:

str

property multicast_ws_url

Returns the multicast websocket URL of this server.

Type:

str

route()[source]

A decorator that registers a coroutine as a server route.

Added in version 1.0.

Parameters:

name (str) – The route name. Defaults to the function name.

await terminate_server()[source]

Terminates the web server.

Return type:

None

Request

Attributes
Methods
class discord_tools.ipc.Request(data, ws, endpoint, headers, loop)[source]

Represents an IPC request.

Added in version 1.0.

for ... in x

Iterates through all the request data keys.

endpoint

The endpoint this request pointed to.

Type:

str

headers

The headers the request provided.

Type:

Dict[str, Any]

keys()[source]

KeysView: Returns all the keys of the data the request provided.

This is similar to dict.keys().

Return type:

KeysView

values()[source]

ValuesView: Returns all the values of the data the request provided.

This is similar to dict.values().

Return type:

ValuesView

items()[source]

ItemsView: Returns (key, value) pairs of all the keys and values the request provided.

This is similar to dict.items().

Return type:

ItemsView

is_done()[source]

bool: Returns whether the request has been responded.

Return type:

bool

await wait_until_done()[source]

Waits for this request to be completed.

This could be useful if you respond to a request on another place outside the route callback.

Return type:

bool

await respond(data, *, compress=None)[source]

Sends a JSON response to this request.

Parameters:

  • data (Dict[str, Any]) – The data to send as response.

  • compress (Optional[bool]) – Whether to compress the response data.

Return type:

None

Route

Attributes
class discord_tools.ipc.Route(callback, name)[source]

Represents a server route.

Added in version 1.0.

str(x)

Returns this route name.

name

The route name, always prefixed with /.

Type:

str

callback

The callback of the route, this is called when it receives a request.

Type:

Callable[…, Coroutine[Any, Any, Any]]

Functions

discord_tools.ipc.route(name=...)[source]

A decorator that registers a coroutine as a server route.

Added in version 1.0.

Parameters:

name (str) – The route name. Defaults to the function name.

Event Reference

discord_tools.ipc.on_raw_ipc_request(request)

Called when the IPC receives a request. This is called before the actual route callback, so it is recommended to not respond to the request in this event nor depend on it.

Note

This event is dispatched always, even if the endpoint is not a valid one.

Parameters:

request (Request) – The raw request

discord_tools.ipc.on_ipc_request_completion(request)

Called when the IPC completes a request. This is called after the route callback.

Note

Unlike on_raw_ipc_request(), this event is not dispatched if the route is not valid.

Parameters:

request (Request) – The request that was completed