hikari.impl.special_endpoints

Special endpoint implementations.

You should never need to make any of these objects manually.

AuditLogIterator

AuditLogIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    guild: SnowflakeishOr[PartialGuild],
    before: UndefinedOr[str],
    user: UndefinedOr[SnowflakeishOr[PartialUser]],
    action_type: UndefinedOr[Union["audit_logs.AuditLogEventType", int]],
)

Bases: LazyIterator['audit_logs.AuditLog']

Iterator implementation for an audit log.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

AutocompleteChoiceBuilder

Bases: AutocompleteChoiceBuilder

Standard implementation of hikari.api.special_endpoints.AutocompleteChoiceBuilder.

name property

name: str

The choice's name.

value property

value: Union[int, str, float]

The choice's value.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_name

set_name(name: str) -> Self

Set this choice's name.

RETURNS	DESCRIPTION
AutocompleteChoiceBuilder	The autocomplete choice builder.

set_value

set_value(value: Union[int, float, str]) -> Self

Set this choice's value.

RETURNS	DESCRIPTION
AutocompleteChoiceBuilder	The autocomplete choice builder.

ChannelSelectMenuBuilder

Bases: SelectMenuBuilder, ChannelSelectMenuBuilder

Builder class for channel select menus.

channel_types property

channel_types: Sequence[ChannelType]

The channel types that can be selected in this menu.

custom_id property

custom_id: str

Developer set custom ID used for identifying interactions with this menu.

is_disabled property

is_disabled: bool

Whether the select menu should be marked as disabled.

max_values property

max_values: int

Maximum number of options which can be chosen.

Defaults to 1. Must be greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values and less than or equal to 25.

min_values property

min_values: int

Minimum number of options which must be chosen.

Defaults to 1. Must be less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values and greater than or equal to 0.

placeholder property

placeholder: UndefinedOr[str]

Placeholder text to display when no options are selected.

type property

type: Union[int, ComponentType]

Type of component this builder represents.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_channel_types

set_channel_types(value: Sequence[ChannelType]) -> Self

Set the valid channel types for this menu.

PARAMETER	DESCRIPTION
value	The valid channel types for this menu. TYPE: Sequence[ChannelType]

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_custom_id

set_custom_id(custom_id: str) -> Self

Set the custom ID used for identifying this menu.

PARAMETER	DESCRIPTION
custom_id	Developer set custom ID used for identifying this menu. TYPE: str

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_is_disabled

set_is_disabled(state: bool) -> Self

Set whether this option is disabled.

PARAMETER	DESCRIPTION
state	Whether this option is disabled. TYPE: bool

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_max_values

set_max_values(value: int) -> Self

Set the maximum amount of options which can be selected for this menu.

Note

This defaults to 1 if not set and must be less than or equal to 25 and greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values.

PARAMETER	DESCRIPTION
value	The maximum amount of options which can selected for this menu. TYPE: int

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_min_values

set_min_values(value: int) -> Self

Set the minimum amount of options which need to be selected for this menu.

Note

This defaults to 1 if not set and must be greater than or equal to 0 and less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values.

PARAMETER	DESCRIPTION
value	The minimum amount of options which need to be selected for this menu. TYPE: int

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_placeholder

set_placeholder(value: UndefinedOr[str]) -> Self

Set place-holder text to be shown when no option is selected.

PARAMETER	DESCRIPTION
value	Place-holder text to be displayed when no option is selected. Max 100 characters. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

CommandBuilder

Bases: CommandBuilder

Standard implementation of hikari.api.special_endpoints.CommandBuilder.

default_member_permissions property

default_member_permissions: Union[UndefinedType, Permissions, int]

Member permissions necessary to utilize this command by default.

If 0, then it will be available for all members. Note that this doesn't affect administrators of the guild and overwrites.

id property

id: UndefinedOr[Snowflake]

ID of this command.

is_dm_enabled property

is_dm_enabled: UndefinedOr[bool]

Whether this command is enabled in DMs with the bot.

Only applicable to globally-scoped commands.

is_nsfw property

is_nsfw: UndefinedOr[bool]

Whether this command age-restricted.

name property

name: str

Name to set for this command.

Warning

This should match the regex ^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$ in Unicode mode and must be lowercase.

name_localizations property

name_localizations: Mapping[Union[Locale, str], str]

Name localizations set for this command.

type abstractmethod property

type: CommandType

Type of this command.

build

build(_: EntityFactory) -> MutableMapping[str, Any]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

create abstractmethod async

create(
    rest: RESTClient,
    application: SnowflakeishOr[PartialApplication],
    /,
    *,
    guild: UndefinedOr[SnowflakeishOr[PartialGuild]] = undefined.UNDEFINED,
) -> PartialCommand

Create this command through a REST call.

PARAMETER	DESCRIPTION
rest	The REST client to use to make this request. TYPE: RESTClient
application	The application to create this command for. TYPE: SnowflakeishOr[PartialApplication]

PARAMETER	DESCRIPTION
guild	The guild to create this command for. If left undefined then this command will be declared globally. TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

RETURNS	DESCRIPTION
PartialCommand	The created command.

set_default_member_permissions

set_default_member_permissions(
    default_member_permissions: Union[UndefinedType, int, Permissions]
) -> Self

Set the member permissions necessary to utilize this command by default.

PARAMETER	DESCRIPTION
default_member_permissions	The default member permissions to utilize this command by default. If 0, then it will be available for all members. Note that this doesn't affect administrators of the guild and overwrites. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder.

set_id

set_id(id_: UndefinedOr[Snowflakeish]) -> Self

Set the ID of this command.

PARAMETER	DESCRIPTION
id_	The ID to set for this command. TYPE: UndefinedOr[Snowflake]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_is_dm_enabled

set_is_dm_enabled(state: UndefinedOr[bool]) -> Self

Set whether this command will be enabled in DMs with the bot.

PARAMETER	DESCRIPTION
state	Whether this command is enabled in DMs with the bot. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_is_nsfw

set_is_nsfw(state: UndefinedOr[bool]) -> Self

Set whether this command will be age-restricted.

PARAMETER	DESCRIPTION
state	Whether this command is age-restricted. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder for chained calls.

set_name

set_name(name: str) -> Self

Set the name of this command.

PARAMETER	DESCRIPTION
name	The name to set for this command. TYPE: str

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_name_localizations

set_name_localizations(
    name_localizations: Mapping[Union[Locale, str], str]
) -> Self

Set the name localizations for this command.

PARAMETER	DESCRIPTION
name_localizations	The name localizations to set for this command. TYPE: Mapping[Union[Locale, str], str]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder.

ContextMenuCommandBuilder

Bases: CommandBuilder, ContextMenuCommandBuilder

Builder class for context menu commands.

default_member_permissions property

default_member_permissions: Union[UndefinedType, Permissions, int]

Member permissions necessary to utilize this command by default.

If 0, then it will be available for all members. Note that this doesn't affect administrators of the guild and overwrites.

id property

id: UndefinedOr[Snowflake]

ID of this command.

is_dm_enabled property

is_dm_enabled: UndefinedOr[bool]

Whether this command is enabled in DMs with the bot.

Only applicable to globally-scoped commands.

is_nsfw property

is_nsfw: UndefinedOr[bool]

Whether this command age-restricted.

name property

name: str

Name to set for this command.

Warning

This should match the regex ^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$ in Unicode mode and must be lowercase.

name_localizations property

name_localizations: Mapping[Union[Locale, str], str]

Name localizations set for this command.

type property

type: CommandType

Type of this command.

build

build(_: EntityFactory) -> MutableMapping[str, Any]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

create async

create(
    rest: RESTClient,
    application: SnowflakeishOr[PartialApplication],
    /,
    *,
    guild: UndefinedOr[SnowflakeishOr[PartialGuild]] = undefined.UNDEFINED,
) -> ContextMenuCommand

Create this command through a REST call.

This is a shorthand for calling hikari.api.rest.RESTClient.create_context_menu_command with the builder's information.

