Skip to content

hikari.traits#

Core app interface for application implementations.

CacheAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for a cache-aware object.

Any cache-aware objects are able to access the Discord application cache.

cache abstractmethod property #

cache: Cache

Immutable cache implementation for this object.

EntityFactoryAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for an entity factory-aware object.

These components will be able to construct library entities.

entity_factory abstractmethod property #

entity_factory: EntityFactory

Entity factory implementation for this object.

EventFactoryAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for an event factory-aware object.

These components are able to construct library events.

event_factory abstractmethod property #

event_factory: EventFactory

Event factory component.

EventManagerAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for a event manager-aware object.

event manager-aware components are able to manage event listeners and waiters.

event_manager abstractmethod property #

event_manager: EventManager

Event manager for this object.

ExecutorAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for an executor-aware object.

These components will contain an executor attribute that may return a concurrent.futures.Executor or None if the default asyncio thread pool for the event loop is used.

executor abstractmethod property #

executor: Executor | None

Executor to use for blocking operations.

This may return None if the default asyncio thread pool should be used instead.

GatewayBotAware #

Bases: RESTAware, Runnable, ShardAware, EventFactoryAware, EventManagerAware, CacheAware, FastProtocolChecking, Protocol

Structural supertype for a component that has all the gateway components.

IntentsAware #

Bases: FastProtocolChecking, Protocol

A component that is aware of the application intents.

intents abstractmethod property #

intents: Intents

Intents registered for the application.

InteractionServerAware #

Bases: RESTAware, EntityFactoryAware, FastProtocolChecking, Protocol

Structural supertype for a interaction REST server-aware object.

interaction_server abstractmethod property #

interaction_server: InteractionServer

Interaction server this app is bound to.

NetworkSettingsAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for any component aware of network settings.

http_settings abstractmethod property #

http_settings: HTTPSettings

HTTP settings in use by this component.

proxy_settings abstractmethod property #

proxy_settings: ProxySettings

Proxy settings in use by this component.

RESTAware #

Bases: EntityFactoryAware, NetworkSettingsAware, ExecutorAware, FastProtocolChecking, Protocol

Structural supertype for a REST-aware object.

These are able to perform REST API calls.

rest abstractmethod property #

rest: RESTClient

REST client to use for HTTP requests.

RESTBotAware #

Bases: InteractionServerAware, Runnable, FastProtocolChecking, Protocol

Structural supertype for a component that has all the RESTful components.

on_shutdown abstractmethod property #

on_shutdown: Sequence[
    Callable[[Self], Coroutine[Any, Any, None]]
]

Sequence of the bot's asynchronous shutdown callbacks.

on_startup abstractmethod property #

on_startup: Sequence[
    Callable[[Self], Coroutine[Any, Any, None]]
]

Sequence of the bot's asynchronous startup callbacks.

add_shutdown_callback abstractmethod #

add_shutdown_callback(
    callback: Callable[
        [RESTBotAware], Coroutine[Any, Any, None]
    ],
) -> None

Add an asynchronous callback to be called when the bot shuts down.

PARAMETER DESCRIPTION
callback

The asynchronous shutdown callback to add.

TYPE: Callable[[RESTBotAware], Coroutine[Any, Any, None]]

add_startup_callback abstractmethod #

add_startup_callback(
    callback: Callable[
        [RESTBotAware], Coroutine[Any, Any, None]
    ],
) -> None

Add an asynchronous callback to be called when the bot starts up.

PARAMETER DESCRIPTION
callback

The asynchronous startup callback to add.

TYPE: Callable[[RESTBotAware], Coroutine[Any, Any, None]]

remove_shutdown_callback abstractmethod #

remove_shutdown_callback(
    callback: Callable[
        [RESTBotAware], Coroutine[Any, Any, None]
    ],
) -> None

Remove an asynchronous shutdown callback from the bot.

PARAMETER DESCRIPTION
callback

The shutdown callback to remove.

TYPE: Callable[[RESTBotAware], Coroutine[Any, Any, None]]

RAISES DESCRIPTION
ValueError

If the callback was not registered.

remove_startup_callback abstractmethod #

remove_startup_callback(
    callback: Callable[
        [RESTBotAware], Coroutine[Any, Any, None]
    ],
) -> None

Remove an asynchronous startup callback from the bot.

PARAMETER DESCRIPTION
callback

The asynchronous startup callback to remove.

TYPE: Callable[[RESTBotAware], Coroutine[Any, Any, None]]

RAISES DESCRIPTION
ValueError

If the callback was not registered.

Runnable #

Bases: FastProtocolChecking, Protocol

Structural super-type for an application which can be run independently.

is_alive abstractmethod property #

is_alive: bool

Whether the application is running or not.

This is useful as some functions might raise hikari.errors.ComponentStateConflictError if this is False.

close abstractmethod async #

close() -> None

Kill the application by shutting all components down.

join abstractmethod async #

join() -> None

Wait indefinitely until the application closes.

This can be placed in a task and cancelled without affecting the application runtime itself. Any exceptions raised by shards will be propagated to here.

run abstractmethod #

run() -> None

Start the application and block until it's finished running.

start abstractmethod async #

start() -> None

Start the application and then return.

ShardAware #

Bases: IntentsAware, NetworkSettingsAware, ExecutorAware, VoiceAware, FastProtocolChecking, Protocol

Structural supertype for a shard-aware object.

These will expose a mapping of shards, the intents in use and the bot user object.

heartbeat_latencies abstractmethod property #

heartbeat_latencies: Mapping[int, float]

Mapping of shard ID to heartbeat latency.

Any shards that are not yet started will be float('nan').

heartbeat_latency abstractmethod property #

heartbeat_latency: float

Average heartbeat latency of all started shards.

If no shards are started, this will return float('nan').

shard_count abstractmethod property #

shard_count: int

Number of shards in the total application.

This may not be the same as the size of shards. If the application is auto-sharded, this may be 0 until the shards are started.

shards abstractmethod property #

shards: Mapping[int, GatewayShard]

Mapping of shards in this application instance.

Each shard ID is mapped to the corresponding shard instance.

If the application has not started, it is acceptable to assume the result of this call will be an empty mapping.

get_me abstractmethod #

get_me() -> OwnUser | None

Return the bot user, if known.

This should be available as soon as the bot has fired the hikari.events.lifetime_events.StartingEvent.

Until then, this may or may not be None.

RETURNS DESCRIPTION
Optional[OwnUser]

The bot user, if known, otherwise None.

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
RuntimeError

If the guild passed isn't covered by any of the shards in this sharded client.
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.
RuntimeError

If the guild passed isn't covered by any of the shards in this sharded client.
ComponentStateConflictError

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

update_presence abstractmethod async #

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

Update the presence on all shards.

This call will patch the presence on each shard. This means that unless you explicitly specify a parameter, the previous value will be retained. This means you do not have to track the global presence in your code.

Note

This will only send the update payloads to shards that are alive. Any shards that are not alive will cache the new presence for when they do start.

Note

If you want to set presences per shard, access the shard you wish to update (e.g. by using [hikari.GatewayBot.shards][]), and call hikari.api.shard.GatewayShard.update_presence on that shard. This method is simply a facade to make performing this in bulk simpler.

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 be marked 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 bot 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
RuntimeError

If the guild passed isn't covered by any of the shards in this sharded client.
ComponentStateConflictError

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

VoiceAware #

Bases: FastProtocolChecking, Protocol

Structural supertype for a voice-aware object.

This is an object that provides a voice property to allow the creation of custom voice client instances.

voice abstractmethod property #

voice: VoiceComponent

Voice connection manager component for this application.