Skip to content

API Refernecce#

System for managing hikari shards across processes/systems.

Bot #

Bases: GatewayBotAware

Bot implementation which is managed by an Orchestrator server.

__init__ #

__init__(orchestrator_address, token, /, *, cache_settings=None, ca_cert=None, http_settings=None, intents=None, proxy_settings=None, rest_url=hikari.urls.REST_API_URL, global_shard_count=None, local_shard_count=1)

Initialise an orchestrator Bot.

Parameters:

  • orchestrator_address (str) –

    Address the orchestrator server is hosted at.

  • token (str) –

    Discord bot token to use.

  • cache_settings (CacheSettings | None, default: None ) –

    The cache settings to use.

  • ca_cert (bytes | None, default: None ) –

    Certificate authority certificate used by the orchestrator server for TLS SSL.

  • http_settings (HTTPSettings | None, default: None ) –

    Configuration to use for the REST client.

  • proxy_settings (ProxySettings | None, default: None ) –

    Custom proxy settings to use with network-layer logic in your application to get through an HTTP-proxy.

  • rest_url (str, default: REST_API_URL ) –

    Base URl to use for requests made by the REST client.

  • local_shard_count (int, default: 1 ) –

    Amount of shards this bot should spawn locally.

Client #

Client for interacting with an orchestrator server instance.

remote_shards property #

remote_shards

Mapping of shard IDs to shard objects.

These shard objects can be used to remotely monitor and control shards and will only be populated while the client is active.

__init__ #

__init__(token, orchestrator_address, /, *, ca_cert=None)

Initialise an orchestrator client.

Parameters:

  • token (str) –

    Discord token for the bot that's being orchestrated.

  • orchestrator_address (str) –

    Address the orchestrator server is being hosted at.

  • ca_cert (bytes | None, default: None ) –

    The certificate authority being used by the server for TLS SSL.

fetch_all_states async #

fetch_all_states()

Fetch the states of all of the bot's shards.

fetch_config async #

fetch_config()

Fetch the bot config.

recommended_shard async #

recommended_shard(make_shard)

Acquire the next shard recommended by the server.

request_guild_members async #

request_guild_members(guild, *, include_presences=hikari.UNDEFINED, query='', limit=0, users=hikari.UNDEFINED, nonce=hikari.UNDEFINED)

Request for a guild chunk.

The received guild chunks will be sent to the shard the guild is in, not necessarily the current shard.

Note

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

Parameters:

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.

start async #

start()

Start the client by connecting to the orchestrator.

stop async #

stop()

Stop the orchestrator client.

update_presence async #

update_presence(*, idle_since=hikari.UNDEFINED, afk=hikari.UNDEFINED, activity=hikari.UNDEFINED, status=hikari.UNDEFINED)

Update the presence of every shard in this bot.

This state will be remembered between restarts.

Parameters:

  • idle_since (UndefinedNoneOr[datetime], default: UNDEFINED ) –

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

  • afk (UndefinedOr[bool], default: UNDEFINED ) –

    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], default: UNDEFINED ) –

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

  • status (UndefinedOr[Status], default: UNDEFINED ) –

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

update_voice_state async #

update_voice_state(guild, channel, *, self_mute=hikari.UNDEFINED, self_deaf=hikari.UNDEFINED)

Update the voice state in a given guild.

Parameters:

  • guild (SnowflakeishOr[PartialGuild]) –

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

  • channel (SnowflakeishOr[GuildVoiceChannel] | None) –

    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 (UndefinedOr[bool], default: UNDEFINED ) –

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

  • self_deaf (UndefinedOr[bool], default: UNDEFINED ) –

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

run_server #

run_server(token, address, /, *, intents=hikari.Intents.ALL_UNPRIVILEGED, ca_cert=None, private_key=None, shard_count=None)

Run an Orchestrator server instance.

Parameters:

  • token (str) –

    Discord token of the bot this orchestrator serve is managing.

  • address (str) –

    The address to host the server at.

    This defaults to TCP if no scheme is included and more information on the supported schemes can be found here.

  • intents (Intents | int, default: ALL_UNPRIVILEGED ) –

    The Discord gateway intents this bot should run with.

  • ca_cert (bytes | None, default: None ) –

    Bytes of the unencrypted PEM certificate authority this should use for TLS SSL encryption.

    private_key must also be passed when this is provided.

  • private_key (bytes | None, default: None ) –

    Bytes of the unencrypted private PEM key this server should use for TLS SSL encryption.

    ca_cert must also be passed when this is proivded.

  • shard_count (int | None, default: None ) –

    The amount of shards this bot should be split into.

    If left as None then this defaults to the shard count recommended by Discord.

run_subprocesses #

run_subprocesses(token, /, *, callback=None, shard_count=None, intents=hikari.Intents.ALL_UNPRIVILEGED, subprocess_count=DEFAULT_SUBPROCESS_COUNT)

Run a bot across several procsesses.

Parameters:

  • token (str) –

    Discord token of the bot

  • callback (Callable[[GatewayBotAware], None] | None, default: None ) –

    Callback to call each child bot instance with on startup.

    This is used to setup the bot.

  • shard_count (int | None, default: None ) –

    The amount of shards this bot should be split into.

    If left as None then this defaults to the shard count recommended by Discord.

  • intents (Intents | int, default: ALL_UNPRIVILEGED ) –

    The Discord gateway intents this bot should run with.

  • subprocess_count (int, default: DEFAULT_SUBPROCESS_COUNT ) –

    The amount of subprocesses to spawn.

    If left as undefined then the current system's thread count is used. This will never spawn more subprocesses than shard_count.

spawn_subprocesses async #

spawn_subprocesses(token, /, *, callback=None, shard_count=None, intents=hikari.Intents.ALL_UNPRIVILEGED, subprocess_count=DEFAULT_SUBPROCESS_COUNT)

Asynchronously variant of run_subprocesses.

The returned coroutine will finish once the server has closed.