PARAMETER	DESCRIPTION
rest	The REST client to use to make this request. TYPE: RESTClient
application	The application to create this command for. TYPE: SnowflakeishOr[PartialApplication]

PARAMETER	DESCRIPTION
guild	The guild to create this command for. If left undefined then this command will be declared globally. TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

RETURNS	DESCRIPTION
ContextMenuCommand	The created command.

set_default_member_permissions

set_default_member_permissions(
    default_member_permissions: Union[UndefinedType, int, Permissions]
) -> Self

Set the member permissions necessary to utilize this command by default.

PARAMETER	DESCRIPTION
default_member_permissions	The default member permissions to utilize this command by default. If 0, then it will be available for all members. Note that this doesn't affect administrators of the guild and overwrites. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder.

set_id

set_id(id_: UndefinedOr[Snowflakeish]) -> Self

Set the ID of this command.

PARAMETER	DESCRIPTION
id_	The ID to set for this command. TYPE: UndefinedOr[Snowflake]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_is_dm_enabled

set_is_dm_enabled(state: UndefinedOr[bool]) -> Self

Set whether this command will be enabled in DMs with the bot.

PARAMETER	DESCRIPTION
state	Whether this command is enabled in DMs with the bot. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_is_nsfw

set_is_nsfw(state: UndefinedOr[bool]) -> Self

Set whether this command will be age-restricted.

PARAMETER	DESCRIPTION
state	Whether this command is age-restricted. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder for chained calls.

set_name

set_name(name: str) -> Self

Set the name of this command.

PARAMETER	DESCRIPTION
name	The name to set for this command. TYPE: str

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_name_localizations

set_name_localizations(
    name_localizations: Mapping[Union[Locale, str], str]
) -> Self

Set the name localizations for this command.

PARAMETER	DESCRIPTION
name_localizations	The name localizations to set for this command. TYPE: Mapping[Union[Locale, str], str]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder.

GuildBanIterator

GuildBanIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    guild: SnowflakeishOr[PartialGuild],
    newest_first: bool,
    first_id: str,
)

Bases: BufferedLazyIterator['guilds.GuildBan']

Iterator implementation for retrieving guild bans.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

GuildBuilder

Bases: GuildBuilder

Result type of hikari.api.rest.RESTClient.guild_builder.

This is used to create a guild in a tidy way using the HTTP API, since the logic behind creating a guild on an API level is somewhat confusing and detailed.

Note

If you call hikari.api.special_endpoints.GuildBuilder.add_role, the default roles provided by Discord will be created. This also applies to the add_ functions for text channels/voice channels/categories.

Note

Functions that return a hikari.snowflakes.Snowflake do not provide the final ID that the object will have once the API call is made. The returned IDs are only able to be used to re-reference particular objects while building the guild format to allow for the creation of channels within categories, and to provide permission overwrites.

Examples:

Creating an empty guild:

    guild = await rest.guild_builder("My Server!").create()

Creating a guild with an icon:

    from hikari.files import WebResourceStream

    guild_builder = rest.guild_builder("My Server!")
    guild_builder.icon = WebResourceStream("cat.png", "http://...")
    guild = await guild_builder.create()

Adding roles to your guild:

    from hikari.permissions import Permissions

    guild_builder = rest.guild_builder("My Server!")

    everyone_role_id = guild_builder.add_role("@everyone")
    admin_role_id = guild_builder.add_role("Admins", permissions=Permissions.ADMINISTRATOR)

    await guild_builder.create()

Warning

The first role must always be the @everyone role.

Adding a text channel to your guild:

    guild_builder = rest.guild_builder("My Server!")

    category_id = guild_builder.add_category("My safe place")
    channel_id = guild_builder.add_text_channel("general", parent_id=category_id)

    await guild_builder.create()

default_message_notifications class-attribute instance-attribute

default_message_notifications: UndefinedOr[GuildMessageNotificationsLevel] = (
    field(default=UNDEFINED)
)

Default message notification level that can be overwritten.

If not overridden, this will use the Discord default level.

explicit_content_filter_level class-attribute instance-attribute

explicit_content_filter_level: UndefinedOr[GuildExplicitContentFilterLevel] = (
    field(default=UNDEFINED)
)

Explicit content filter level that can be overwritten.

If not overridden, this will use the Discord default level.

icon class-attribute instance-attribute

icon: UndefinedOr[Resourceish] = field(default=UNDEFINED)

Guild icon to use that can be overwritten.

If not overridden, the guild will not have an icon.

name property

name: str

Name of the guild to create.

verification_level class-attribute instance-attribute

verification_level: UndefinedOr[Union[GuildVerificationLevel, int]] = field(
    default=UNDEFINED
)

Verification level required to join the guild.

add_category

