Core app interface for application implementations.

This module

Expand source code
Browse git 
# -*- coding: utf-8 -*-
# cython: language_level=3
# Copyright (c) 2020 Nekokatt
# Copyright (c) 2021-present davfsa
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Core app interface for application implementations."""
from __future__ import annotations

__all__: typing.Sequence[str] = (
    "CacheAware",
    "EventManagerAware",
    "EntityFactoryAware",
    "EventFactoryAware",
    "ExecutorAware",
    "GatewayBotAware",
    "IntentsAware",
    "NetworkSettingsAware",
    "RESTAware",
    "RESTBotAware",
    "Runnable",
    "InteractionServerAware",
    "ShardAware",
    "VoiceAware",
)

import typing

from hikari import presences
from hikari import undefined
from hikari.internal import fast_protocol

if typing.TYPE_CHECKING:
    import datetime
    from concurrent import futures

    from hikari import channels
    from hikari import guilds
    from hikari import intents as intents_
    from hikari import snowflakes
    from hikari import users as users_
    from hikari.api import cache as cache_
    from hikari.api import config
    from hikari.api import entity_factory as entity_factory_
    from hikari.api import event_factory as event_factory_
    from hikari.api import event_manager as event_manager_
    from hikari.api import interaction_server as interaction_server_
    from hikari.api import rest as rest_
    from hikari.api import shard as gateway_shard
    from hikari.api import voice as voice_


@typing.runtime_checkable
class NetworkSettingsAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for any component aware of network settings."""

    __slots__: typing.Sequence[str] = ()

    @property
    def http_settings(self) -> config.HTTPSettings:
        """Return the HTTP settings in use by this component.

        Returns
        -------
        hikari.config.HTTPSettings
            The HTTP settings in use.
        """
        raise NotImplementedError

    @property
    def proxy_settings(self) -> config.ProxySettings:
        """Return the proxy settings in use by this component.

        Returns
        -------
        hikari.config.ProxySettings
            The proxy settings in use.
        """
        raise NotImplementedError


@typing.runtime_checkable
class EventManagerAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a event manager-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def event_manager(self) -> event_manager_.EventManager:
        """Return the event manager for this object.

        Returns
        -------
        hikari.api.event_manager.EventManager
            The event manager component.
        """
        raise NotImplementedError


@typing.runtime_checkable
class EntityFactoryAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for an entity factory-aware object.

    These components will be able to construct library entities.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def entity_factory(self) -> entity_factory_.EntityFactory:
        """Return the entity factory implementation for this object.

        Returns
        -------
        hikari.api.entity_factory.EntityFactory
            The entity factory component.
        """
        raise NotImplementedError


@typing.runtime_checkable
class ExecutorAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for an executor-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def executor(self) -> typing.Optional[futures.Executor]:
        """Return the executor to use for blocking operations.

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

        Returns
        -------
        typing.Optional[concurrent.futures.Executor]
            The executor to use, or `builtins.None` to use the `asyncio` default
            instead.
        """
        raise NotImplementedError


@typing.runtime_checkable
class EventFactoryAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for an event factory-aware object.

    These components are able to construct library events.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def event_factory(self) -> event_factory_.EventFactory:
        """Return the event factory component.

        Returns
        -------
        hikari.api.event_factory.EventFactory
            The event factory component.
        """
        raise NotImplementedError


@typing.runtime_checkable
class IntentsAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """A component that is aware of the application intents."""

    __slots__: typing.Sequence[str] = ()

    @property
    def intents(self) -> intents_.Intents:
        """Return the intents registered for the application.

        Returns
        -------
        hikari.intents.Intents
            The intents registered on this application.
        """
        raise NotImplementedError


