hikari.presences#

Application and entities that are used to describe guilds on Discord.

Module Contents#

class hikari.presences.ActivityType[source]#

Bases: int, hikari.internal.enums.Enum

The activity type.

PLAYING = 0[source]#

Shows up as Playing.

STREAMING = 1[source]#

Shows up as Streaming and links to a Twitch or YouTube stream/video.

Warning

You MUST provide a valid Twitch or YouTube stream URL to the activity you create in order for this to be valid. If you fail to do this, then the activity WILL NOT update.

LISTENING = 2[source]#

Shows up as Listening to.

WATCHING = 3[source]#

Shows up as Watching.

CUSTOM = 4[source]#

A custom status.

To set an emoji with the status, place a unicode emoji or Discord emoji (:smiley:) as the first part of the status activity name.

Warning

Bots DO NOT support setting custom statuses.

COMPETING = 5[source]#

Shows up as Competing in.

class hikari.presences.ActivityTimestamps[source]#

The datetimes for the start and/or end of an activity session.

start: Optional[datetime.datetime][source]#

When this activity’s session was started, if applicable.

end: Optional[datetime.datetime][source]#

When this activity’s session will end, if applicable.

class hikari.presences.ActivityParty[source]#

Used to represent activity groups of users.

id: Optional[str][source]#

The string id of this party instance, if set.

current_size: Optional[int][source]#

Current size of this party, if applicable.

max_size: Optional[int][source]#

Maximum size of this party, if applicable.

class hikari.presences.ActivityAssets[source]#

Used to represent possible assets for an activity.

property large_image_url: Optional[hikari.files.URL][source]#

Large image asset URL.

Note

This will be None if no large image asset exists or if the asset’s dynamic URL (indicated by a {name}: prefix) is not known.

property small_image_url: Optional[hikari.files.URL][source]#

Small image asset URL.

Note

This will be None if no large image asset exists or if the asset’s dynamic URL (indicated by a {name}: prefix) is not known.

large_image: Optional[str][source]#

The ID of the asset’s large image, if set.

large_text: Optional[str][source]#

The text that’ll appear when hovering over the large image, if set.

small_image: Optional[str][source]#

The ID of the asset’s small image, if set.

small_text: Optional[str][source]#

The text that’ll appear when hovering over the small image, if set.

make_large_image_url(*, ext='png', size=4096)[source]#

Generate the large image asset URL for this application.

Note

ext and size are ignored for images hosted outside of Discord or on Discord’s media proxy.

Parameters
extstr

The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.

sizeint

The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

Returns
typing.Optional[hikari.files.URL]

The URL, or None if no icon exists.

Raises
ValueError

If the size is not an integer power of 2 between 16 and 4096 (inclusive).

RuntimeError

If ActivityAssets.large_image points towards an unknown asset type.

make_small_image_url(*, ext='png', size=4096)[source]#

Generate the small image asset URL for this application.

Parameters
extstr

The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.

sizeint

The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

Returns
typing.Optional[hikari.files.URL]

The URL, or None if no icon exists.

Raises
ValueError

If the size is not an integer power of 2 between 16 and 4096 (inclusive).

RuntimeError

If ActivityAssets.small_image points towards an unknown asset type.

class hikari.presences.ActivitySecret[source]#

The secrets used for interacting with an activity party.

join: Optional[str][source]#

The secret used for joining a party, if applicable.

spectate: Optional[str][source]#

The secret used for spectating a party, if applicable.

match: Optional[str][source]#

The secret used for matching a party, if applicable.

class hikari.presences.ActivityFlag[source]#

Bases: hikari.internal.enums.Flag

Flags that describe what an activity includes.

This can be more than one using bitwise-combinations.

INSTANCE[source]#

Instance.

JOIN[source]#

Join.

SPECTATE[source]#

Spectate.

JOIN_REQUEST[source]#

Join Request.

SYNC[source]#

Sync.

PLAY[source]#

Play.

PARTY_PRIVACY_FRIENDS[source]#

Party privacy: friends only.

PARTY_PRIVACY_VOICE_CHANNEL[source]#

Party privacy: voice channel only.

EMBEDDED[source]#

An activity that’s embedded into a voice channel.

class hikari.presences.Activity[source]#

Represents a regular activity that can be associated with a presence.

name: str[source]#

The activity name.

url: Optional[str][source]#

The activity URL. Only valid for STREAMING activities.

type: Union[ActivityType, int][source]#

The activity type.

class hikari.presences.RichActivity[source]#

Bases: Activity

Represents a rich activity that can be associated with a presence.

created_at: datetime.datetime[source]#

When this activity was added to the user’s session.

timestamps: Optional[ActivityTimestamps][source]#

The timestamps for when this activity’s current state will start and end, if applicable.

application_id: Optional[hikari.snowflakes.Snowflake][source]#

The ID of the application this activity is for, if applicable.

details: Optional[str][source]#

The text that describes what the activity’s target is doing, if set.

state: Optional[str][source]#

The current status of this activity’s target, if set.

emoji: Optional[hikari.emojis.Emoji][source]#

The emoji of this activity, if it is a custom status and set.

party: Optional[ActivityParty][source]#

Information about the party associated with this activity, if set.

assets: Optional[ActivityAssets][source]#

Images and their hover over text for the activity.

secrets: Optional[ActivitySecret][source]#

Secrets for Rich Presence joining and spectating.

is_instance: Optional[bool][source]#

Whether this activity is an instanced game session.

flags: Optional[ActivityFlag][source]#

Flags that describe what the activity includes, if present.

buttons: Sequence[str][source]#

A sequence of up to 2 of the button labels shown in this rich presence.

class hikari.presences.Status[source]#

Bases: str, hikari.internal.enums.Enum

The status of a member.

ONLINE = 'online'[source]#

Online/green.

IDLE = 'idle'[source]#

Idle/yellow.

DO_NOT_DISTURB = 'dnd'[source]#

Do not disturb/red.

OFFLINE = 'offline'[source]#

Offline or invisible/grey.

class hikari.presences.ClientStatus[source]#

The client statuses for this member.

desktop: Union[Status, str][source]#

The status of the target user’s desktop session.

mobile: Union[Status, str][source]#

The status of the target user’s mobile session.

web: Union[Status, str][source]#

The status of the target user’s web session.

class hikari.presences.MemberPresence[source]#

Used to represent a guild member’s presence.

app: hikari.traits.RESTAware[source]#

Client application that models may use for procedures.

user_id: hikari.snowflakes.Snowflake[source]#

The ID of the user this presence belongs to.

guild_id: hikari.snowflakes.Snowflake[source]#

The ID of the guild this presence belongs to.

visible_status: Union[Status, str][source]#

This user’s current status being displayed by the client.

activities: Sequence[RichActivity][source]#

All active user activities.

You can assume the first activity is the one that the GUI Discord client will show.

client_status: ClientStatus[source]#

Platform-specific user-statuses.

async fetch_user()[source]#

Fetch the user this presence is for.

Returns
hikari.users.User

The requested user.

Raises
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.NotFoundError

If the user is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.

async fetch_member()[source]#

Fetch the member this presence is for.

Returns
hikari.guilds.Member

The requested member.

Raises
hikari.errors.UnauthorizedError

If you are unauthorized to make the request (invalid/missing token).

hikari.errors.NotFoundError

If the user is not found.

hikari.errors.RateLimitTooLongError

Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.

hikari.errors.RateLimitedError

Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.

hikari.errors.InternalServerError

If an internal error occurs on Discord while handling the request.