add_category(
    name: str,
    /,
    *,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Collection[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
) -> Snowflake

Create a category channel.

PARAMETER	DESCRIPTION
name	The channels name. Must be between 2 and 1000 characters. TYPE: str

PARAMETER	DESCRIPTION
position	If provided, the position of the category. TYPE: UndefinedOr[int]
permission_overwrites	If provided, the permission overwrites for the category. TYPE: UndefinedOr[Sequence[PermissionOverwrite]]

RETURNS	DESCRIPTION
Snowflake	The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout. When the guild is created, this will be replaced with a different ID.

add_role

add_role(
    name: str,
    /,
    *,
    color: UndefinedOr[Colorish] = undefined.UNDEFINED,
    colour: UndefinedOr[Colorish] = undefined.UNDEFINED,
    hoist: UndefinedOr[bool] = undefined.UNDEFINED,
    mentionable: UndefinedOr[bool] = undefined.UNDEFINED,
    permissions: UndefinedOr[Permissions] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
) -> Snowflake

Create a role.

Warning

The first role you create (i.e., position 0) must always be the @everyone role.

PARAMETER	DESCRIPTION
name	The role's name. TYPE: str

PARAMETER	DESCRIPTION
permissions	If provided, the permissions for the role. TYPE: UndefinedOr[Permissions]
color	If provided, the role's color. TYPE: UndefinedOr[Colorish]
colour	An alias for color. TYPE: UndefinedOr[Colorish]
hoist	If provided, whether to hoist the role. TYPE: UndefinedOr[bool]
mentionable	If provided, whether to make the role mentionable. TYPE: UndefinedOr[bool]
position	If provided, the position of the role. TYPE: UndefinedOr[int]

RETURNS	DESCRIPTION
Snowflake	The dummy ID for this role that can be used temporarily to refer to this object while designing the guild layout. When the guild is created, this will be replaced with a different ID.

RAISES	DESCRIPTION
ValueError	If you are defining the first role, but did not name it @everyone.
TypeError	If you specify both color and colour together or if you try to specify color, colour, hoisted, mentionable or position for the @everyone role.

add_stage_channel

add_stage_channel(
    name: str,
    /,
    *,
    parent_id: UndefinedOr[Snowflake] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Collection[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    region: UndefinedNoneOr[Union[VoiceRegion, str]],
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
) -> Snowflake

Create a stage channel.

PARAMETER	DESCRIPTION
name	The channels name. Must be between 2 and 1000 characters. TYPE: str

PARAMETER	DESCRIPTION
position	If provided, the position of the channel (relative to the category, if any). TYPE: UndefinedOr[int]
user_limit	If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit. TYPE: UndefinedOr[int]
bitrate	If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers. TYPE: UndefinedOr[int]
permission_overwrites	If provided, the permission overwrites for the channel. TYPE: UndefinedOr[Sequence[PermissionOverwrite]]
region	If provided, the voice region to for this channel. Passing None here will set it to "auto" mode where the used region will be decided based on the first person who connects to it when it's empty. TYPE: UndefinedOr[Union[VoiceRegion, str]]
parent_id	The ID of the category to create the channel under. TYPE: UndefinedOr[Snowflake]

RETURNS	DESCRIPTION
Snowflake	The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout. When the guild is created, this will be replaced with a different ID.

add_text_channel

add_text_channel(
    name: str,
    /,
    *,
    parent_id: UndefinedOr[Snowflake] = undefined.UNDEFINED,
    topic: UndefinedOr[str] = undefined.UNDEFINED,
    rate_limit_per_user: UndefinedOr[Intervalish] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Collection[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    nsfw: UndefinedOr[bool] = undefined.UNDEFINED,
) -> Snowflake

Create a text channel.

PARAMETER	DESCRIPTION
name	The channels name. Must be between 2 and 1000 characters. TYPE: str

PARAMETER	DESCRIPTION
position	If provided, the position of the channel (relative to the category, if any). TYPE: UndefinedOr[int]
topic	If provided, the channels topic. Maximum 1024 characters. TYPE: UndefinedOr[str]
nsfw	If provided, whether to mark the channel as NSFW. TYPE: UndefinedOr[bool]
rate_limit_per_user	If provided, the amount of seconds a user has to wait before being able to send another message in the channel. Maximum 21600 seconds. TYPE: UndefinedOr[int]
permission_overwrites	If provided, the permission overwrites for the channel. TYPE: UndefinedOr[Sequence[PermissionOverwrite]]
parent_id	The ID of the category to create the channel under. TYPE: UndefinedOr[Snowflake]

RETURNS	DESCRIPTION
Snowflake	The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout. When the guild is created, this will be replaced with a different ID.

add_voice_channel

add_voice_channel(
    name: str,
    /,
    *,
    parent_id: UndefinedOr[Snowflake] = undefined.UNDEFINED,
    bitrate: UndefinedOr[int] = undefined.UNDEFINED,
    video_quality_mode: UndefinedOr[
        Union[VideoQualityMode, int]
    ] = undefined.UNDEFINED,
    position: UndefinedOr[int] = undefined.UNDEFINED,
    permission_overwrites: UndefinedOr[
        Collection[PermissionOverwrite]
    ] = undefined.UNDEFINED,
    region: UndefinedNoneOr[Union[VoiceRegion, str]],
    user_limit: UndefinedOr[int] = undefined.UNDEFINED,
) -> Snowflake

Create a voice channel.

PARAMETER	DESCRIPTION
name	The channels name. Must be between 2 and 1000 characters. TYPE: str

PARAMETER	DESCRIPTION
position	If provided, the position of the channel (relative to the category, if any). TYPE: UndefinedOr[int]
user_limit	If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit. TYPE: UndefinedOr[int]
bitrate	If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers. TYPE: UndefinedOr[int]
video_quality_mode	If provided, the new video quality mode for the channel. TYPE: UndefinedOr[Union[VideoQualityMode, int]]
permission_overwrites	If provided, the permission overwrites for the channel. TYPE: UndefinedOr[Sequence[PermissionOverwrite]]
region	If provided, the voice region to for this channel. Passing None here will set it to "auto" mode where the used region will be decided based on the first person who connects to it when it's empty. TYPE: UndefinedOr[Union[VoiceRegion, str]]
parent_id	The ID of the category to create the channel under. TYPE: UndefinedOr[Snowflake]

RETURNS	DESCRIPTION
Snowflake	The dummy ID for this channel that can be used temporarily to refer to this object while designing the guild layout. When the guild is created, this will be replaced with a different ID.

create async

create() -> RESTGuild

Send the request to Discord to create the guild.

The application user will be added to this guild as soon as it is created. All IDs that were provided when building this guild will become invalid and will be replaced with real IDs.

RETURNS	DESCRIPTION
RESTGuild	The created guild.

RAISES	DESCRIPTION
BadRequestError	If any values set in the guild builder are invalid.
UnauthorizedError	If you are unauthorized to make the request (invalid/missing token).
ForbiddenError	If you are already in 10 guilds.
InternalServerError	If an internal error occurs on Discord while handling the request.

GuildThreadIterator

GuildThreadIterator(
    deserialize: _ThreadDeserializeSig[_GuildThreadChannelCovT],
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    route: CompiledRoute,
    before: UndefinedOr[str],
    before_is_timestamp: bool,
)

Bases: BufferedLazyIterator[_GuildThreadChannelT]

Iterator implemented for guild thread endpoints.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

InteractionAutocompleteBuilder

Bases: InteractionAutocompleteBuilder

Standard implementation of hikari.api.special_endpoints.InteractionAutocompleteBuilder.

choices property

choices: Sequence[AutocompleteChoiceBuilder]

Autocomplete choices.

type property

type: Literal[AUTOCOMPLETE]

Type of this response.

build

build(
    _: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
typing.Tuple[typing.MutableMapping[str, typing.Any], typing.Sequence[files.Resource[Files.AsyncReader]]	A tuple of the built json object representation of this builder and a sequence of up to 10 files to send with the response.

set_choices

set_choices(choices: Sequence[AutocompleteChoiceBuilder]) -> Self

Set autocomplete choices.

PARAMETER	DESCRIPTION
choices	The choices to set. TYPE: Sequence[AutocompleteChoiceBuilder]

RETURNS	DESCRIPTION
InteractionAutocompleteBuilder	Object of this builder.

InteractionDeferredBuilder

Bases: InteractionDeferredBuilder

Standard implementation of hikari.api.special_endpoints.InteractionDeferredBuilder.

PARAMETER	DESCRIPTION
type	The type of interaction response this is. TYPE: DeferredResponseTypesT

flags property

flags: Union[UndefinedType, int, MessageFlag]

Message flags this response should have.

Note

As of writing the only message flags which can be set here are hikari.messages.MessageFlag.EPHEMERAL, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.SUPPRESS_EMBEDS.

type property

type: DeferredResponseTypesT

Type of this response.

build

build(
    _: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
typing.Tuple[typing.MutableMapping[str, typing.Any], typing.Sequence[files.Resource[Files.AsyncReader]]	A tuple of the built json object representation of this builder and a sequence of up to 10 files to send with the response.

set_flags

set_flags(flags: Union[UndefinedType, int, MessageFlag]) -> Self

Set message flags for this response.

Note

As of writing, the only message flags which can be set are hikari.messages.MessageFlag.EPHEMERAL hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.SUPPRESS_EMBEDS.

PARAMETER	DESCRIPTION
flags	The message flags to set for this response. TYPE: Union[UndefinedType, int, MessageFlag]

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder.

InteractionMessageBuilder

Bases: InteractionMessageBuilder

Standard implementation of hikari.api.special_endpoints.InteractionMessageBuilder.

PARAMETER	DESCRIPTION
type	The type of interaction response this is. TYPE: MessageResponseTypesT

PARAMETER	DESCRIPTION
content	The content of this response, if supplied. This follows the same rules as "content" on create message. TYPE: UndefinedOr[str]

attachments property

attachments: UndefinedNoneOr[Sequence[Resourceish]]

Sequence of up to 10 attachments to send with the message.

components property

components: UndefinedNoneOr[Sequence[ComponentBuilder]]

Sequence of up to 5 component builders to send in this response.

content property

content: UndefinedNoneOr[str]

Response's message content.

embeds property

embeds: UndefinedNoneOr[Sequence[Embed]]

Sequence of up to 10 of the embeds included in this response.

flags property

flags: Union[UndefinedType, int, MessageFlag]

Message flags this response should have.

Note

As of writing the only message flags which can be set here are hikari.messages.MessageFlag.EPHEMERAL, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS and hikari.messages.MessageFlag.SUPPRESS_EMBEDS.

is_tts property

is_tts: UndefinedOr[bool]

Whether this response's content should be treated as text-to-speech.

mentions_everyone property

mentions_everyone: UndefinedOr[bool]

Whether @everyone and @here mentions should be enabled for this response.

role_mentions property

role_mentions: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]

Whether and what role mentions should be enabled for this response.

Either a sequence of object/IDs of the roles mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any role mentions or True to allow all role mentions.

type property

type: MessageResponseTypesT

Type of this response.

user_mentions property

user_mentions: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]

Whether and what user mentions should be enabled for this response.

Either a sequence of object/IDs of the users mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any user mentions or True to allow all user mentions.

add_attachment

add_attachment(attachment: Resourceish) -> Self

Add an attachment to this response.

PARAMETER	DESCRIPTION
attachment	The attachment to add. TYPE: Resourceish

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder.

add_component

add_component(component: ComponentBuilder) -> Self

Add a component to this response.

PARAMETER	DESCRIPTION
component	The component builder to add to this response. TYPE: ComponentBuilder

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder.

add_embed

add_embed(embed: Embed) -> Self

Add an embed to this response.

PARAMETER	DESCRIPTION
embed	Object of the embed to add to this response. TYPE: Embed

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

build

build(
    entity_factory: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
typing.Tuple[typing.MutableMapping[str, typing.Any], typing.Sequence[files.Resource[Files.AsyncReader]]	A tuple of the built json object representation of this builder and a sequence of up to 10 files to send with the response.

clear_attachments

clear_attachments() -> Self

Clear attachments for this response.

This is only useful for message update responses, where you might want to remove all existing attachments.

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder.

set_content

set_content(content: UndefinedOr[str]) -> Self

Set the response's message content.

PARAMETER	DESCRIPTION
content	The message content to set for this response. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

set_flags

set_flags(flags: Union[UndefinedType, int, MessageFlag]) -> Self

Set message flags for this response.

Note

As of writing, the only message flags which can be set is hikari.messages.MessageFlag.EPHEMERAL and hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS.

PARAMETER	DESCRIPTION
flags	The message flags to set for this response. TYPE: Union[UndefinedType, int, MessageFlag]

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

set_mentions_everyone

set_mentions_everyone(state: UndefinedOr[bool] = undefined.UNDEFINED) -> Self

Set whether this response should be able to mention @everyone/@here.

PARAMETER	DESCRIPTION
mentions	Whether this response should be able to mention @everyone/@here. TYPE: UndefinedOr[bool] DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

set_role_mentions

set_role_mentions(
    role_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialRole], bool]
    ] = undefined.UNDEFINED
) -> Self

Set whether and what role mentions should be possible for this response.

PARAMETER	DESCRIPTION
mentions	Either a sequence of object/IDs of the roles mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any role mentions or True to allow all role mentions. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]] DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

set_tts

set_tts(tts: UndefinedOr[bool]) -> Self

Set whether this response should trigger text-to-speech processing.

PARAMETER	DESCRIPTION
tts	Whether this response should trigger text-to-speech processing. TYPE: bool

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

set_user_mentions

set_user_mentions(
    user_mentions: UndefinedOr[
        Union[SnowflakeishSequence[PartialUser], bool]
    ] = undefined.UNDEFINED
) -> Self

Set whether and what user mentions should be possible for this response.

PARAMETER	DESCRIPTION
mentions	Either a sequence of object/IDs of the users mentions should be enabled for, False or hikari.undefined.UNDEFINED to disallow any user mentions or True to allow all user mentions. TYPE: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]] DEFAULT: UNDEFINED

