illest.py 2.3.1

Models

What the library hands you: people, servers, channels, roles and messages.

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

User

classfrom Messageable

illest.User

class User(id: 'int', username: 'str' = '', bot: 'bool' = False, display_name: 'str | None' = None, raw: 'dict[str, Any] | None' = None, *, client: "'Client | None'" = None)

An account. name is its handle, global_name the name it shows; display_name is whichever it shows.

username

property

display_name

property

mention

property

<@id>. Sent in a message, the library writes it out as @name and notifies them.

avatar

property

display_avatar

property

accent_colour

property

accent_color

property

colour

property

color

property

created_at

property

dm_channel

property

mutual_guilds

property

mentioned_in

mentioned_in(message: "'Message'") -> 'bool'

create_dm

async

async create_dm() -> "'DMChannel'"

is_blocked

is_blocked() -> 'bool'

from_wire

classmethod

from_wire(d: 'dict[str, Any]', client: "'Client | None'" = None) -> "'User'"

ClientUser

classfrom User

illest.ClientUser

class ClientUser(id: 'int', username: 'str' = '', bot: 'bool' = False, display_name: 'str | None' = None, raw: 'dict[str, Any] | None' = None, *, client: "'Client | None'" = None)

The bot's own account.

edit

async

async edit(*, username: 'str | None' = None, avatar: 'bytes | None' = None, bio: 'str | None' = None, display_name: 'str | None' = None) -> "'ClientUser'"

Change what the bot shows: its display name, its about text, its picture. Its handle is its owner's to change.

Member

classfrom User

illest.Member

class Member(guild_id: 'Any' = None, user: 'User | None' = None, nick: 'str | None' = None, roles: 'Iterable[Any]' = (), joined_at: 'Any' = 0, timed_out_until: 'Any' = None, raw: 'dict[str, Any] | None' = None, _client: "'Client | None'" = None)

An account in one server: its roles there, its nickname there, when it joined, and whether it is timed out.

Every attribute of User is here too.

user

property

guild_id

property

roles

property

Its roles, @everyone first (lowest first).

top_role

property

guild

property

display_name

property

guild_avatar

property

joined_at

property

timed_out_until

property

communication_disabled_until

property

is_timed_out

is_timed_out() -> 'bool'

colour

property

color

property

guild_permissions

property

voice

property

status

property

raw_status

property

activity

property

pending

property

premium_since

property

permissions_in

permissions_in(channel: "'GuildChannel'") -> 'Permissions'

kick

async

async kick(*, reason: 'str | None' = None) -> 'None'

Remove them from the server (moderate scope, and KICK_MEMBERS above them).

ban

async

async ban(*, reason: 'str | None' = None, delete_message_days: 'int' = 0, delete_message_seconds: 'int' = 0) -> 'None'

Ban them (moderate, BAN_MEMBERS). Their old messages stay: they are ciphertext in everybody's groups; a moderator destroys one with Message.delete.

unban

async

async unban(*, reason: 'str | None' = None) -> 'None'

timeout

async

async timeout(until: 'Any', /, *, reason: 'str | None' = None) -> 'None'

Keep them from speaking: until is a timedelta, a datetime, seconds, or None to lift it (28 days at most).

add_roles

async

async add_roles(*roles: 'Any', reason: 'str | None' = None, atomic: 'bool' = True) -> 'None'

remove_roles

async

async remove_roles(*roles: 'Any', reason: 'str | None' = None, atomic: 'bool' = True) -> 'None'

edit

async

async edit(*, nick: 'str | None' = Ellipsis, roles: 'Sequence[Any] | None' = None, mute: 'bool | None' = None, deafen: 'bool | None' = None, voice_channel: 'Any' = Ellipsis, timed_out_until: 'Any' = Ellipsis, reason: 'str | None' = None, **_: 'Any') -> "'Member'"

move_to

async

async move_to(channel: 'Any', *, reason: 'str | None' = None) -> 'None'

Move them to another voice channel, or out of voice with None (moderate, MOVE_MEMBERS).

