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: Optional[Executor]

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.

cache abstractmethod property

cache: Cache

Immutable cache implementation for this object.

entity_factory abstractmethod property

entity_factory: EntityFactory

Entity factory implementation for this object.

event_factory abstractmethod property

event_factory: EventFactory

Event factory component.

event_manager abstractmethod property

event_manager: EventManager

Event manager for this object.

executor abstractmethod property

executor: Optional[Executor]

Executor to use for blocking operations.

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

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').

http_settings abstractmethod property

http_settings: HTTPSettings

HTTP settings in use by this component.

intents abstractmethod property

intents: Intents

Intents registered for the application.

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.

proxy_settings abstractmethod property

proxy_settings: ProxySettings

Proxy settings in use by this component.

rest abstractmethod property

rest: RESTClient

REST client to use for HTTP requests.

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.

voice abstractmethod property

voice: VoiceComponent

Voice connection manager component for this application.

close abstractmethod async

close() -> None

Kill the application by shutting all components down.

get_me abstractmethod

get_me() -> Optional[OwnUser]

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.

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.

request_guild_members abstractmethod async

request_guild_members(
    guild: SnowflakeishOr[PartialGuild],
    *,
    include_presences: UndefinedOr[bool] = undefined.UNDEFINED,
    query: str = "",
    limit: int = 0,
    users: UndefinedOr[SnowflakeishSequence[User]] = undefined.UNDEFINED,
    nonce: UndefinedOr[str] = undefined.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: Guild

PARAMETER	DESCRIPTION
include_presences	If provided, whether to request presences. TYPE: UndefinedOr[bool]
query	If not "", request the members which username starts with the string. TYPE: str
limit	Maximum number of members to send matching the query. TYPE: int
users	If provided, the users to request for. TYPE: UndefinedOr[SnowflakeishSequence[User]]
nonce	If provided, the nonce to be sent with guild chunks. TYPE: UndefinedOr[str]

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.

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.

update_presence abstractmethod async

update_presence(
    *,
    idle_since: UndefinedNoneOr[datetime] = undefined.UNDEFINED,
    status: UndefinedOr[Status] = undefined.UNDEFINED,
    activity: UndefinedNoneOr[Activity] = undefined.UNDEFINED,
    afk: UndefinedOr[bool] = undefined.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]
afk	Whether to be marked as AFK. If undefined, this will not be changed. TYPE: UndefinedOr[bool]
activity	The activity to appear to be playing. If undefined, this will not be changed. TYPE: UndefinedNoneOr[Activity]
status	The web status to show. If undefined, this will not be changed. TYPE: UndefinedOr[Status]

update_voice_state abstractmethod async

update_voice_state(
    guild: SnowflakeishOr[PartialGuild],
    channel: Optional[SnowflakeishOr[GuildVoiceChannel]],
    *,
    self_mute: UndefinedOr[bool] = undefined.UNDEFINED,
    self_deaf: UndefinedOr[bool] = undefined.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: Optional[SnowflakeishOr[GuildVoiceChannel]]
self_mute	If specified and True, the bot will mute itself in that voice channel. If False, then it will unmute itself. TYPE: 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: bool DEFAULT: UNDEFINED

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

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.

entity_factory abstractmethod property

entity_factory: EntityFactory

Entity factory implementation for this object.

executor abstractmethod property

executor: Optional[Executor]

Executor to use for blocking operations.

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

http_settings abstractmethod property

http_settings: HTTPSettings

HTTP settings in use by this component.

interaction_server abstractmethod property

interaction_server: InteractionServer

Interaction server this app is bound to.

proxy_settings abstractmethod property

proxy_settings: ProxySettings

Proxy settings in use by this component.

rest abstractmethod property

rest: RESTClient

REST client to use for HTTP requests.

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.

entity_factory abstractmethod property

entity_factory: EntityFactory

Entity factory implementation for this object.

executor abstractmethod property

executor: Optional[Executor]

Executor to use for blocking operations.

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

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.

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.

entity_factory abstractmethod property

entity_factory: EntityFactory

Entity factory implementation for this object.

executor abstractmethod property

executor: Optional[Executor]

Executor to use for blocking operations.

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

http_settings abstractmethod property

http_settings: HTTPSettings

HTTP settings in use by this component.

interaction_server abstractmethod property

interaction_server: InteractionServer

Interaction server this app is bound to.

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.

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.

proxy_settings abstractmethod property

proxy_settings: ProxySettings

Proxy settings in use by this component.

rest abstractmethod property

rest: RESTClient

REST client to use for HTTP requests.

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]]

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.

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.

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.

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.

executor abstractmethod property

executor: Optional[Executor]

Executor to use for blocking operations.

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

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').

http_settings abstractmethod property

http_settings: HTTPSettings

HTTP settings in use by this component.

intents abstractmethod property

intents: Intents

Intents registered for the application.

proxy_settings abstractmethod property

proxy_settings: ProxySettings

Proxy settings in use by this component.

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.

voice abstractmethod property

voice: VoiceComponent

Voice connection manager component for this application.

get_me abstractmethod

get_me() -> Optional[OwnUser]

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_guild_members abstractmethod async

request_guild_members(
    guild: SnowflakeishOr[PartialGuild],
    *,
    include_presences: UndefinedOr[bool] = undefined.UNDEFINED,
    query: str = "",
    limit: int = 0,
    users: UndefinedOr[SnowflakeishSequence[User]] = undefined.UNDEFINED,
    nonce: UndefinedOr[str] = undefined.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: Guild

PARAMETER	DESCRIPTION
include_presences	If provided, whether to request presences. TYPE: UndefinedOr[bool]
query	If not "", request the members which username starts with the string. TYPE: str
limit	Maximum number of members to send matching the query. TYPE: int
users	If provided, the users to request for. TYPE: UndefinedOr[SnowflakeishSequence[User]]
nonce	If provided, the nonce to be sent with guild chunks. TYPE: UndefinedOr[str]

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.

update_presence abstractmethod async

update_presence(
    *,
    idle_since: UndefinedNoneOr[datetime] = undefined.UNDEFINED,
    status: UndefinedOr[Status] = undefined.UNDEFINED,
    activity: UndefinedNoneOr[Activity] = undefined.UNDEFINED,
    afk: UndefinedOr[bool] = undefined.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]
afk	Whether to be marked as AFK. If undefined, this will not be changed. TYPE: UndefinedOr[bool]
activity	The activity to appear to be playing. If undefined, this will not be changed. TYPE: UndefinedNoneOr[Activity]
status	The web status to show. If undefined, this will not be changed. TYPE: UndefinedOr[Status]

update_voice_state abstractmethod async

update_voice_state(
    guild: SnowflakeishOr[PartialGuild],
    channel: Optional[SnowflakeishOr[GuildVoiceChannel]],
    *,
    self_mute: UndefinedOr[bool] = undefined.UNDEFINED,
    self_deaf: UndefinedOr[bool] = undefined.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: Optional[SnowflakeishOr[GuildVoiceChannel]]
self_mute	If specified and True, the bot will mute itself in that voice channel. If False, then it will unmute itself. TYPE: 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: bool DEFAULT: UNDEFINED

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

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.