RETURNS	DESCRIPTION
InteractionMessageBuilder	Object of this builder to allow for chained calls.

InteractionModalBuilder

Bases: InteractionModalBuilder

Standard implementation of hikari.api.special_endpoints.InteractionModalBuilder.

components property

components: Sequence[ComponentBuilder]

Sequence of component builders to send in this modal.

custom_id property

custom_id: str

Developer set custom ID used for identifying interactions with this modal.

title property

title: str

Title that will show up in the modal.

type property

type: Literal[MODAL]

Type of this response.

add_component

add_component(component: ComponentBuilder) -> Self

Add a component to this modal.

PARAMETER	DESCRIPTION
component	The component builder to add to this modal. TYPE: ComponentBuilder

build

build(
    entity_factory: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
typing.Tuple[typing.MutableMapping[str, typing.Any], typing.Sequence[files.Resource[Files.AsyncReader]]	A tuple of the built json object representation of this builder and a sequence of up to 10 files to send with the response.

set_custom_id

set_custom_id(custom_id: str) -> Self

Set the custom ID used for identifying interactions with this modal.

PARAMETER	DESCRIPTION
custom_id	The developer set custom ID used for identifying interactions with this modal. TYPE: str

set_title

set_title(title: str) -> Self

Set the title that will show up in the modal.

PARAMETER	DESCRIPTION
title	The title that will show up in the modal. TYPE: str

InteractiveButtonBuilder

Bases: _ButtonBuilder, InteractiveButtonBuilder

Builder class for interactive buttons.

custom_id property

custom_id: str

Developer set custom ID used for identifying interactions with this button.

emoji property

emoji: Union[Snowflakeish, Emoji, str, UndefinedType]

Emoji which should appear on this button.

is_disabled property

is_disabled: bool

Whether the button should be marked as disabled.

label property

label: UndefinedOr[str]

Text label which should appear on this button.

Note

The text label to that should appear on this button. This may be up to 80 characters long.

style property

style: Union[int, ButtonStyle]

Button's style.

type property

type: Literal[BUTTON]

Type of component this builder represents.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_custom_id

set_custom_id(custom_id: str) -> Self

Set the custom ID used for identifying this button.

PARAMETER	DESCRIPTION
custom_id	Developer set custom ID used for identifying this button. TYPE: str

RETURNS	DESCRIPTION
InteractiveButtonBuilder	The builder object to enable chained calls.

set_emoji

set_emoji(emoji: Union[Snowflakeish, Emoji, str, UndefinedType]) -> Self

Set the emoji to display on this button.

PARAMETER	DESCRIPTION
emoji	Object, ID or raw string of the emoji which should be displayed on this button. TYPE: Union[Snowflakeish, Emoji, str, UndefinedType]

RETURNS	DESCRIPTION
ButtonBuilder	The builder object to enable chained calls.

set_is_disabled

set_is_disabled(state: bool) -> Self

Set whether this button should be disabled.

PARAMETER	DESCRIPTION
state	Whether this button should be disabled. TYPE: bool

RETURNS	DESCRIPTION
ButtonBuilder	The builder object to enable chained calls.

set_label

set_label(label: UndefinedOr[str]) -> Self

Set the text label which should be displayed on this button.

PARAMETER	DESCRIPTION
label	The text label to show on this button. This may be up to 80 characters long. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
ButtonBuilder	The builder object to enable chained calls.

LinkButtonBuilder

Bases: _ButtonBuilder, LinkButtonBuilder

Builder class for link buttons.

emoji property

emoji: Union[Snowflakeish, Emoji, str, UndefinedType]

Emoji which should appear on this button.

is_disabled property

is_disabled: bool

Whether the button should be marked as disabled.

label property

label: UndefinedOr[str]

Text label which should appear on this button.

Note

The text label to that should appear on this button. This may be up to 80 characters long.

style property

style: Union[int, ButtonStyle]

Button's style.

type property

type: Literal[BUTTON]

Type of component this builder represents.

url property

url: str

URL this button should link to when pressed.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_emoji

set_emoji(emoji: Union[Snowflakeish, Emoji, str, UndefinedType]) -> Self

Set the emoji to display on this button.

PARAMETER	DESCRIPTION
emoji	Object, ID or raw string of the emoji which should be displayed on this button. TYPE: Union[Snowflakeish, Emoji, str, UndefinedType]

RETURNS	DESCRIPTION
ButtonBuilder	The builder object to enable chained calls.

set_is_disabled

set_is_disabled(state: bool) -> Self

Set whether this button should be disabled.

PARAMETER	DESCRIPTION
state	Whether this button should be disabled. TYPE: bool

RETURNS	DESCRIPTION
ButtonBuilder	The builder object to enable chained calls.

set_label

set_label(label: UndefinedOr[str]) -> Self

Set the text label which should be displayed on this button.

PARAMETER	DESCRIPTION
label	The text label to show on this button. This may be up to 80 characters long. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
ButtonBuilder	The builder object to enable chained calls.

MemberIterator

MemberIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    guild: SnowflakeishOr[PartialGuild],
)

Bases: BufferedLazyIterator['guilds.Member']

Implementation of an iterator for retrieving members in a guild.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

MessageActionRowBuilder

Bases: MessageActionRowBuilder

Standard implementation of hikari.api.special_endpoints.MessageActionRowBuilder.

components property

components: Sequence[ComponentBuilder]

Sequence of the component builders registered within this action row.

type property

type: Literal[ACTION_ROW]

Type of component this builder represents.

add_channel_menu

add_channel_menu(
    custom_id: str,
    /,
    *,
    channel_types: Sequence[ChannelType] = (),
    placeholder: UndefinedOr[str] = undefined.UNDEFINED,
    min_values: int = 0,
    max_values: int = 1,
    is_disabled: bool = False,
) -> Self

Add a channel select menu component to this action row builder.

PARAMETER	DESCRIPTION
custom_id	A developer-defined custom identifier used to identify which menu triggered component interactions. TYPE: str
channel_types	The channel types this select menu should allow. If left as an empty sequence then there will be no channel type restriction. TYPE: Sequence[ChannelType] DEFAULT: ()
placeholder	Placeholder text to show when no entries have been selected. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
min_values	The minimum amount of entries which need to be selected. TYPE: int DEFAULT: 0
max_values	The maximum amount of entries which can be selected. TYPE: int DEFAULT: 1
is_disabled	Whether this select menu should be marked as disabled. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ActionRowBuilder	The action row builder to enable chained calls.

RAISES	DESCRIPTION
ValueError	If an invalid select menu type is passed.

add_component

add_component(component: ComponentBuilder) -> Self

Add a component to this action row builder.

Warning

It is generally better to use hikari.api.special_endpoints.MessageActionRowBuilder.add_interactive_button and hikari.api.special_endpoints.MessageActionRowBuilder.add_select_menu to add your component to the builder. Those methods utilize this one.

PARAMETER	DESCRIPTION
component	The component builder to add to the action row. TYPE: ComponentBuilder

RETURNS	DESCRIPTION
ActionRowBuilder	The builder object to enable chained calls.

add_interactive_button

add_interactive_button(
    style: InteractiveButtonTypesT,
    custom_id: str,
    /,
    *,
    emoji: Union[Snowflakeish, Emoji, str, UndefinedType] = undefined.UNDEFINED,
    label: UndefinedOr[str] = undefined.UNDEFINED,
    is_disabled: bool = False,
) -> Self

Add an interactive button component to this action row builder.

Either emoji or label (exclusively) must be provided to be the button's displayed label.

PARAMETER	DESCRIPTION
style	The button's style. TYPE: InteractiveButtonTypesT
custom_id	The developer-defined custom identifier used to identify which button triggered component interactions. TYPE: str
emoji	The button's display emoji. TYPE: Union[Snowflakeish, Emoji, str, UndefinedType] DEFAULT: UNDEFINED
label	The button's display label. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
is_disabled	Whether the button should be marked as disabled. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ActionRowBuilder	The action row builder to enable chained calls.

add_link_button

add_link_button(
    url: str,
    /,
    *,
    emoji: Union[Snowflakeish, Emoji, str, UndefinedType] = undefined.UNDEFINED,
    label: UndefinedOr[str] = undefined.UNDEFINED,
    is_disabled: bool = False,
) -> Self

Add a link button component to this action row builder.

Either emoji or label (exclusively) must be provided to be the button's displayed label.

PARAMETER	DESCRIPTION
url	The URL the link button should redirect to. TYPE: str
emoji	The button's display emoji. TYPE: Union[Snowflakeish, Emoji, str, UndefinedType] DEFAULT: UNDEFINED
label	The button's display label. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
is_disabled	Whether the button should be marked as disabled. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ActionRowBuilder	The action row builder to enable chained calls.

add_select_menu

add_select_menu(
    type_: Union[ComponentType, int],
    custom_id: str,
    /,
    *,
    placeholder: UndefinedOr[str] = undefined.UNDEFINED,
    min_values: int = 0,
    max_values: int = 1,
    is_disabled: bool = False,
) -> Self

Add a select menu component to this action row builder.

For channel select menus and text select menus see hikari.api.special_endpoints.MessageActionRowBuilder.add_channel_menu and hikari.api.special_endpoints.MessageActionRowBuilder.add_text_menu.

PARAMETER	DESCRIPTION
type_	The type for the select menu. TYPE: Union[ComponentType, int]
custom_id	A developer-defined custom identifier used to identify which menu triggered component interactions. TYPE: str
placeholder	Placeholder text to show when no entries have been selected. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
min_values	The minimum amount of entries which need to be selected. TYPE: int DEFAULT: 0
max_values	The maximum amount of entries which can be selected. TYPE: int DEFAULT: 1
is_disabled	Whether this select menu should be marked as disabled. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ActionRowBuilder	The action row builder to enable chained calls.

RAISES	DESCRIPTION
ValueError	If an invalid select menu type is passed.

add_text_menu

add_text_menu(
    custom_id: str,
    /,
    *,
    placeholder: UndefinedOr[str] = undefined.UNDEFINED,
    min_values: int = 0,
    max_values: int = 1,
    is_disabled: bool = False,
) -> TextSelectMenuBuilder[Self]

Add a select menu component to this action row builder.

PARAMETER	DESCRIPTION
custom_id	A developer-defined custom identifier used to identify which menu triggered component interactions. TYPE: str
placeholder	Placeholder text to show when no entries have been selected. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
min_values	The minimum amount of entries which need to be selected. TYPE: int DEFAULT: 0
max_values	The maximum amount of entries which can be selected. TYPE: int DEFAULT: 1
is_disabled	Whether this select menu should be marked as disabled. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
TextSelectMenuBuilder	The text select menu builder. hikari.api.special_endpoints.TextSelectMenuBuilder.add_option should be called to add options to the returned builder then hikari.api.special_endpoints.TextSelectMenuBuilder.parent can be used to return to this action row while chaining calls.

RAISES	DESCRIPTION
ValueError	If an invalid select menu type is passed.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

MessageIterator

MessageIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    channel: SnowflakeishOr[TextableChannel],
    direction: str,
    first_id: UndefinedOr[str],
)

