Skip to content

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 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 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 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 of this command.

build #

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 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 of this command.

build #

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

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

Autocomplete choices.

type property #

Type of this response.

build #

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 #

Message flags this response should have.

type property #

Type of this response.

build #

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.

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 #

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

components property #

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

content property #

content: UndefinedNoneOr[str]

Response's message content.

embeds property #

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

flags property #

Message flags this response should have.

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 #

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 of this response.

user_mentions property #

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

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

InteractionPremiumRequiredBuilder #

Bases: InteractionPremiumRequiredBuilder

Standard implementation of hikari.api.special_endpoints.InteractionPremiumRequiredBuilder.

type property #

Type of this response.

build #

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.

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

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

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

Sequence of the component builders registered within this action row.

type property #

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(
    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 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 #

Sequence of the component builders registered within this action row.

type property #

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)