@typing.runtime_checkable
class RESTAware(
    EntityFactoryAware, NetworkSettingsAware, ExecutorAware, fast_protocol.FastProtocolChecking, typing.Protocol
):
    """Structural supertype for a REST-aware object.

    These are able to perform REST API calls.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def rest(self) -> rest_.RESTClient:
        """Return the REST client to use for HTTP requests.

        Returns
        -------
        hikari.api.rest.RESTClient
            The REST client to use.
        """
        raise NotImplementedError


@typing.runtime_checkable
class VoiceAware(fast_protocol.FastProtocolChecking, typing.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.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def voice(self) -> voice_.VoiceComponent:
        """Return the voice connection manager component for this application.

        Returns
        -------
        hikari.api.voice.VoiceComponent
            The voice component for the application.
        """
        raise NotImplementedError


@typing.runtime_checkable
class ShardAware(
    IntentsAware,
    NetworkSettingsAware,
    ExecutorAware,
    VoiceAware,
    fast_protocol.FastProtocolChecking,
    typing.Protocol,
):
    """Structural supertype for a shard-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def heartbeat_latencies(self) -> typing.Mapping[int, float]:
        """Return a mapping of shard ID to heartbeat latency.

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

        Returns
        -------
        typing.Mapping[builtins.int, builtins.float]
            Each shard ID mapped to the corresponding heartbeat latency.
            Each latency is measured in seconds.
        """
        raise NotImplementedError

    @property
    def heartbeat_latency(self) -> float:
        """Return the average heartbeat latency of all started shards.

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

        Returns
        -------
        builtins.float
            The average heartbeat latency of all started shards, or
            `float('nan')` if no shards are started. This is measured
            in seconds.
        """
        raise NotImplementedError

    @property
    def shards(self) -> typing.Mapping[int, gateway_shard.GatewayShard]:
        """Return a 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.

        Returns
        -------
        typing.Mapping[int, hikari.api.shard.GatewayShard]
            The shard mapping.
        """
        raise NotImplementedError

    @property
    def shard_count(self) -> int:
        """Return the 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.

        Returns
        -------
        builtins.int
            The number of shards in the total application.
        """
        raise NotImplementedError

    def get_me(self) -> typing.Optional[users_.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 `builtins.None`.

        Returns
        -------
        typing.Optional[hikari.users.OwnUser]
            The bot user, if known, otherwise `builtins.None`.
        """
        raise NotImplementedError

    async def update_presence(
        self,
        *,
        status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
        idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
        activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
        afk: undefined.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.

        Other Parameters
        ----------------
        idle_since : hikari.undefined.UndefinedNoneOr[datetime.datetime]
            The datetime that the user started being idle. If undefined, this
            will not be changed.
        afk : hikari.undefined.UndefinedOr[builtins.bool]
            If `builtins.True`, the user is marked as AFK. If `builtins.False`,
            the user is marked as being active. If undefined, this will not be
            changed.
        activity : hikari.undefined.UndefinedNoneOr[hikari.presences.Activity]
            The activity to appear to be playing. If undefined, this will not be
            changed.
        status : hikari.undefined.UndefinedOr[hikari.presences.Status]
            The web status to show. If undefined, this will not be changed.

        !!! 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.
        """
        raise NotImplementedError

    async def update_voice_state(
        self,
        guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
        channel: typing.Optional[snowflakes.SnowflakeishOr[channels.GuildVoiceChannel]],
        *,
        self_mute: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
        self_deaf: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
    ) -> None:
        """Update the voice state for this bot in a given guild.

        Parameters
        ----------
        guild : hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]
            The guild or guild ID to update the voice state for.
        channel : typing.Optional[hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildVoiceChannel]]
            The channel or channel ID to update the voice state for. If `builtins.None`
            then the bot will leave the voice channel that it is in for the
            given guild.
        self_mute : builtins.bool
            If specified and `builtins.True`, the bot will mute itself in that
            voice channel. If `builtins.False`, then it will unmute itself.
        self_deaf : builtins.bool
            If specified and `builtins.True`, the bot will deafen itself in that
            voice channel. If `builtins.False`, then it will undeafen itself.

        Raises
        ------
        builtins.RuntimeError
            If the guild passed isn't covered by any of the shards in this sharded
            client.
        """

    async def request_guild_members(
        self,
        guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
        *,
        include_presences: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
        query: str = "",
        limit: int = 0,
        users: undefined.UndefinedOr[snowflakes.SnowflakeishSequence[users_.User]] = undefined.UNDEFINED,
        nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
    ) -> None:
        """Request for a guild chunk.

        Parameters
        ----------
        guild: hikari.guilds.Guild
            The guild to request chunk for.

        Other Parameters
        ----------------
        include_presences: hikari.undefined.UndefinedOr[builtins.bool]
            If provided, whether to request presences.
        query: builtins.str
            If not `""`, request the members which username starts with the string.
        limit: builtins.int
            Maximum number of members to send matching the query.
        users: hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.users.User]]
            If provided, the users to request for.
        nonce: hikari.undefined.UndefinedOr[builtins.str]
            If provided, the nonce to be sent with guild chunks.

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

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


@typing.runtime_checkable
class InteractionServerAware(RESTAware, EntityFactoryAware, fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a interaction REST server-aware object."""

    __slots__: typing.Sequence[str] = ()

    @property
    def interaction_server(self) -> interaction_server_.InteractionServer:
        """Interaction server this app is bound to.

        Returns
        -------
        hikari.api.interaction_server.InteractionServer
            The interaction server this app is bound to.
        """
        raise NotImplementedError


@typing.runtime_checkable
class CacheAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a cache-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def cache(self) -> cache_.Cache:
        """Return the immutable cache implementation for this object.

        Returns
        -------
        hikari.api.cache.Cache
            The cache component for this object.
        """
        raise NotImplementedError


@typing.runtime_checkable
class Runnable(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural super-type for an application which can be run independently."""

    __slots__: typing.Sequence[str] = ()

    @property
    def is_alive(self) -> bool:
        """Check whether the application is running or not.

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

        Returns
        -------
        builtins.bool
            Whether the bot is running or not.
        """
        raise NotImplementedError

    async def close(self) -> None:
        """Kill the application by shutting all components down."""

    async def join(self) -> 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.
        """
        raise NotImplementedError

    def run(self) -> None:
        """Start the application and block until it's finished running."""
        raise NotImplementedError

    async def start(self) -> None:
        """Start the application and then return."""
        raise NotImplementedError


@typing.runtime_checkable
class GatewayBotAware(
    RESTAware,
    Runnable,
    ShardAware,
    EventFactoryAware,
    EventManagerAware,
    CacheAware,
    fast_protocol.FastProtocolChecking,
    typing.Protocol,
):
    """Structural supertype for a component that has all the gateway components."""

    __slots__: typing.Sequence[str] = ()


@typing.runtime_checkable
class RESTBotAware(InteractionServerAware, Runnable, fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a component that has all the RESTful components."""

    __slots__: typing.Sequence[str] = ()

Classes

trait CacheAware

class CacheAware: ...

Structural supertype for a cache-aware object.

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

Expand source code
Browse git 
class CacheAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a cache-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def cache(self) -> cache_.Cache:
        """Return the immutable cache implementation for this object.

        Returns
        -------
        hikari.api.cache.Cache
            The cache component for this object.
        """
        raise NotImplementedError
Subclasses
trait GatewayBotAware

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

Method resolution order
trait CacheAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property cache : cache_.Cache

Return the immutable cache implementation for this object.

Returns

Cache
The cache component for this object.

trait EntityFactoryAware

class EntityFactoryAware: ...

Structural supertype for an entity factory-aware object.

These components will be able to construct library entities.

Expand source code
Browse git 
class EntityFactoryAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for an entity factory-aware object.

    These components will be able to construct library entities.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def entity_factory(self) -> entity_factory_.EntityFactory:
        """Return the entity factory implementation for this object.

        Returns
        -------
        hikari.api.entity_factory.EntityFactory
            The entity factory component.
        """
        raise NotImplementedError
Subclasses
trait InteractionServerAware

Structural supertype for a interaction REST server-aware object.

trait RESTAware

Structural supertype for a REST-aware object …

Method resolution order
trait EntityFactoryAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property entity_factory : entity_factory_.EntityFactory

Return the entity factory implementation for this object.

Returns

EntityFactory
The entity factory component.

trait EventFactoryAware

class EventFactoryAware: ...

Structural supertype for an event factory-aware object.

These components are able to construct library events.

Expand source code
Browse git 
class EventFactoryAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for an event factory-aware object.

    These components are able to construct library events.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def event_factory(self) -> event_factory_.EventFactory:
        """Return the event factory component.

        Returns
        -------
        hikari.api.event_factory.EventFactory
            The event factory component.
        """
        raise NotImplementedError
Subclasses
trait GatewayBotAware

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

Method resolution order
trait EventFactoryAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property event_factory : event_factory_.EventFactory

Return the event factory component.

Returns

EventFactory
The event factory component.

trait EventManagerAware

class EventManagerAware: ...

Structural supertype for a event manager-aware object.

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

Expand source code
Browse git 
class EventManagerAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a event manager-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def event_manager(self) -> event_manager_.EventManager:
        """Return the event manager for this object.

        Returns
        -------
        hikari.api.event_manager.EventManager
            The event manager component.
        """
        raise NotImplementedError
Subclasses
trait GatewayBotAware

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

Method resolution order
trait EventManagerAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property event_manager : event_manager_.EventManager

Return the event manager for this object.

Returns

EventManager
The event manager component.

trait ExecutorAware

class ExecutorAware: ...

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.

Expand source code
Browse git 
class ExecutorAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for an executor-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def executor(self) -> typing.Optional[futures.Executor]:
        """Return the executor to use for blocking operations.

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

        Returns
        -------
        typing.Optional[concurrent.futures.Executor]
            The executor to use, or `builtins.None` to use the `asyncio` default
            instead.
        """
        raise NotImplementedError
Subclasses
class RESTApp

The base for a HTTP-only Discord application …

trait RESTAware

Structural supertype for a REST-aware object …

trait ShardAware

Structural supertype for a shard-aware object …

Method resolution order
trait ExecutorAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property executor : Optional[futures.Executor]

Return the executor to use for blocking operations.

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

Returns

Optional[concurrent.futures.Executor]
The executor to use, or None to use the asyncio default instead.

trait GatewayBotAware

class GatewayBotAware: ...

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

Expand source code
Browse git 
class GatewayBotAware(
    RESTAware,
    Runnable,
    ShardAware,
    EventFactoryAware,
    EventManagerAware,
    CacheAware,
    fast_protocol.FastProtocolChecking,
    typing.Protocol,
):
    """Structural supertype for a component that has all the gateway components."""

    __slots__: typing.Sequence[str] = ()
Subclasses
class GatewayBot

Basic auto-sharding bot implementation …

Method resolution order
trait GatewayBotAware
That's this class!
trait RESTAware

Structural supertype for a REST-aware object …

trait EntityFactoryAware

Structural supertype for an entity factory-aware object …

trait Runnable

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

trait ShardAware

Structural supertype for a shard-aware object …

trait IntentsAware

A component that is aware of the application intents.

trait NetworkSettingsAware

Structural supertype for any component aware of network settings.

trait ExecutorAware

Structural supertype for an executor-aware object …

trait VoiceAware

Structural supertype for a voice-aware object …

trait EventFactoryAware

Structural supertype for an event factory-aware object …

trait EventManagerAware

Structural supertype for a event manager-aware object …

trait CacheAware

Structural supertype for a cache-aware object …

trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property cache : cache_.Cache

Return the immutable cache implementation for this object.

Returns

Cache
The cache component for this object.
property entity_factory : entity_factory_.EntityFactory

Return the entity factory implementation for this object.

Returns

EntityFactory
The entity factory component.
property event_factory : event_factory_.EventFactory

Return the event factory component.

Returns

EventFactory
The event factory component.
property event_manager : event_manager_.EventManager

Return the event manager for this object.

Returns

EventManager
The event manager component.
property executor : Optional[futures.Executor]

Return the executor to use for blocking operations.

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

Returns

Optional[concurrent.futures.Executor]
The executor to use, or None to use the asyncio default instead.
property heartbeat_latencies : Mapping[int, float]

Return a mapping of shard ID to heartbeat latency.

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

Returns

Mapping[int, float]
Each shard ID mapped to the corresponding heartbeat latency. Each latency is measured in seconds.
property heartbeat_latency : float

Return the average heartbeat latency of all started shards.

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

Returns

float
The average heartbeat latency of all started shards, or float('nan') if no shards are started. This is measured in seconds.
property http_settings : config.HTTPSettings

Return the HTTP settings in use by this component.

Returns

hikari.config.HTTPSettings
The HTTP settings in use.
property intents : intents_.Intents

Return the intents registered for the application.

Returns

Intents
The intents registered on this application.
property is_alive : bool

Check whether the application is running or not.

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

Returns

bool
Whether the bot is running or not.
property proxy_settings : config.ProxySettings

Return the proxy settings in use by this component.

Returns

hikari.config.ProxySettings
The proxy settings in use.
property rest : rest_.RESTClient

Return the REST client to use for HTTP requests.

Returns

RESTClient
The REST client to use.
property shard_count : int

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

Returns

int
The number of shards in the total application.
property shards : Mapping[int, gateway_shard.GatewayShard]

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

Returns

Mapping[int, GatewayShard]
The shard mapping.
property voice : voice_.VoiceComponent

Return the voice connection manager component for this application.

Returns

VoiceComponent
The voice component for the application.
Methods
async def close() -> None: ...

Inherited from: Runnable.close

Kill the application by shutting all components down.

def get_me() -> Optional[users_.OwnUser]: ...

Inherited from: ShardAware.get_me

Return the bot user, if known.

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

Until then, this may or may not be None.

Returns

Optional[OwnUser]
The bot user, if known, otherwise None.
async def join() -> None: ...

Inherited from: Runnable.join

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.

async def request_guild_members(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    *,
    include_presences: undefined.UndefinedOr[bool] = UNDEFINED,
    query: str = '',
    limit: int = 0,
    users: undefined.UndefinedOr[snowflakes.SnowflakeishSequence[users_.User]] = UNDEFINED,
    nonce: undefined.UndefinedOr[str] = UNDEFINED,
) -> None: ...

Inherited from: ShardAware.request_guild_members

Request for a guild chunk.

Parameters

guild : Guild
The guild to request chunk for.

Other Parameters

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

Note

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

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.
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.
def run() -> None: ...

Inherited from: Runnable.run

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

async def start() -> None: ...

Inherited from: Runnable.start

Start the application and then return.

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

Inherited from: ShardAware.update_presence

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.

Other Parameters

idle_since : UndefinedNoneOr[datetime.datetime]
The datetime that the user started being idle. If undefined, this will not be changed.
afk : 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.
activity : UndefinedNoneOr[Activity]
The activity to appear to be playing. If undefined, this will not be changed.
status : UndefinedOr[Status]
The web status to show. If undefined, this will not be changed.

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 update_presence on that shard.

This method is simply a facade to make performing this in bulk simpler.

async def update_voice_state(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    channel: Optional[snowflakes.SnowflakeishOr[channels.GuildVoiceChannel]],
    *,
    self_mute: undefined.UndefinedOr[bool] = UNDEFINED,
    self_deaf: undefined.UndefinedOr[bool] = UNDEFINED,
) -> None: ...

Inherited from: ShardAware.update_voice_state

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

Parameters

guild : SnowflakeishOr[PartialGuild]
The guild or guild ID to update the voice state for.
channel : Optional[SnowflakeishOr[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_mute : bool
If specified and True, the bot will mute itself in that voice channel. If False, then it will unmute itself.
self_deaf : bool
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.

trait IntentsAware

class IntentsAware: ...

A component that is aware of the application intents.

Expand source code
Browse git 
class IntentsAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """A component that is aware of the application intents."""

    __slots__: typing.Sequence[str] = ()

    @property
    def intents(self) -> intents_.Intents:
        """Return the intents registered for the application.

        Returns
        -------
        hikari.intents.Intents
            The intents registered on this application.
        """
        raise NotImplementedError
Subclasses
trait ShardAware

Structural supertype for a shard-aware object …

Method resolution order
trait IntentsAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property intents : intents_.Intents

Return the intents registered for the application.

Returns

Intents
The intents registered on this application.

trait InteractionServerAware

class InteractionServerAware: ...

Structural supertype for a interaction REST server-aware object.

Expand source code
Browse git 
class InteractionServerAware(RESTAware, EntityFactoryAware, fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a interaction REST server-aware object."""

    __slots__: typing.Sequence[str] = ()

    @property
    def interaction_server(self) -> interaction_server_.InteractionServer:
        """Interaction server this app is bound to.

        Returns
        -------
        hikari.api.interaction_server.InteractionServer
            The interaction server this app is bound to.
        """
        raise NotImplementedError
Subclasses
trait RESTBotAware

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

Method resolution order
trait InteractionServerAware
That's this class!
trait RESTAware

Structural supertype for a REST-aware object …

trait EntityFactoryAware

Structural supertype for an entity factory-aware object …

trait NetworkSettingsAware

Structural supertype for any component aware of network settings.

trait ExecutorAware

Structural supertype for an executor-aware object …

trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property entity_factory : entity_factory_.EntityFactory

Return the entity factory implementation for this object.

Returns

EntityFactory
The entity factory component.
property executor : Optional[futures.Executor]

Return the executor to use for blocking operations.

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

Returns

Optional[concurrent.futures.Executor]
The executor to use, or None to use the asyncio default instead.
property http_settings : config.HTTPSettings

Return the HTTP settings in use by this component.

Returns

hikari.config.HTTPSettings
The HTTP settings in use.
property interaction_server : interaction_server_.InteractionServer

Interaction server this app is bound to.

Returns

InteractionServer
The interaction server this app is bound to.
property proxy_settings : config.ProxySettings

Return the proxy settings in use by this component.

Returns

hikari.config.ProxySettings
The proxy settings in use.
property rest : rest_.RESTClient

Return the REST client to use for HTTP requests.

Returns

RESTClient
The REST client to use.

trait NetworkSettingsAware

class NetworkSettingsAware: ...

Structural supertype for any component aware of network settings.

Expand source code
Browse git 
class NetworkSettingsAware(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for any component aware of network settings."""

    __slots__: typing.Sequence[str] = ()

    @property
    def http_settings(self) -> config.HTTPSettings:
        """Return the HTTP settings in use by this component.

        Returns
        -------
        hikari.config.HTTPSettings
            The HTTP settings in use.
        """
        raise NotImplementedError

    @property
    def proxy_settings(self) -> config.ProxySettings:
        """Return the proxy settings in use by this component.

        Returns
        -------
        hikari.config.ProxySettings
            The proxy settings in use.
        """
        raise NotImplementedError
Subclasses
abstract class RESTClient

Interface for functionality that a REST API implementation provides.

trait RESTAware

Structural supertype for a REST-aware object …

trait ShardAware

Structural supertype for a shard-aware object …

Method resolution order
trait NetworkSettingsAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property http_settings : config.HTTPSettings

Return the HTTP settings in use by this component.

Returns

hikari.config.HTTPSettings
The HTTP settings in use.
property proxy_settings : config.ProxySettings

Return the proxy settings in use by this component.

Returns

hikari.config.ProxySettings
The proxy settings in use.

trait RESTAware

class RESTAware: ...

Structural supertype for a REST-aware object.

These are able to perform REST API calls.

Expand source code
Browse git 
class RESTAware(
    EntityFactoryAware, NetworkSettingsAware, ExecutorAware, fast_protocol.FastProtocolChecking, typing.Protocol
):
    """Structural supertype for a REST-aware object.

    These are able to perform REST API calls.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def rest(self) -> rest_.RESTClient:
        """Return the REST client to use for HTTP requests.

        Returns
        -------
        hikari.api.rest.RESTClient
            The REST client to use.
        """
        raise NotImplementedError
Subclasses
trait GatewayBotAware

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

trait InteractionServerAware

Structural supertype for a interaction REST server-aware object.

Method resolution order
trait RESTAware
That's this class!
trait EntityFactoryAware

Structural supertype for an entity factory-aware object …

trait NetworkSettingsAware

Structural supertype for any component aware of network settings.

trait ExecutorAware

Structural supertype for an executor-aware object …

trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property entity_factory : entity_factory_.EntityFactory

Return the entity factory implementation for this object.

Returns

EntityFactory
The entity factory component.
property executor : Optional[futures.Executor]

Return the executor to use for blocking operations.

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

Returns

Optional[concurrent.futures.Executor]
The executor to use, or None to use the asyncio default instead.
property http_settings : config.HTTPSettings

Return the HTTP settings in use by this component.

Returns

hikari.config.HTTPSettings
The HTTP settings in use.
property proxy_settings : config.ProxySettings

Return the proxy settings in use by this component.

Returns

hikari.config.ProxySettings
The proxy settings in use.
property rest : rest_.RESTClient

Return the REST client to use for HTTP requests.

Returns

RESTClient
The REST client to use.

trait RESTBotAware

class RESTBotAware: ...

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

Expand source code
Browse git 
class RESTBotAware(InteractionServerAware, Runnable, fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural supertype for a component that has all the RESTful components."""

    __slots__: typing.Sequence[str] = ()
Subclasses
class RESTBot

Basic implementation of an interaction based REST-only bot …

Method resolution order
trait RESTBotAware
That's this class!
trait InteractionServerAware

Structural supertype for a interaction REST server-aware object.

trait RESTAware

Structural supertype for a REST-aware object …

trait EntityFactoryAware

Structural supertype for an entity factory-aware object …

trait NetworkSettingsAware

Structural supertype for any component aware of network settings.

trait ExecutorAware

Structural supertype for an executor-aware object …

trait Runnable

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

trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property entity_factory : entity_factory_.EntityFactory

Return the entity factory implementation for this object.

Returns

EntityFactory
The entity factory component.
property executor : Optional[futures.Executor]

Return the executor to use for blocking operations.

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

Returns

Optional[concurrent.futures.Executor]
The executor to use, or None to use the asyncio default instead.
property http_settings : config.HTTPSettings

Return the HTTP settings in use by this component.

Returns

hikari.config.HTTPSettings
The HTTP settings in use.
property interaction_server : interaction_server_.InteractionServer

Interaction server this app is bound to.

Returns

InteractionServer
The interaction server this app is bound to.
property is_alive : bool

Check whether the application is running or not.

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

Returns

bool
Whether the bot is running or not.
property proxy_settings : config.ProxySettings

Return the proxy settings in use by this component.

Returns

hikari.config.ProxySettings
The proxy settings in use.
property rest : rest_.RESTClient

Return the REST client to use for HTTP requests.

Returns

RESTClient
The REST client to use.
Methods
async def close() -> None: ...

Inherited from: Runnable.close

Kill the application by shutting all components down.

async def join() -> None: ...

Inherited from: Runnable.join

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.

def run() -> None: ...

Inherited from: Runnable.run

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

async def start() -> None: ...

Inherited from: Runnable.start

Start the application and then return.

trait Runnable

class Runnable: ...

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

Expand source code
Browse git 
class Runnable(fast_protocol.FastProtocolChecking, typing.Protocol):
    """Structural super-type for an application which can be run independently."""

    __slots__: typing.Sequence[str] = ()

    @property
    def is_alive(self) -> bool:
        """Check whether the application is running or not.

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

        Returns
        -------
        builtins.bool
            Whether the bot is running or not.
        """
        raise NotImplementedError

    async def close(self) -> None:
        """Kill the application by shutting all components down."""

    async def join(self) -> 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.
        """
        raise NotImplementedError

    def run(self) -> None:
        """Start the application and block until it's finished running."""
        raise NotImplementedError

    async def start(self) -> None:
        """Start the application and then return."""
        raise NotImplementedError
Subclasses
trait GatewayBotAware

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

trait RESTBotAware

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

Method resolution order
trait Runnable
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property is_alive : bool

Check whether the application is running or not.

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

Returns

bool
Whether the bot is running or not.
Methods
async def close() -> None: ...

Kill the application by shutting all components down.

Expand source code
Browse git 
async def close(self) -> None:
    """Kill the application by shutting all components down."""
async def 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.

Expand source code
Browse git 
async def join(self) -> 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.
    """
    raise NotImplementedError
def run() -> None: ...

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

Expand source code
Browse git 
def run(self) -> None:
    """Start the application and block until it's finished running."""
    raise NotImplementedError
async def start() -> None: ...

Start the application and then return.

Expand source code
Browse git 
async def start(self) -> None:
    """Start the application and then return."""
    raise NotImplementedError

trait ShardAware

class ShardAware: ...

Structural supertype for a shard-aware object.

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

Expand source code
Browse git 
class ShardAware(
    IntentsAware,
    NetworkSettingsAware,
    ExecutorAware,
    VoiceAware,
    fast_protocol.FastProtocolChecking,
    typing.Protocol,
):
    """Structural supertype for a shard-aware object.

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

    __slots__: typing.Sequence[str] = ()

    @property
    def heartbeat_latencies(self) -> typing.Mapping[int, float]:
        """Return a mapping of shard ID to heartbeat latency.

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

        Returns
        -------
        typing.Mapping[builtins.int, builtins.float]
            Each shard ID mapped to the corresponding heartbeat latency.
            Each latency is measured in seconds.
        """
        raise NotImplementedError

    @property
    def heartbeat_latency(self) -> float:
        """Return the average heartbeat latency of all started shards.

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

        Returns
        -------
        builtins.float
            The average heartbeat latency of all started shards, or
            `float('nan')` if no shards are started. This is measured
            in seconds.
        """
        raise NotImplementedError

    @property
    def shards(self) -> typing.Mapping[int, gateway_shard.GatewayShard]:
        """Return a 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.

        Returns
        -------
        typing.Mapping[int, hikari.api.shard.GatewayShard]
            The shard mapping.
        """
        raise NotImplementedError

    @property
    def shard_count(self) -> int:
        """Return the 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.

        Returns
        -------
        builtins.int
            The number of shards in the total application.
        """
        raise NotImplementedError

    def get_me(self) -> typing.Optional[users_.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 `builtins.None`.

        Returns
        -------
        typing.Optional[hikari.users.OwnUser]
            The bot user, if known, otherwise `builtins.None`.
        """
        raise NotImplementedError

    async def update_presence(
        self,
        *,
        status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
        idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
        activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
        afk: undefined.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.

        Other Parameters
        ----------------
        idle_since : hikari.undefined.UndefinedNoneOr[datetime.datetime]
            The datetime that the user started being idle. If undefined, this
            will not be changed.
        afk : hikari.undefined.UndefinedOr[builtins.bool]
            If `builtins.True`, the user is marked as AFK. If `builtins.False`,
            the user is marked as being active. If undefined, this will not be
            changed.
        activity : hikari.undefined.UndefinedNoneOr[hikari.presences.Activity]
            The activity to appear to be playing. If undefined, this will not be
            changed.
        status : hikari.undefined.UndefinedOr[hikari.presences.Status]
            The web status to show. If undefined, this will not be changed.

        !!! 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.
        """
        raise NotImplementedError

    async def update_voice_state(
        self,
        guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
        channel: typing.Optional[snowflakes.SnowflakeishOr[channels.GuildVoiceChannel]],
        *,
        self_mute: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
        self_deaf: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
    ) -> None:
        """Update the voice state for this bot in a given guild.

        Parameters
        ----------
        guild : hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]
            The guild or guild ID to update the voice state for.
        channel : typing.Optional[hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildVoiceChannel]]
            The channel or channel ID to update the voice state for. If `builtins.None`
            then the bot will leave the voice channel that it is in for the
            given guild.
        self_mute : builtins.bool
            If specified and `builtins.True`, the bot will mute itself in that
            voice channel. If `builtins.False`, then it will unmute itself.
        self_deaf : builtins.bool
            If specified and `builtins.True`, the bot will deafen itself in that
            voice channel. If `builtins.False`, then it will undeafen itself.

        Raises
        ------
        builtins.RuntimeError
            If the guild passed isn't covered by any of the shards in this sharded
            client.
        """

    async def request_guild_members(
        self,
        guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
        *,
        include_presences: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
        query: str = "",
        limit: int = 0,
        users: undefined.UndefinedOr[snowflakes.SnowflakeishSequence[users_.User]] = undefined.UNDEFINED,
        nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
    ) -> None:
        """Request for a guild chunk.

        Parameters
        ----------
        guild: hikari.guilds.Guild
            The guild to request chunk for.

        Other Parameters
        ----------------
        include_presences: hikari.undefined.UndefinedOr[builtins.bool]
            If provided, whether to request presences.
        query: builtins.str
            If not `""`, request the members which username starts with the string.
        limit: builtins.int
            Maximum number of members to send matching the query.
        users: hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.users.User]]
            If provided, the users to request for.
        nonce: hikari.undefined.UndefinedOr[builtins.str]
            If provided, the nonce to be sent with guild chunks.

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

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

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

Method resolution order
trait ShardAware
That's this class!
trait IntentsAware

A component that is aware of the application intents.

trait NetworkSettingsAware

Structural supertype for any component aware of network settings.

trait ExecutorAware

Structural supertype for an executor-aware object …

trait VoiceAware

Structural supertype for a voice-aware object …

trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property executor : Optional[futures.Executor]

Return the executor to use for blocking operations.

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

Returns

Optional[concurrent.futures.Executor]
The executor to use, or None to use the asyncio default instead.
property heartbeat_latencies : Mapping[int, float]

Return a mapping of shard ID to heartbeat latency.

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

Returns

Mapping[int, float]
Each shard ID mapped to the corresponding heartbeat latency. Each latency is measured in seconds.
property heartbeat_latency : float

Return the average heartbeat latency of all started shards.

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

Returns

float
The average heartbeat latency of all started shards, or float('nan') if no shards are started. This is measured in seconds.
property http_settings : config.HTTPSettings

Return the HTTP settings in use by this component.

Returns

hikari.config.HTTPSettings
The HTTP settings in use.
property intents : intents_.Intents

Return the intents registered for the application.

Returns

Intents
The intents registered on this application.
property proxy_settings : config.ProxySettings

Return the proxy settings in use by this component.

Returns

hikari.config.ProxySettings
The proxy settings in use.
property shard_count : int

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

Returns

int
The number of shards in the total application.
property shards : Mapping[int, gateway_shard.GatewayShard]

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

Returns

Mapping[int, GatewayShard]
The shard mapping.
property voice : voice_.VoiceComponent

Return the voice connection manager component for this application.

Returns

VoiceComponent
The voice component for the application.
Methods
def get_me() -> Optional[users_.OwnUser]: ...

Return the bot user, if known.

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

Until then, this may or may not be None.

Returns

Optional[OwnUser]
The bot user, if known, otherwise None.
Expand source code
Browse git 
def get_me(self) -> typing.Optional[users_.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 `builtins.None`.

    Returns
    -------
    typing.Optional[hikari.users.OwnUser]
        The bot user, if known, otherwise `builtins.None`.
    """
    raise NotImplementedError
async def request_guild_members(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    *,
    include_presences: undefined.UndefinedOr[bool] = UNDEFINED,
    query: str = '',
    limit: int = 0,
    users: undefined.UndefinedOr[snowflakes.SnowflakeishSequence[users_.User]] = UNDEFINED,
    nonce: undefined.UndefinedOr[str] = UNDEFINED,
) -> None: ...

Request for a guild chunk.

Parameters

guild : Guild
The guild to request chunk for.

Other Parameters

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

Note

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

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.
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.
Expand source code
Browse git 
async def request_guild_members(
    self,
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    *,
    include_presences: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
    query: str = "",
    limit: int = 0,
    users: undefined.UndefinedOr[snowflakes.SnowflakeishSequence[users_.User]] = undefined.UNDEFINED,
    nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
) -> None:
    """Request for a guild chunk.

    Parameters
    ----------
    guild: hikari.guilds.Guild
        The guild to request chunk for.

    Other Parameters
    ----------------
    include_presences: hikari.undefined.UndefinedOr[builtins.bool]
        If provided, whether to request presences.
    query: builtins.str
        If not `""`, request the members which username starts with the string.
    limit: builtins.int
        Maximum number of members to send matching the query.
    users: hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishSequence[hikari.users.User]]
        If provided, the users to request for.
    nonce: hikari.undefined.UndefinedOr[builtins.str]
        If provided, the nonce to be sent with guild chunks.

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

    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`.
    builtins.RuntimeError
        If the guild passed isn't covered by any of the shards in this sharded
        client.
    """
async def update_presence(
    *,
    status: undefined.UndefinedOr[presences.Status] = UNDEFINED,
    idle_since: undefined.UndefinedNoneOr[datetime.datetime] = UNDEFINED,
    activity: undefined.UndefinedNoneOr[presences.Activity] = UNDEFINED,
    afk: undefined.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.

Other Parameters

idle_since : UndefinedNoneOr[datetime.datetime]
The datetime that the user started being idle. If undefined, this will not be changed.
afk : 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.
activity : UndefinedNoneOr[Activity]
The activity to appear to be playing. If undefined, this will not be changed.
status : UndefinedOr[Status]
The web status to show. If undefined, this will not be changed.

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 update_presence on that shard.

This method is simply a facade to make performing this in bulk simpler.

Expand source code
Browse git 
async def update_presence(
    self,
    *,
    status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
    idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
    activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
    afk: undefined.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.

    Other Parameters
    ----------------
    idle_since : hikari.undefined.UndefinedNoneOr[datetime.datetime]
        The datetime that the user started being idle. If undefined, this
        will not be changed.
    afk : hikari.undefined.UndefinedOr[builtins.bool]
        If `builtins.True`, the user is marked as AFK. If `builtins.False`,
        the user is marked as being active. If undefined, this will not be
        changed.
    activity : hikari.undefined.UndefinedNoneOr[hikari.presences.Activity]
        The activity to appear to be playing. If undefined, this will not be
        changed.
    status : hikari.undefined.UndefinedOr[hikari.presences.Status]
        The web status to show. If undefined, this will not be changed.

    !!! 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.
    """
    raise NotImplementedError
async def update_voice_state(
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    channel: Optional[snowflakes.SnowflakeishOr[channels.GuildVoiceChannel]],
    *,
    self_mute: undefined.UndefinedOr[bool] = UNDEFINED,
    self_deaf: undefined.UndefinedOr[bool] = UNDEFINED,
) -> None: ...

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

Parameters

guild : SnowflakeishOr[PartialGuild]
The guild or guild ID to update the voice state for.
channel : Optional[SnowflakeishOr[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_mute : bool
If specified and True, the bot will mute itself in that voice channel. If False, then it will unmute itself.
self_deaf : bool
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.
Expand source code
Browse git 
async def update_voice_state(
    self,
    guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
    channel: typing.Optional[snowflakes.SnowflakeishOr[channels.GuildVoiceChannel]],
    *,
    self_mute: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
    self_deaf: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
) -> None:
    """Update the voice state for this bot in a given guild.

    Parameters
    ----------
    guild : hikari.snowflakes.SnowflakeishOr[hikari.guilds.PartialGuild]
        The guild or guild ID to update the voice state for.
    channel : typing.Optional[hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildVoiceChannel]]
        The channel or channel ID to update the voice state for. If `builtins.None`
        then the bot will leave the voice channel that it is in for the
        given guild.
    self_mute : builtins.bool
        If specified and `builtins.True`, the bot will mute itself in that
        voice channel. If `builtins.False`, then it will unmute itself.
    self_deaf : builtins.bool
        If specified and `builtins.True`, the bot will deafen itself in that
        voice channel. If `builtins.False`, then it will undeafen itself.

    Raises
    ------
    builtins.RuntimeError
        If the guild passed isn't covered by any of the shards in this sharded
        client.
    """

trait VoiceAware

class VoiceAware: ...

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.

Expand source code
Browse git 
class VoiceAware(fast_protocol.FastProtocolChecking, typing.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.
    """

    __slots__: typing.Sequence[str] = ()

    @property
    def voice(self) -> voice_.VoiceComponent:
        """Return the voice connection manager component for this application.

        Returns
        -------
        hikari.api.voice.VoiceComponent
            The voice component for the application.
        """
        raise NotImplementedError
Subclasses
trait ShardAware

Structural supertype for a shard-aware object …

Method resolution order
trait VoiceAware
That's this class!
trait FastProtocolChecking

An extension to make protocols with faster instance checks …

extern class Protocol

Base class for protocol classes …

extern class Generic

Abstract base class for generic types …

Variables and properties
property voice : voice_.VoiceComponent

Return the voice connection manager component for this application.

Returns

VoiceComponent
The voice component for the application.