Bases: BufferedLazyIterator['messages.Message']

Implementation of an iterator for message history.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

ModalActionRowBuilder

Bases: ModalActionRowBuilder

Standard implementation of hikari.api.special_endpoints.ModalActionRowBuilder.

components property

components: Sequence[ComponentBuilder]

Sequence of the component builders registered within this action row.

type property

type: Literal[ACTION_ROW]

Type of component this builder represents.

add_component

add_component(component: ComponentBuilder) -> Self

Add a component to this action row builder.

Warning

It is generally better to use hikari.api.special_endpoints.MessageActionRowBuilder.add_interactive_button and hikari.api.special_endpoints.MessageActionRowBuilder.add_select_menu to add your component to the builder. Those methods utilize this one.

PARAMETER	DESCRIPTION
component	The component builder to add to the action row. TYPE: ComponentBuilder

RETURNS	DESCRIPTION
ActionRowBuilder	The builder object to enable chained calls.

add_text_input

add_text_input(
    custom_id: str,
    label: str,
    /,
    *,
    style: TextInputStyle = component_models.TextInputStyle.SHORT,
    placeholder: UndefinedOr[str] = undefined.UNDEFINED,
    value: UndefinedOr[str] = undefined.UNDEFINED,
    required: bool = True,
    min_length: int = 0,
    max_length: int = 4000,
) -> Self

Add a text input component to this action row builder.

PARAMETER	DESCRIPTION
custom_id	Developer set custom ID used for identifying this text input. TYPE: str
label	Label above this text input. TYPE: str
style	The text input's style. TYPE: TextInputStyle DEFAULT: SHORT
placeholder	Placeholder text to display when the text input is empty. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
value	Default text to pre-fill the field with. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
required	Whether text must be supplied for this text input. TYPE: bool DEFAULT: True
min_length	Minimum length the input text can be. This can be greater than or equal to 0 and less than or equal to 4000. TYPE: int DEFAULT: 0
max_length	Maximum length the input text can be. This can be greater than or equal to 1 and less than or equal to 4000. TYPE: int DEFAULT: 4000

