illest.py 2.3.1

Rich Presence (rpc)

Read from the library itself: every signature and every word here is its own docstring.

Presence

class

illest.rpc.Presence

class Presence(client_id: 'str | int', *, pipe: 'int | str | None' = None, auto_reconnect: 'bool' = True, timeout: 'float' = 5.0, reconnect_delay: 'float' = 1.0, max_reconnect_delay: 'float' = 15.0)

A program's Rich Presence on ILLEST, without asyncio: pypresence's Presence, for the ILLEST desktop app.

Python

from illest.rpc import Presence
import time

rpc = Presence("1234567890123456789")
rpc.connect()
rpc.update(details="Exploring the caves", state="Level 4", start=time.time(), large_image="caves")

Every method blocks until the app answers, at most timeout seconds. The pipe is kept by a thread of its own, which also brings the activity back when the app restarts (see AsyncPresence). close() ends that thread; use the object as a context manager to have it closed for you.

client_id

property

connected

property

ready

property

connect

connect() -> 'dict[str, Any]'

Find the app's pipe and say which application this is. Raises NotRunning when no app is listening.

update

update(*, state: 'str | None' = None, details: 'str | None' = None, start: 'float | _dt.datetime | None' = None, end: 'float | _dt.datetime | None' = None, large_image: 'str | None' = None, large_text: 'str | None' = None, small_image: 'str | None' = None, small_text: 'str | None' = None, party_size: 'Sequence[int] | None' = None, buttons: 'Sequence[dict[str, str]] | None' = None, activity_type: 'ActivityType | str | int | None' = None, pid: 'int | None' = None) -> 'dict[str, Any] | None'

Say what the person is doing now; see AsyncPresence.update.

clear

clear(pid: 'int | None' = None) -> 'None'

Take the activity away.

ping

ping() -> 'float'

How long the app takes to answer, in seconds.

close

close() -> 'None'

Close the pipe, which takes the activity away, and end the thread that kept it.

AsyncPresence

class

illest.rpc.AsyncPresence

class AsyncPresence(client_id: 'str | int', *, pipe: 'int | str | None' = None, auto_reconnect: 'bool' = True, timeout: 'float' = 5.0, reconnect_delay: 'float' = 1.0, max_reconnect_delay: 'float' = 15.0)

A program's Rich Presence on ILLEST, from asyncio: pypresence's AioPresence, for the ILLEST desktop app.

Python

rpc = AsyncPresence("1234567890123456789")
await rpc.connect()
await rpc.update(details="Ranked match", state="In a group", start=time.time(), party_size=[2, 5])

The person sees the card once they have allowed the application on their computer (the app asks them the first time).

With auto_reconnect (the default), losing the app (it quit, restarted or updated) is not an error: the activity is kept, the pipe is looked for again, a little less often each time up to every max_reconnect_delay seconds, and the last activity is sent again as soon as the app is back. update() and clear() while it is away keep the newest word and return None.

connected

property

Whether the pipe to the app is open now.

connect

async

async connect() -> 'dict[str, Any]'

Find the app's pipe and say which application this is. Raises NotRunning when no app is listening.

update

async

async update(*, state: 'str | None' = None, details: 'str | None' = None, start: 'float | _dt.datetime | None' = None, end: 'float | _dt.datetime | None' = None, large_image: 'str | None' = None, large_text: 'str | None' = None, small_image: 'str | None' = None, small_text: 'str | None' = None, party_size: 'Sequence[int] | None' = None, buttons: 'Sequence[dict[str, str]] | None' = None, activity_type: 'ActivityType | str | int | None' = None, pid: 'int | None' = None) -> 'dict[str, Any] | None'

Say what the person is doing now. Every call replaces the one before it.

large_image and small_image are image keys of your application (uploaded in the developer portal) or http(s) addresses, which the app fetches once and keeps on the person's server, so nobody who sees the card asks your site for it. start alone counts up, end alone counts down and both draw a bar. activity_type is playing (the default), listening, watching or competing. Up to two buttons, each {"label": ..., "url": "https://..."}.

Answers what the app took, or None when it is away and the activity will be sent once it is back.

clear

async

async clear(pid: 'int | None' = None) -> 'None'

Take the activity away. Closing does too.

ping

async

async ping() -> 'float'

How long the app takes to answer, in seconds.

close

async

async close() -> 'None'

Close the pipe, which takes the activity away. The object can connect() again after.

build_activity

decorator

illest.rpc.build_activity

build_activity(*, state: 'str | None' = None, details: 'str | None' = None, start: 'float | _dt.datetime | None' = None, end: 'float | _dt.datetime | None' = None, large_image: 'str | None' = None, large_text: 'str | None' = None, small_image: 'str | None' = None, small_text: 'str | None' = None, party_size: 'Sequence[int] | None' = None, buttons: 'Sequence[dict[str, str]] | None' = None, activity_type: 'ActivityType | str | int | None' = None) -> 'dict[str, Any]'

The activity as SET_ACTIVITY carries it, checked here so a mistake says so at the line that made it.

RPCError

exceptionfrom Exception

illest.rpc.RPCError

class RPCError(message: 'str', code: 'int' = 0)

An error the desktop app answered, or one on the way to it. code is the app's number for it, 0 where it gave none.

NotRunning

exceptionfrom RPCError

illest.rpc.NotRunning

class NotRunning(message: 'str', code: 'int' = 0)

No desktop app is listening: ILLEST is not running, is a version without Rich Presence, or the person turned it off.

HandshakeRefused

exceptionfrom RPCError

illest.rpc.HandshakeRefused

class HandshakeRefused(message: 'str', code: 'int' = 0)

The app closed the pipe in answer to the handshake: an application id it does not take, or Rich Presence turned off.

Blocked

exceptionfrom RPCError

illest.rpc.Blocked

class Blocked(message: 'str', code: 'int' = 0)

The person blocked this application on this computer, or turned Rich Presence off (code 4006).

UnknownApplication

exceptionfrom RPCError

illest.rpc.UnknownApplication

class UnknownApplication(message: 'str', code: 'int' = 0)

No application has this id. Register one on the developer site (code 4007).

InvalidActivity

exceptionfrom RPCError

illest.rpc.InvalidActivity

class InvalidActivity(message: 'str', code: 'int' = 0)

The app refused what was sent (code 4000).

NotConnected

exceptionfrom RPCError

illest.rpc.NotConnected

class NotConnected(message: 'str', code: 'int' = 0)

connect() has not been called, or close() has.

ConnectionLost

exceptionfrom RPCError

illest.rpc.ConnectionLost

class ConnectionLost(message: 'str', code: 'int' = 0)

The pipe closed while waiting for an answer, as it does when the app quits or restarts.