Skip to content

hikari.api.shard#

Provides an interface for gateway shard implementations to conform to.

ChannelInfoField #

Bases: str, Enum

Fields which can be requested through hikari.api.shard.GatewayShard.request_channel_info.

STATUS class-attribute instance-attribute #

STATUS = 'status'

The voice channel status.

VOICE_START_TIME class-attribute instance-attribute #

VOICE_START_TIME = 'voice_start_time'

When the ongoing voice session in the voice channel started.

GatewayCompression #

Bases: str, Enum

Types of gateway compression that may be supported.

PAYLOAD_ZLIB_STREAM class-attribute instance-attribute #

PAYLOAD_ZLIB_STREAM = 'payload_zlib_stream'

Payload compression using ZLIB.

TRANSPORT_ZLIB_STREAM class-attribute instance-attribute #

TRANSPORT_ZLIB_STREAM = 'transport_zlib_stream'

Transport compression using ZLIB.

TRANSPORT_ZSTD_STREAM class-attribute instance-attribute #

TRANSPORT_ZSTD_STREAM = 'transport_zstd_stream'

Transport compression using ZSTD.

GatewayDataFormat #

Bases: str, Enum

Format of inbound gateway payloads.

ETF class-attribute instance-attribute #

ETF = 'etf'

Erlang transmission format.

JSON class-attribute instance-attribute #

JSON = 'json'

Javascript serialized object notation.

GatewayShard #

Bases: ABC

Interface for a definition of a v10 compatible websocket gateway.

Each instance should represent a single shard.

capabilities abstractmethod property #

capabilities: GatewayCapabilities

Capabilities set on this shard.

heartbeat_latency abstractmethod property #

heartbeat_latency: float

Shard's most recent heartbeat latency.

If the information is not yet available, then this will be float('nan') instead.

id abstractmethod property #

id: int

0-based shard ID for this shard.

intents abstractmethod property #

intents: Intents

Intents set on this shard.

is_alive abstractmethod property #

is_alive: bool

Whether the shard is alive.

is_connected abstractmethod property #

is_connected: bool

Whether the shard is connected.

shard_count abstractmethod property #

shard_count: int

Return the total number of shards expected in the entire application.

close abstractmethod async #

close() -> None

Close the websocket if it is connected.

get_user_id abstractmethod #

get_user_id() -> Snowflake

Return the user ID.

RETURNS DESCRIPTION
Snowflake

The user ID for the application user.
RAISES DESCRIPTION
ComponentStateConflictError

When the shard is not connected so it cannot be interacted with.

join abstractmethod async #

join() -> None

Wait indefinitely until the websocket closes.

This can be placed in a task and cancelled without affecting the websocket runtime itself.

request_channel_info abstractmethod async #

request_channel_info(
    guild: SnowflakeishOr[PartialGuild],
    *,
    fields: Sequence[ChannelInfoField],
) -> None

Request ephemeral channel data for the channels of a guild.

The response will be dispatched as a hikari.events.shard_events.ChannelInfoEvent.

PARAMETER DESCRIPTION
guild

The guild to request channel info for.

TYPE: SnowflakeishOr[PartialGuild]

fields

The fields to request.

TYPE: Sequence[ChannelInfoField]

RAISES DESCRIPTION
ComponentStateConflictError

When the shard is not connected so it cannot be interacted with.

request_guild_members abstractmethod async #

request_guild_members(
    guild: SnowflakeishOr[PartialGuild],
    *,
    include_presences: UndefinedOr[bool] = UNDEFINED,
    query: str = "",
    limit: int = 0,
    users: UndefinedOr[
        SnowflakeishSequence[User]
    ] = UNDEFINED,
    nonce: UndefinedOr[str] = UNDEFINED,
) -> None

Request for a guild chunk.

Note

To request the full list of members, set query to "" (empty string) and limit to 0.

PARAMETER DESCRIPTION
guild

The guild to request chunk for.

TYPE: SnowflakeishOr[PartialGuild]

include_presences

If provided, whether to request presences.

TYPE: UndefinedOr[bool] DEFAULT: UNDEFINED

query

If not "", request the members which username starts with the string.

TYPE: str DEFAULT: ''

limit

Maximum number of members to send matching the query.

TYPE: int DEFAULT: 0

users

If provided, the users to request for.

TYPE: UndefinedOr[SnowflakeishSequence[User]] DEFAULT: UNDEFINED

nonce

If provided, the nonce to be sent with guild chunks.

TYPE: UndefinedOr[str] DEFAULT: UNDEFINED

RAISES DESCRIPTION
ValueError

If trying to specify users with query/limit, if limit is not between 0 and 100, both inclusive or if users length is over 100.
MissingIntentError

When trying to request presences without the hikari.intents.Intents.GUILD_MEMBERS or when trying to request the full list of members without hikari.intents.Intents.GUILD_PRESENCES.
ComponentStateConflictError

When the shard is not connected so it cannot be interacted with.

start abstractmethod async #

start() -> None

Start the shard, wait for it to become ready.

update_presence abstractmethod async #

update_presence(
    *,
    idle_since: UndefinedNoneOr[datetime] = UNDEFINED,
    afk: UndefinedOr[bool] = UNDEFINED,
    activity: UndefinedNoneOr[Activity] = UNDEFINED,
    status: UndefinedOr[Status] = UNDEFINED,
) -> None

Update the presence of the shard user.

If the shard is not alive, no physical data will be sent, however, the new presence settings will be remembered for when the shard does connect.

PARAMETER DESCRIPTION
idle_since

The datetime that the user started being idle. If undefined, this will not be changed.

TYPE: UndefinedNoneOr[datetime] DEFAULT: UNDEFINED

afk

Whether to mark the user as AFK. If undefined, this will not be changed.

TYPE: UndefinedOr[bool] DEFAULT: UNDEFINED

activity

The activity to appear to be playing. If undefined, this will not be changed.

TYPE: UndefinedNoneOr[Activity] DEFAULT: UNDEFINED

status

The web status to show. If undefined, this will not be changed.

TYPE: UndefinedOr[Status] DEFAULT: UNDEFINED

RAISES DESCRIPTION
ComponentStateConflictError

When the shard is not connected so it cannot be interacted with.

update_voice_state abstractmethod async #

update_voice_state(
    guild: SnowflakeishOr[PartialGuild],
    channel: SnowflakeishOr[GuildVoiceChannel] | None,
    *,
    self_mute: UndefinedOr[bool] = UNDEFINED,
    self_deaf: UndefinedOr[bool] = UNDEFINED,
) -> None

Update the voice state for this shard in a given guild.

PARAMETER DESCRIPTION
guild

The guild or guild ID to update the voice state for.

TYPE: SnowflakeishOr[PartialGuild]

channel

The channel or channel ID to update the voice state for. If None then the bot will leave the voice channel that it is in for the given guild.

TYPE: SnowflakeishOr[GuildVoiceChannel] | None

self_mute

If specified and True, the bot will mute itself in that voice channel. If False, then it will unmute itself.

TYPE: UndefinedOr[bool] DEFAULT: UNDEFINED

self_deaf

If specified and True, the bot will deafen itself in that voice channel. If False, then it will undeafen itself.

TYPE: UndefinedOr[bool] DEFAULT: UNDEFINED

RAISES DESCRIPTION
ComponentStateConflictError

When the shard is not connected so it cannot be interacted with.