RETURNS	DESCRIPTION
ModalActionRowBuilder	The modal action row builder to enable call chaining.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

OwnGuildIterator

OwnGuildIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    newest_first: bool,
    first_id: str,
)

Bases: BufferedLazyIterator['applications.OwnGuild']

Implementation of an iterator for retrieving guilds you are in.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

ReactorIterator

ReactorIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    channel: SnowflakeishOr[TextableChannel],
    message: SnowflakeishOr[PartialMessage],
    emoji: str,
)

Bases: BufferedLazyIterator['users.User']

Implementation of an iterator for message reactions.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

ScheduledEventUserIterator

ScheduledEventUserIterator(
    entity_factory: EntityFactory,
    request_call: _RequestCallSig,
    newest_first: bool,
    first_id: str,
    guild: SnowflakeishOr[PartialGuild],
    event: SnowflakeishOr[ScheduledEvent],
)

Bases: BufferedLazyIterator['scheduled_events.ScheduledEventUser']

Implementation of an iterator for retrieving the users subscribed to a scheduled event.

awaiting

awaiting(window_size: int = 10) -> LazyIterator[ValueT]

Await each item concurrently in a fixed size window.

Warning

Setting a large window size, or setting it to 0 to await everything is a dangerous thing to do if you are making API calls. Some endpoints will get ratelimited and cause a backup of waiting tasks, others may begin to spam global rate limits instead (the fetch_user endpoint seems to be notorious for doing this).

Note

This call assumes that the iterator contains awaitable values as input. MyPy cannot detect this nicely, so any cast is forced internally. If the item is not awaitable, you will receive a TypeError instead. You have been warned. You cannot escape the ways of the duck type young grasshopper.

PARAMETER	DESCRIPTION
window_size	The window size of how many tasks to await at once. You can set this to 0 to await everything at once, but see the below warning. TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The new lazy iterator to return.

chunk

chunk(chunk_size: int) -> LazyIterator[Sequence[ValueT]]

Return results in chunks of up to chunk_size amount of entries.

PARAMETER	DESCRIPTION
chunk_size	The limit for how many results should be returned in each chunk. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[Sequence[ValueT]]	hikari.iterators.LazyIterator that emits each chunked sequence.

collect async

collect(
    collector: Callable[[Sequence[ValueT]], Collection[ValueT]]
) -> Collection[ValueT]

Collect the results into a given type and return it.

PARAMETER	DESCRIPTION
collector	A function that consumes a sequence of values and returns a collection. TYPE: Callable[[Sequence[ValueT]], Collection[ValueT]]

count async

count() -> int

Count the number of results.

RETURNS	DESCRIPTION
int	Number of results found.

enumerate

enumerate(*, start: int = 0) -> LazyIterator[Tuple[int, ValueT]]

Enumerate the paginated results lazily.

This behaves as an asyncio-friendly version of enumerate which uses much less memory than collecting all the results first and calling enumerate across them.

PARAMETER	DESCRIPTION
start	Optional int to start at. If omitted, this is 0. TYPE: int DEFAULT: 0

Examples:

    >>> async for i, item in paginated_results.enumerate():
    ...    print(i, item)
    (0, foo)
    (1, bar)
    (2, baz)
    (3, bork)
    (4, qux)

    >>> async for i, item in paginated_results.enumerate(start=9):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)
    (12, bork)
    (13, qux)

    >>> async for i, item in paginated_results.enumerate(start=9).limit(3):
    ...    print(i, item)
    (9, foo)
    (10, bar)
    (11, baz)

RETURNS	DESCRIPTION
LazyIterator[Tuple[int, T]]	A paginated results view that asynchronously yields an increasing counter in a tuple with each result, lazily.

filter