fetch_message

async

async fetch_message(id: 'int')

A message this bot holds. An end-to-end encrypted message is readable only once, as it arrives; the bot keeps the newest max_messages (and, with Client(message_store=...), writes them to disk), and that is what it can fetch.

from_wire

classmethod

from_wire(guild_id: 'Any', d: 'dict[str, Any]', client: "'Client | None'" = None) -> "'Member'"

Guild

class

illest.Guild

class Guild(d: 'dict[str, Any]', client: "'Client | None'" = None)

A server, as the bot sees it: its name, owner, channels, roles and the members it has read.

channels

property

text_channels

property

voice_channels

property

stage_channels

property

forums

property

threads

property

by_category

by_category() -> "list[tuple['CategoryChannel | None', list['GuildChannel']]]"

roles

property

Lowest first, @everyone at the start.

default_role

property

members

property

member_count

property

emojis

property

owner

property

me

property

icon

property

created_at

property

system_channel

property

rules_channel

property

public_updates_channel

property

voice_client

property

chunked

property

get_member

get_member(user_id: 'Any') -> 'Member | None'

get_member_named

get_member_named(name: 'str') -> 'Member | None'

get_role

get_role(role_id: 'Any') -> 'Role | None'

get_channel

get_channel(channel_id: 'Any') -> "'GuildChannel | None'"

get_channel_or_thread

get_channel_or_thread(channel_id: 'Any') -> "'GuildChannel | None'"

get_thread

get_thread(thread_id: 'Any') -> 'None'

get_emoji

get_emoji(emoji_id: 'Any') -> 'Emoji | None'

fetch_channels

async

async fetch_channels() -> "list['GuildChannel']"

fetch_channel

async

async fetch_channel(channel_id: 'Any') -> "'GuildChannel'"

fetch_roles

async

async fetch_roles() -> 'list[Role]'

fetch_role

async

async fetch_role(role_id: 'Any') -> 'Role'

fetch_members

fetch_members(*, limit: 'int | None' = 1000, after: 'Any' = None) -> 'AsyncIterator[Member]'

Everyone in the server (members.read), read from the server and kept in members.

chunk

async

async chunk(*, cache: 'bool' = True) -> 'list[Member]'

fetch_member

async

async fetch_member(member_id: 'Any') -> 'Member'

query_members

async

async query_members(query: 'str | None' = None, *, limit: 'int' = 5, user_ids: 'list[int] | None' = None, **_: 'Any') -> 'list[Member]'

fetch_emojis

async

async fetch_emojis() -> 'list[Emoji]'

fetch_emoji

async

async fetch_emoji(emoji_id: 'Any') -> 'Emoji'

kick

async

async kick(user: 'Any', *, reason: 'str | None' = None) -> 'None'

ban

async

async ban(user: 'Any', *, reason: 'str | None' = None, delete_message_days: 'int' = 0, delete_message_seconds: 'int' = 0) -> 'None'

unban

async

async unban(user: 'Any', *, reason: 'str | None' = None) -> 'None'

bulk_ban

async

async bulk_ban(users: 'Iterable[Any]', *, reason: 'str | None' = None, delete_message_seconds: 'int' = 0) -> 'Any'

bans

bans(*, limit: 'int | None' = 1000, before: 'Any' = None, after: 'Any' = None) -> "AsyncIterator['BanEntry']"

fetch_ban

async

async fetch_ban(user: 'Any') -> "'BanEntry'"

audit_logs

audit_logs(*, limit: 'int | None' = 100, before: 'Any' = None, after: 'Any' = None, oldest_first: 'bool' = False, user: 'Any' = None, action: 'Any' = None) -> "AsyncIterator['AuditLogEntry']"

The server's audit log (moderate): who did what, to whom, and why.

invites

async

async invites() -> "list['Invite']"

create_text_channel

async

async create_text_channel(name: 'str', **options: 'Any') -> "'TextChannel'"

create_voice_channel

async

