hikari.traits#

Core app interface for application implementations.

Module Contents#

class hikari.traits.CacheAware[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for a cache-aware object.

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

abstract property cache: hikari.api.cache.Cache[source]#

Immutable cache implementation for this object.

class hikari.traits.EntityFactoryAware[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for an entity factory-aware object.

These components will be able to construct library entities.

abstract property entity_factory: hikari.api.entity_factory.EntityFactory[source]#

Entity factory implementation for this object.

class hikari.traits.EventFactoryAware[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for an event factory-aware object.

These components are able to construct library events.

abstract property event_factory: hikari.api.event_factory.EventFactory[source]#

Event factory component.

class hikari.traits.EventManagerAware[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for a event manager-aware object.

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

abstract property event_manager: hikari.api.event_manager.EventManager[source]#

Event manager for this object.

class hikari.traits.ExecutorAware[source]#

Bases: hikari.internal.fast_protocol.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.

abstract property executor: concurrent.futures.Executor | None[source]#

Executor to use for blocking operations.

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

class hikari.traits.GatewayBotAware[source]#

Bases: RESTAware, Runnable, ShardAware, EventFactoryAware, EventManagerAware, CacheAware, hikari.internal.fast_protocol.FastProtocolChecking, Protocol

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

class hikari.traits.IntentsAware[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

A component that is aware of the application intents.

abstract property intents: hikari.intents.Intents[source]#

Intents registered for the application.

class hikari.traits.InteractionServerAware[source]#

Bases: RESTAware, EntityFactoryAware, hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for a interaction REST server-aware object.

abstract property interaction_server: hikari.api.interaction_server.InteractionServer[source]#

Interaction server this app is bound to.

class hikari.traits.NetworkSettingsAware[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for any component aware of network settings.

abstract property http_settings: hikari.api.config.HTTPSettings[source]#

HTTP settings in use by this component.

abstract property proxy_settings: hikari.api.config.ProxySettings[source]#

Proxy settings in use by this component.

class hikari.traits.RESTAware[source]#

Bases: EntityFactoryAware, NetworkSettingsAware, ExecutorAware, hikari.internal.fast_protocol.FastProtocolChecking, Protocol

Structural supertype for a REST-aware object.

These are able to perform REST API calls.

abstract property rest: hikari.api.rest.RESTClient[source]#

REST client to use for HTTP requests.

class hikari.traits.RESTBotAware[source]#

Bases: InteractionServerAware, Runnable, hikari.internal.fast_protocol.FastProtocolChecking, Protocol

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

abstract property on_shutdown: Sequence[Callable[[typing_extensions.Self], Coroutine[Any, Any, None]]][source]#

Sequence of the bot’s asynchronous shutdown callbacks.

abstract property on_startup: Sequence[Callable[[typing_extensions.Self], Coroutine[Any, Any, None]]][source]#

Sequence of the bot’s asynchronous startup callbacks.

abstract add_shutdown_callback(callback, /)[source]#

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

Parameters:
callbacktyping.Callable[[RESTBotAware], typing.Coroutine[typing.Any, typing.Any, None]]

The asynchronous shutdown callback to add.

abstract add_startup_callback(callback, /)[source]#

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

Parameters:
callbacktyping.Callable[[RESTBotAware], typing.Coroutine[typing.Any, typing.Any, None]]

The asynchronous startup callback to add.

abstract remove_shutdown_callback(callback, /)[source]#

Remove an asynchronous shutdown callback from the bot.

Parameters:
callbacktyping.Callable[[RESTBotAware], typing.Coroutine[typing.Any, typing.Any, None]]

The shutdown callback to remove.

Raises:
ValueError

If the callback was not registered.

abstract remove_startup_callback(callback, /)[source]#

Remove an asynchronous startup callback from the bot.

Parameters:
callbacktyping.Callable[[RESTBotAware], typing.Coroutine[typing.Any, typing.Any, None]]

The asynchronous startup callback to remove.

Raises:
ValueError

If the callback was not registered.

class hikari.traits.Runnable[source]#

Bases: hikari.internal.fast_protocol.FastProtocolChecking, Protocol

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

abstract property is_alive: bool[source]#

Whether the application is running or not.

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

abstract async close()[source]#

Kill the application by shutting all components down.

abstract async join()[source]#

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.

abstract run()[source]#

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

abstract async start()[source]#

Start the application and then return.

class hikari.traits.ShardAware[source]#

Bases: IntentsAware, NetworkSettingsAware, ExecutorAware, VoiceAware, hikari.internal.fast_protocol.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.

abstract property heartbeat_latencies: Mapping[int, float][source]#

Mapping of shard ID to heartbeat latency.

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

abstract property heartbeat_latency: float[source]#

Average heartbeat latency of all started shards.

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

abstract property shard_count: int[source]#

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.

abstract property shards: Mapping[int, hikari.api.shard.GatewayShard][source]#

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.

abstract get_me()[source]#

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:
typing.Optional[hikari.users.OwnUser]

The bot user, if known, otherwise None.

abstract async request_guild_members(guild, *, include_presences=undefined.UNDEFINED, query='', limit=0, users=undefined.UNDEFINED, nonce=undefined.UNDEFINED)[source]#

Request for a guild chunk.

Note

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

Parameters:
guildhikari.guilds.Guild

The guild to request chunk for.

Other Parameters:
include_presenceshikari.undefined.UndefinedOr[bool]

If provided, whether to request presences.

querystr

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

limitint

Maximum number of members to send matching the query.

usershikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.users.User]]

If provided, the users to request for.

noncehikari.undefined.UndefinedOr[str]

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

Raises:
ValueError

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

hikari.errors.MissingIntentError

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

RuntimeError

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

abstract async update_presence(*, idle_since=undefined.UNDEFINED, status=undefined.UNDEFINED, activity=undefined.UNDEFINED, afk=undefined.UNDEFINED)[source]#

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

Other Parameters:
idle_sincehikari.undefined.UndefinedNoneOr[datetime.datetime]

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

afkhikari.undefined.UndefinedOr[bool]

If True, the user is marked as AFK. If False, the user is marked as being active. If undefined, this will not be changed.

activityhikari.undefined.UndefinedNoneOr[hikari.presences.Activity]

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

statushikari.undefined.UndefinedOr[hikari.presences.Status]

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

abstract async update_voice_state(guild, channel, *, self_mute=undefined.UNDEFINED, self_deaf=undefined.UNDEFINED)[source]#

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

Parameters:
guildhikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]

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

channeltyping.Optional[hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildVoiceChannel]]

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.

self_mutebool

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

self_deafbool

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

Raises:
RuntimeError

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

class hikari.traits.VoiceAware[source]#

Bases: hikari.internal.fast_protocol.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.

abstract property voice: hikari.api.voice.VoiceComponent[source]#

Voice connection manager component for this application.