filter(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Filter the items by one or more conditions.

Each condition is treated as a predicate, being called with each item that this iterator would return when it is requested.

All conditions must evaluate to True for the item to be returned. If this is not met, then the item is discarded and ignored, the next matching item will be returned instead, if there is one.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.filter(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	hikari.iterators.LazyIterator that only emits values where all conditions are matched.

flat_map

flat_map(
    flattener: _FlattenerT[ValueT, AnotherValueT]
) -> LazyIterator[AnotherValueT]

Perform a flat mapping operation.

This will pass each item in the iterator to the given function parameter, expecting a new typing.Iterable or typing.AsyncIterator to be returned as the result. This means you can map to a new hikari.iterators.LazyIterator, typing.AsyncIterator, typing.Iterable, async generator, or generator.

Remember that typing.Iterator implicitly provides typing.Iterable compatibility.

This is used to provide lazy conversions, and can be used to implement reactive-like pipelines if desired.

All results are combined into one large lazy iterator and yielded lazily.

PARAMETER	DESCRIPTION
flattener	A function that returns either an async iterator or iterator of new values. Could be an attribute name instead. TYPE: _FlattenerT[ValueT, AnotherValueT]

Examples:

The following example generates a distinct collection of all mentioned users in the given channel from the past 500 messages.

    def iter_mentioned_users(message: hikari.Message) -> typing.Iterable[Snowflake]:
        for match in re.findall(r"<@!?(\d+)>", message.content):
            yield Snowflake(match)

    mentioned_users = await (
        channel
        .history()
        .limit(500)
        .map(".content")
        .flat_map(iter_mentioned_users)
        .distinct()
    )

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	The new lazy iterator to return.

flatten

flatten() -> LazyIterator[AnotherValueT]

Flatten an async iterator of iterables.

for_each async

for_each(consumer: Callable[[ValueT], Any]) -> None

Forward each value to a given consumer immediately.

last async

last() -> ValueT

Return the last element of this iterator only.

Note

This method will consume the whole iterator if run.

RETURNS	DESCRIPTION
ValueT	The last result.

RAISES	DESCRIPTION
LookupError	If no result exists.

limit

limit(limit: int) -> LazyIterator[ValueT]

Limit the number of items you receive from this async iterator.

PARAMETER	DESCRIPTION
limit	The number of items to get. This must be greater than zero. TYPE: int

Examples:

    >>> async for item in paginated_results.limit(3):
    ...     print(item)

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields a maximum of the given number of items before completing.

map

map(
    transformation: Union[Callable[[ValueT], AnotherValueT], str]
) -> LazyIterator[AnotherValueT]

Map the values to a different value.

PARAMETER	DESCRIPTION
transformation	The function to use to map the attribute. This may alternatively be a string attribute name to replace the input value with. You can provide nested attributes using the . operator. TYPE: Union[Callable[[ValueT], bool], str]

RETURNS	DESCRIPTION
LazyIterator[AnotherValueT]	hikari.iterators.LazyIterator that maps each value to another value.

next async

next() -> ValueT

Return the next element of this iterator only.

RETURNS	DESCRIPTION
ValueT	The next result.

RAISES	DESCRIPTION
LookupError	If no more results exist.

reversed

reversed() -> LazyIterator[ValueT]

Return a lazy iterator of the remainder of this iterator's values reversed.

RETURNS	DESCRIPTION
LazyIterator[ValueT]	The lazy iterator of this iterator's remaining values reversed.

skip

skip(number: int) -> LazyIterator[ValueT]

Drop the given number of items, then yield anything after.

PARAMETER	DESCRIPTION
number	The max number of items to drop before any items are yielded. TYPE: int

RETURNS	DESCRIPTION
LazyIterator[ValueT]	A paginated results view that asynchronously yields all items AFTER the given number of items are discarded first.

skip_until

skip_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are False.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has failed. All items before this are discarded.

skip_while

skip_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Discard items while all conditions are True.

Items after this will be yielded as normal.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.skip_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values once a condition has been met. All items before this are discarded.

sort async

sort(*, key: Any = None, reverse: bool = False) -> Sequence[ValueT]

Collect all results, then sort the collection before returning it.

take_until

take_until(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions pass or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_until(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are matched.

take_while

take_while(
    *predicates: Union[Tuple[str, Any], Callable[[ValueT], bool]], **attrs: Any
) -> LazyIterator[ValueT]

Return each item until any conditions fail or the end is reached.

PARAMETER	DESCRIPTION
*predicates	Predicates to invoke. These are functions that take a value and return True if it is of interest, or False otherwise. These may instead include 2-tuple objects consisting of a str attribute name (nested attributes are referred to using the . operator), and values to compare for equality. This allows you to specify conditions such as members.take_while(("user.bot", True)). TYPE: Union[Callable[[ValueT], bool], Tuple[str, Any]] DEFAULT: ()
**attrs	Alternative to passing 2-tuples. Cannot specify nested attributes using this method. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
LazyIterator[ValueT]	LazyIterator that only emits values until any conditions are not matched.

SelectMenuBuilder

Bases: SelectMenuBuilder

Builder class for select menus.

custom_id property

custom_id: str

Developer set custom ID used for identifying interactions with this menu.

is_disabled property

is_disabled: bool

Whether the select menu should be marked as disabled.

max_values property

max_values: int

Maximum number of options which can be chosen.

Defaults to 1. Must be greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values and less than or equal to 25.

min_values property

min_values: int

Minimum number of options which must be chosen.

Defaults to 1. Must be less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values and greater than or equal to 0.

placeholder property

placeholder: UndefinedOr[str]

Placeholder text to display when no options are selected.

type property

type: Union[int, ComponentType]

Type of component this builder represents.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_custom_id

set_custom_id(custom_id: str) -> Self

Set the custom ID used for identifying this menu.

PARAMETER	DESCRIPTION
custom_id	Developer set custom ID used for identifying this menu. TYPE: str

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_is_disabled

set_is_disabled(state: bool) -> Self

Set whether this option is disabled.

PARAMETER	DESCRIPTION
state	Whether this option is disabled. TYPE: bool

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_max_values

set_max_values(value: int) -> Self

Set the maximum amount of options which can be selected for this menu.

Note

This defaults to 1 if not set and must be less than or equal to 25 and greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values.

PARAMETER	DESCRIPTION
value	The maximum amount of options which can selected for this menu. TYPE: int

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_min_values

set_min_values(value: int) -> Self

Set the minimum amount of options which need to be selected for this menu.

Note

This defaults to 1 if not set and must be greater than or equal to 0 and less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values.

PARAMETER	DESCRIPTION
value	The minimum amount of options which need to be selected for this menu. TYPE: int

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_placeholder

set_placeholder(value: UndefinedOr[str]) -> Self

Set place-holder text to be shown when no option is selected.

PARAMETER	DESCRIPTION
value	Place-holder text to be displayed when no option is selected. Max 100 characters. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

SelectOptionBuilder

Bases: SelectOptionBuilder

Builder class for select menu options.

description property

description: UndefinedOr[str]

Description of the option, max 100 characters.

emoji property

emoji: Union[Snowflakeish, Emoji, str, UndefinedType]

Emoji which should appear on this option.

is_default property

is_default: bool

Whether this option should be marked as selected by default.

label property

label: str

User-facing name of the option, max 100 characters.

value property

value: str

Developer-defined value of the option, max 100 characters.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_description

set_description(value: UndefinedOr[str]) -> Self

Set the option's description.

PARAMETER	DESCRIPTION
value	Description to set for this option. This can be up to 100 characters long. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
SelectOptionBuilder	The builder object to enable chained calls.

set_emoji

set_emoji(emoji: Union[Snowflakeish, Emoji, str, UndefinedType]) -> Self

Set the emoji to display on this option.

PARAMETER	DESCRIPTION
emoji	Object, ID or raw string of the emoji which should be displayed on this option. TYPE: Union[Snowflakeish, Emoji, str, UndefinedType]

RETURNS	DESCRIPTION
SelectOptionBuilder	The builder object to enable chained calls.

set_is_default

set_is_default(state: bool) -> Self

Set whether this option should be selected by default.

PARAMETER	DESCRIPTION
state	Whether this option should be selected by default. TYPE: bool

RETURNS	DESCRIPTION
SelectOptionBuilder	The builder object to enable chained calls.

set_label

set_label(label: str) -> Self

Set the option's label.

PARAMETER	DESCRIPTION
label	Label to set for this option. This can be up to 100 characters long. TYPE: str

RETURNS	DESCRIPTION
SelectOptionBuilder	The builder object to enable chained calls.

set_value

set_value(value: str) -> Self

Set the option's value.

PARAMETER	DESCRIPTION
value	Value to set for this option. This can be up to 100 characters long. TYPE: str

RETURNS	DESCRIPTION
SelectOptionBuilder	The builder object to enable chained calls.

SlashCommandBuilder

Bases: CommandBuilder, SlashCommandBuilder

Builder class for slash commands.

default_member_permissions property

default_member_permissions: Union[UndefinedType, Permissions, int]

Member permissions necessary to utilize this command by default.

If 0, then it will be available for all members. Note that this doesn't affect administrators of the guild and overwrites.

description property

description: str

Command's description.

Warning

This should be inclusively between 1-100 characters in length.

description_localizations property

description_localizations: Mapping[Union[Locale, str], str]

Command's localised descriptions.

id property

id: UndefinedOr[Snowflake]

ID of this command.

is_dm_enabled property

is_dm_enabled: UndefinedOr[bool]

Whether this command is enabled in DMs with the bot.

Only applicable to globally-scoped commands.

is_nsfw property

is_nsfw: UndefinedOr[bool]

Whether this command age-restricted.

name property

name: str

Name to set for this command.

Warning

This should match the regex ^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$ in Unicode mode and must be lowercase.

name_localizations property

name_localizations: Mapping[Union[Locale, str], str]

Name localizations set for this command.

options property

options: Sequence[CommandOption]

Sequence of up to 25 of the options set for this command.

type property

type: CommandType

Type of this command.

add_option

add_option(option: CommandOption) -> Self

Add an option to this command.

Note

A command can have up to 25 options.

PARAMETER	DESCRIPTION
option	The option to add to this command. TYPE: CommandOption

RETURNS	DESCRIPTION
SlashCommandBuilder	Object of this command builder to allow for chained calls.

build

build(entity_factory: EntityFactory) -> MutableMapping[str, Any]

Build a JSON object from this builder.

PARAMETER	DESCRIPTION
entity_factory	The entity factory to use to serialize entities within this builder. TYPE: EntityFactory

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

create async

create(
    rest: RESTClient,
    application: SnowflakeishOr[PartialApplication],
    /,
    *,
    guild: UndefinedOr[SnowflakeishOr[PartialGuild]] = undefined.UNDEFINED,
) -> SlashCommand

Create this command through a REST call.

This is a shorthand for calling hikari.api.rest.RESTClient.create_slash_command with the builder's information.

PARAMETER	DESCRIPTION
rest	The REST client to use to make this request. TYPE: RESTClient
application	The application to create this command for. TYPE: SnowflakeishOr[PartialApplication]

PARAMETER	DESCRIPTION
guild	The guild to create this command for. If left undefined then this command will be declared globally. TYPE: UndefinedOr[SnowflakeishOr[PartialGuild]]

RETURNS	DESCRIPTION
SlashCommand	The created command.

set_default_member_permissions

set_default_member_permissions(
    default_member_permissions: Union[UndefinedType, int, Permissions]
) -> Self

Set the member permissions necessary to utilize this command by default.

PARAMETER	DESCRIPTION
default_member_permissions	The default member permissions to utilize this command by default. If 0, then it will be available for all members. Note that this doesn't affect administrators of the guild and overwrites. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder.

set_description

set_description(description: str) -> Self

Set the description for this command.

PARAMETER	DESCRIPTION
description	The description to set for this command. TYPE: str

RETURNS	DESCRIPTION
SlashCommandBuilder	Object of this command builder.

set_description_localizations

set_description_localizations(
    description_localizations: Mapping[Union[Locale, str], str]
) -> Self

Set the localised descriptions for this command.

PARAMETER	DESCRIPTION
description_localizations	The description localizations to set for this command. TYPE: Mapping[Union[Locale, str], str]

RETURNS	DESCRIPTION
SlashCommandBuilder	Object of this command builder.

set_id

set_id(id_: UndefinedOr[Snowflakeish]) -> Self

Set the ID of this command.

PARAMETER	DESCRIPTION
id_	The ID to set for this command. TYPE: UndefinedOr[Snowflake]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_is_dm_enabled

set_is_dm_enabled(state: UndefinedOr[bool]) -> Self

Set whether this command will be enabled in DMs with the bot.

PARAMETER	DESCRIPTION
state	Whether this command is enabled in DMs with the bot. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_is_nsfw

set_is_nsfw(state: UndefinedOr[bool]) -> Self

Set whether this command will be age-restricted.

PARAMETER	DESCRIPTION
state	Whether this command is age-restricted. TYPE: UndefinedOr[bool]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder for chained calls.

set_name

set_name(name: str) -> Self

Set the name of this command.

PARAMETER	DESCRIPTION
name	The name to set for this command. TYPE: str

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder to allow for chained calls.

set_name_localizations

set_name_localizations(
    name_localizations: Mapping[Union[Locale, str], str]
) -> Self

Set the name localizations for this command.

PARAMETER	DESCRIPTION
name_localizations	The name localizations to set for this command. TYPE: Mapping[Union[Locale, str], str]

RETURNS	DESCRIPTION
CommandBuilder	Object of this command builder.

TextInputBuilder

Bases: TextInputBuilder

Standard implementation of hikari.api.special_endpoints.TextInputBuilder.

custom_id property

custom_id: str

Developer set custom ID used for identifying this text input.

Note

This custom_id is never used in component interaction events. It is meant to be used purely for resolving components modal interactions.

is_required property

is_required: bool

Whether this text input is required to be filled-in.

label property

label: str

Label above this text input.

max_length property

max_length: int

Maximum length the text should have.

min_length property

min_length: int

Minimum length the text should have.

placeholder property

placeholder: UndefinedOr[str]

Placeholder text for when the text input is empty.

style property

style: TextInputStyle

Style to use for the text input.

type property

type: Literal[TEXT_INPUT]

Type of component this builder represents.

value property

value: UndefinedOr[str]

Pre-filled text that will be sent if the user does not write anything.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_custom_id

set_custom_id(custom_id: str) -> Self

Set the custom ID used for identifying this text input.

PARAMETER	DESCRIPTION
custom_id	Developer set custom ID used for identifying this text input. TYPE: str

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_label

set_label(label: str) -> Self

Set the label above this text input.

PARAMETER	DESCRIPTION
label	Label above this text input. TYPE: str

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_max_length

set_max_length(max_length: int) -> Self

Set the maximum length the text should have.

PARAMETER	DESCRIPTION
max_length	The maximum length the text should have. TYPE: int

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_min_length

set_min_length(min_length: int) -> Self

Set the minimum length the text should have.

PARAMETER	DESCRIPTION
min_length	The minimum length the text should have. TYPE: int

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_placeholder

set_placeholder(placeholder: UndefinedOr[str]) -> Self

Set the placeholder text for when the text input is empty.

PARAMETER	DESCRIPTION
placeholder	Placeholder text that will disappear when the user types anything. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_required

set_required(required: bool) -> Self

Set whether this text input is required to be filled-in.

PARAMETER	DESCRIPTION
required	Whether this text input is required to be filled-in. TYPE: bool

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_style

set_style(style: Union[TextInputStyle, int]) -> Self

Set the style to use for the text input.

PARAMETER	DESCRIPTION
style	Style to use for the text input. TYPE: Union[TextInputStyle, int]

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

set_value

set_value(value: UndefinedOr[str]) -> Self

Pre-filled text that will be sent if the user does not write anything.

PARAMETER	DESCRIPTION
value	Pre-filled text that will be sent if the user does not write anything. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
TextInputBuilder	The builder object to enable chained calls.

TextSelectMenuBuilder

TextSelectMenuBuilder(
    *,
    custom_id: str,
    parent: Optional[_ParentT] = None,
    options: Sequence[SelectOptionBuilder] = (),
    placeholder: UndefinedOr[str] = undefined.UNDEFINED,
    min_values: int = 0,
    max_values: int = 1,
    is_disabled: bool = False
)

Bases: SelectMenuBuilder, TextSelectMenuBuilder[_ParentT]

Builder class for text select menus.

custom_id property

custom_id: str

Developer set custom ID used for identifying interactions with this menu.

is_disabled property

is_disabled: bool

Whether the select menu should be marked as disabled.

max_values property

max_values: int

Maximum number of options which can be chosen.

Defaults to 1. Must be greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values and less than or equal to 25.

min_values property

min_values: int

Minimum number of options which must be chosen.

Defaults to 1. Must be less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values and greater than or equal to 0.

options property

options: Sequence[SelectOptionBuilder]

Sequence of the options set for this select menu.

parent property

parent: _ParentT

Parent object which initialised this builder.

placeholder property

placeholder: UndefinedOr[str]

Placeholder text to display when no options are selected.

type property

type: Union[int, ComponentType]

Type of component this builder represents.

add_option

add_option(
    label: str,
    value: str,
    /,
    *,
    description: UndefinedOr[str] = undefined.UNDEFINED,
    emoji: Union[Snowflakeish, Emoji, str, UndefinedType] = undefined.UNDEFINED,
    is_default: bool = False,
) -> Self

Add an option to this menu.

PARAMETER	DESCRIPTION
label	The user-facing name of this option, max 100 characters. TYPE: str
value	The developer defined value of this option, max 100 characters. TYPE: str
description	The option's description. This can be up to 100 characters long. TYPE: UndefinedOr[str] DEFAULT: UNDEFINED
emoji	The option's display emoji. TYPE: Union[Snowflakeish, Emoji, str, UndefinedType] DEFAULT: UNDEFINED
is_default	Whether this option should be selected by default. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
TextSelectMenuBuilder	The select menu builder to enable call chaining.

build

build() -> MutableMapping[str, Any]

Build a JSON object from this builder.

RETURNS	DESCRIPTION
MutableMapping[str, Any]	The built json object representation of this builder.

set_custom_id

set_custom_id(custom_id: str) -> Self

Set the custom ID used for identifying this menu.

PARAMETER	DESCRIPTION
custom_id	Developer set custom ID used for identifying this menu. TYPE: str

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_is_disabled

set_is_disabled(state: bool) -> Self

Set whether this option is disabled.

PARAMETER	DESCRIPTION
state	Whether this option is disabled. TYPE: bool

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_max_values

set_max_values(value: int) -> Self

Set the maximum amount of options which can be selected for this menu.

Note

This defaults to 1 if not set and must be less than or equal to 25 and greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values.

PARAMETER	DESCRIPTION
value	The maximum amount of options which can selected for this menu. TYPE: int

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_min_values

set_min_values(value: int) -> Self

Set the minimum amount of options which need to be selected for this menu.

Note

This defaults to 1 if not set and must be greater than or equal to 0 and less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values.

PARAMETER	DESCRIPTION
value	The minimum amount of options which need to be selected for this menu. TYPE: int

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

set_placeholder

set_placeholder(value: UndefinedOr[str]) -> Self

Set place-holder text to be shown when no option is selected.

PARAMETER	DESCRIPTION
value	Place-holder text to be displayed when no option is selected. Max 100 characters. TYPE: UndefinedOr[str]

RETURNS	DESCRIPTION
SelectMenuBuilder	The builder object to enable chained calls.

TypingIndicator

TypingIndicator(
    request_call: _RequestCallSig,
    channel: SnowflakeishOr[TextableChannel],
    rest_close_event: Event,
)

Bases: TypingIndicator

Result type of hikari.api.rest.RESTClient.trigger_typing.

This is an object that can either be awaited like a coroutine to trigger the typing indicator once, or an async context manager to keep triggering the typing indicator repeatedly until the context finishes.

Note

This is a helper class that is used by hikari.api.rest.RESTClient. You should only ever need to use instances of this class that are produced by that API.