async create_voice_channel(name: 'str', **options: 'Any') -> "'VoiceChannel'"

create_stage_channel

async

async create_stage_channel(name: 'str', **options: 'Any') -> "'StageChannel'"

create_forum

async

async create_forum(name: 'str', **options: 'Any') -> "'ForumChannel'"

create_forum_channel

async

async create_forum_channel(name: 'str', **options: 'Any') -> "'ForumChannel'"

create_category

async

async create_category(name: 'str', **options: 'Any') -> "'CategoryChannel'"

create_category_channel

async

async create_category_channel(name: 'str', **options: 'Any') -> "'CategoryChannel'"

create_role

async

async create_role(*, name: 'str' = 'new role', permissions: 'Permissions | None' = None, colour: 'Any' = None, color: 'Any' = None, hoist: 'bool' = False, mentionable: 'bool' = False, reason: 'str | None' = None, **_: 'Any') -> 'Role'

edit_role_positions

async

async edit_role_positions(positions: 'dict[Role, int]', *, reason: 'str | None' = None) -> 'list[Role]'

create_custom_emoji

async

async create_custom_emoji(*, name: 'str', image: 'bytes', roles: 'Any' = None, reason: 'str | None' = None) -> 'Emoji'

leave

async

async leave() -> 'None'

edit

async

async edit(**_: 'Any') -> "'Guild'"

delete

async

async delete() -> 'None'

vanity_invite

async

async vanity_invite() -> "'Invite | None'"

active_threads

async

async active_threads() -> "list['Thread']"

fetch_voice_states

async

async fetch_voice_states(channel: 'Any') -> 'list[VoiceState]'

from_wire

classmethod

from_wire(d, client=None)

Role

class

illest.Role

class Role(guild: "'Guild'", d: 'dict[str, Any]')

A server's role. The server's @everyone role has the server's own id.

color

property

is_default

is_default() -> 'bool'

is_bot_managed

is_bot_managed() -> 'bool'

is_premium_subscriber

is_premium_subscriber() -> 'bool'

is_integration

is_integration() -> 'bool'

is_assignable

is_assignable() -> 'bool'

mention

property

members

property

created_at

property

edit

async

async edit(*, name: 'str | None' = None, permissions: 'Permissions | None' = None, colour: 'Colour | int | None' = None, color: 'Colour | int | None' = None, hoist: 'bool | None' = None, mentionable: 'bool | None' = None, position: 'int | None' = None, reason: 'str | None' = None, **_: 'Any') -> "'Role'"

Change the role (guilds.manage scope, MANAGE_ROLES, and the bot's top role above it).

delete

async

async delete(*, reason: 'str | None' = None) -> 'None'

TextChannel

classfrom GuildChannel, Messageable

illest.TextChannel

class TextChannel(d: 'dict[str, Any]', guild_id: 'Any' = None, client: "'Client | None'" = None)

A server's text channel.

last_message_id

property

last_message

property

is_news

is_news() -> 'bool'

threads

property

members

property

create_thread

async

async create_thread(*, name: 'str', message: 'Any' = None, auto_archive_duration: 'int' = 1440, type: 'Any' = None, reason: 'str | None' = None, invitable: 'bool' = True, slowmode_delay: 'int | None' = None) -> "'Thread'"

A thread under message (ILLEST threads hang off a message: one level, sealed in the channel's own group). Without a message, the bot first sends name and the thread hangs off that.

get_thread

get_thread(thread_id: 'Any') -> "'Thread'"

purge

async

async purge(*, limit: 'int | None' = 100, check: 'Any' = None, before: 'Any' = None, after: 'Any' = None, around: 'Any' = None, oldest_first: 'bool | None' = None, bulk: 'bool' = True, reason: 'str | None' = None) -> "list['Message']"

Remove messages (moderate scope, MANAGE_MESSAGES). The bot destroys the stored ciphertext of each message it holds that passes check; with no check and no bounds, the channel's newest limit are purged on the server in one step.

delete_messages

async

async delete_messages(messages: 'Iterable[Any]', *, reason: 'str | None' = None) -> 'None'

get_partial_message

get_partial_message(message_id: 'Any') -> "'PartialMessage'"

webhooks

async

async webhooks() -> 'list'

follow

async

async follow(**_: 'Any') -> 'None'

VoiceChannel

classfrom GuildChannel

illest.VoiceChannel

class VoiceChannel(d: 'dict[str, Any]', guild_id: 'Any' = None, client: "'Client | None'" = None)

A voice channel. A bot can see who is in it and move, mute or disconnect them (moderate); it has no microphone, since every call is encrypted from each device.

members

property

voice_states

property

connect

async

async connect(**_: 'Any') -> 'None'

StageChannel

classfrom VoiceChannel

illest.StageChannel

class StageChannel(d: 'dict[str, Any]', guild_id: 'Any' = None, client: "'Client | None'" = None)

CategoryChannel

classfrom GuildChannel

illest.CategoryChannel

class CategoryChannel(d: 'dict[str, Any]', guild_id: 'Any' = None, client: "'Client | None'" = None)

channels

property

text_channels

property

voice_channels

property

create_text_channel

async

async create_text_channel(name: 'str', **options: 'Any') -> 'TextChannel'

create_voice_channel

async

async create_voice_channel(name: 'str', **options: 'Any') -> 'VoiceChannel'

create_forum

async

async create_forum(name: 'str', **options: 'Any') -> "'ForumChannel'"

ForumChannel

classfrom GuildChannel

illest.ForumChannel

class ForumChannel(d: 'dict[str, Any]', guild_id: 'Any' = None, client: "'Client | None'" = None)

A forum: each post is a thread whose first message carries its title and tags, sealed like any message.

available_tags

property

get_tag

get_tag(tag_id: 'Any') -> 'ForumTag | None'

threads

property

create_thread

async

async create_thread(*, name: 'str', content: 'str | None' = None, embed: 'Any' = None, embeds: 'Any' = None, file: 'Any' = None, files: 'Any' = None, view: 'Any' = None, applied_tags: 'Sequence[Any]' = (), allowed_mentions: 'Any' = None, reason: 'str | None' = None, **_: 'Any') -> "'ThreadWithMessage'"

Thread

classfrom Messageable

illest.Thread

class Thread(parent: 'Any', root_wire_id: 'str', *, name: 'str | None' = None)

A thread: the messages hanging off one message in a channel. Its id is that first message's id. A thread lives in its channel's encrypted group, so everyone who reads the channel reads it.

parent_id

property

guild

property

starter_message

property

owner_id

property

mention

property

jump_url

property

is_private

is_private() -> 'bool'

join

async

async join() -> 'None'

leave

async

async leave() -> 'None'

edit

async

async edit(**_: 'Any') -> "'Thread'"

DMChannel

classfrom PrivateBase

illest.DMChannel

class DMChannel(d: 'dict[str, Any]', client: "'Client | None'" = None)

A direct conversation with one account.

recipient

property

me

property

GroupChannel

classfrom PrivateBase

illest.GroupChannel

class GroupChannel(d: 'dict[str, Any]', client: "'Client | None'" = None)

A group conversation.

owner

property

leave

async

async leave() -> 'None'

Message

class

illest.Message

class Message(id: 'Any', channel_id: 'Any', author_id: 'int', body: 'str', sent_at: 'Any' = 0, embeds: 'list[dict] | None' = None, buttons: 'list[dict] | None' = None, visible_to: 'int | None' = None, author_verified: 'bool' = False, author_key_changed: 'bool' = False, late: 'bool' = False, reply_to: 'str | None' = None, thread_root: 'str | None' = None, mentions: 'list[int] | None' = None, attachments: 'list[dict] | None' = None, sender_device: 'str | None' = None, edited_at: 'float | None' = None, _client: "'Client | None'" = None, *, interaction: 'dict[str, Any] | None' = None, deferred: 'bool' = False, post: 'dict[str, Any] | None' = None, nonce: 'str | None' = None, silent: 'bool' = False, created_at: 'Any' = None)

A message, opened and proven.

author_verified is ILLEST's own: True only when the sender's device proves the account author names (a device certified by that account, under the key this bot has known it by). A handler that authorises anything by who sent it checks it first.

id

property

content

property

clean_content

property

system_content

property

created_at

property

edited_at

property

channel

property

guild

property

guild_id

property

author

property

Who sent it: a Member in a server the bot knows, else a User.

jump_url

property

embeds

property

components

property

attachments

property

mentions

property

role_mentions

property

channel_mentions

property

mention_everyone

property

reference

property

interaction

property

interaction_metadata

property

type

property

pinned

property

reactions

property

thread

property

ephemeral

property

is_system

is_system() -> 'bool'

reply

async

async reply(content: 'Any' = None, *, mention_author: 'bool | None' = None, **kwargs: 'Any') -> "'Message'"

send

async

async send(content: 'Any' = None, **kwargs: 'Any') -> "'Message'"

Send to the same channel (this library's first version had it; message.channel.send is the current way).

edit

async

async edit(content: 'Any' = Ellipsis, *, embed: 'Any' = Ellipsis, embeds: 'Any' = Ellipsis, attachments: 'Any' = Ellipsis, view: 'Any' = Ellipsis, delete_after: 'float | None' = None, suppress: 'bool' = False, allowed_mentions: 'Any' = None) -> "'Message'"

Change one of this bot's own messages: its text, its cards, its buttons. Every client ignores an edit from anybody else.

delete

async

async delete(*, delay: 'float | None' = None, reason: 'str | None' = None) -> 'None'

This bot's own message is taken back on every client. Somebody else's is destroyed on the server as a moderator (moderate scope, MANAGE_MESSAGES), which removes its ciphertext for everyone.

redact

async

async redact() -> 'None'

add_reaction

async

async add_reaction(emoji: 'Any') -> 'None'

remove_reaction

async

async remove_reaction(emoji: 'Any', member: 'Any' = None) -> 'None'

clear_reaction

async

async clear_reaction(emoji: 'Any') -> 'None'

clear_reactions

async

async clear_reactions() -> 'None'

async

async pin(*, reason: 'str | None' = None) -> 'None'

unpin

async

async unpin(*, reason: 'str | None' = None) -> 'None'

create_thread

async

async create_thread(*, name: 'str', **_: 'Any') -> 'Thread'

fetch

async

async fetch() -> "'Message'"

to_reference

to_reference(*, fail_if_not_exists: 'bool' = True) -> 'MessageReference'

publish

async

async publish() -> 'None'

forward

async

async forward(destination: 'Any', **_: 'Any') -> "'Message'"

PartialMessage

class

illest.PartialMessage

class PartialMessage(*, channel: 'Any', id: 'int')

A message known by its id and channel only, for the verbs that need nothing else.

guild

property

fetch

async

async fetch() -> 'Message'

delete

async

async delete(*, delay: 'float | None' = None) -> 'None'

add_reaction

async

async add_reaction(emoji: 'Any') -> 'None'

remove_reaction

async

async remove_reaction(emoji: 'Any', member: 'Any' = None) -> 'None'

async

async pin(*, reason: 'str | None' = None) -> 'None'

unpin

async

async unpin(*, reason: 'str | None' = None) -> 'None'

reply

async

async reply(content: 'Any' = None, **kwargs: 'Any') -> 'Message'

edit

async

async edit(**kwargs: 'Any') -> 'Message'

to_reference

to_reference(**_: 'Any') -> 'MessageReference'

jump_url

property

Attachment

class

illest.Attachment

class Attachment(ref: 'dict[str, Any]', client: "'Client | None'" = None)

A file a message carries. It was sealed by its sender with a key that travels inside the message; read() fetches the ciphertext and opens it here.

url

property

proxy_url

property

is_spoiler

is_spoiler() -> 'bool'

read

async

async read(*, use_cached: 'bool' = False) -> 'bytes'

save

async

async save(fp: 'Any', *, seek_begin: 'bool' = True, use_cached: 'bool' = False) -> 'int'

to_file

async

async to_file(*, filename: 'str | None' = None, description: 'str | None' = None, spoiler: 'bool' = False) -> 'Any'

Reaction

class

illest.Reaction

class Reaction(channel_id: 'Any' = None, message_id: 'Any' = None, emoji: 'Any' = '', user_id: 'int' = 0, removed: 'bool' = False, burst: 'bool' = False, user_verified: 'bool' = False, message: 'Message | None' = None, *, count: 'int' = 1, me: 'bool' = False)

An emoji on a message. Delivered to on_reaction_add(reaction, user) and kept on message.reactions.

The first version of this library handed on_reaction_add the reaction alone, with its user_id; those fields stay.

is_custom_emoji

is_custom_emoji() -> 'bool'

users

users(*, limit: 'int | None' = None, after: 'Any' = None) -> 'AsyncIterator[User]'

remove

async

async remove(user: 'Any') -> 'None'

clear

async

async clear() -> 'None'

Emoji

classfrom PartialEmoji

illest.Emoji

class Emoji(guild: "'Guild'", d: 'dict[str, Any]')

A server's own emoji.

url

property

delete

async

async delete(*, reason: 'str | None' = None) -> 'None'

PartialEmoji

class

illest.PartialEmoji

class PartialEmoji(*, name: 'str', id: 'int | None' = None, animated: 'bool' = False)

An emoji as a message carries it: a Unicode emoji (name only), or a server's (<:name:id>).

from_str

classmethod

from_str(value: 'str') -> "'PartialEmoji'"

is_custom_emoji

is_custom_emoji() -> 'bool'

is_unicode_emoji

is_unicode_emoji() -> 'bool'

to_wire

to_wire() -> 'str'

Invite

class

illest.Invite

class Invite(client: "'Client'", d: 'dict[str, Any]', guild: 'Guild | None' = None)

url

property

delete

async

async delete(*, reason: 'str | None' = None) -> 'None'

BanEntry

class

illest.BanEntry

class BanEntry(reason: 'str | None', user: 'User')

AuditLogEntry

class

illest.AuditLogEntry

class AuditLogEntry(guild: 'Guild', d: 'dict[str, Any]')

One line of a server's audit log. action is the server's own word for it (member.kick, role.create...).

user

property

target

property

Object

class

illest.Object

class Object(id: 'Any', *, type: 'type | None' = None)

A stand-in with an id, and type to say what it stands for.

created_at

property

Asset

class

illest.Asset

class Asset(client: "'Client | None'", blob_id: 'str', *, kind: 'str' = 'avatar')

A picture the server keeps in the clear: an avatar, a banner, a server's icon. url is where it is read from.

url

property

read

async

async read() -> 'bytes'

save

async

async save(fp: 'Any') -> 'int'

with_size

with_size(size: 'int') -> "'Asset'"

with_format

with_format(format: 'str') -> "'Asset'"

with_static_format

with_static_format(format: 'str') -> "'Asset'"

User

username

display_name

mention

avatar

display_avatar

banner

accent_colour

accent_color

colour

color

created_at

dm_channel

mutual_guilds

mentioned_in

create_dm

is_blocked

from_wire

ClientUser

edit

Member

user

guild_id

roles

top_role

guild

display_name

guild_avatar

joined_at

timed_out_until

communication_disabled_until

is_timed_out

colour

color

guild_permissions

voice

status

raw_status

activity

pending

premium_since

permissions_in

kick

ban

unban

timeout

add_roles

remove_roles

edit

move_to

fetch_message

from_wire

Guild

channels

text_channels

voice_channels

stage_channels

categories

forums

threads

by_category

roles

default_role

members

member_count

emojis

owner

me

icon

banner

created_at

system_channel

rules_channel

public_updates_channel

voice_client

chunked

get_member

get_member_named

get_role

get_channel