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
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
.
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. |
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.
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.
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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.
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.
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 set for this command.
build
#
build(_: EntityFactory) -> MutableMapping[str, Any]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
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:
|
application |
The application to create this command for.
TYPE:
|
PARAMETER | DESCRIPTION |
---|---|
guild |
The guild to create this command for. If left undefined then this command will be declared globally.
TYPE:
|
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
TYPE:
|
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:
|
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:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
CommandBuilder
|
Object of this command builder to allow for chained calls. |
set_name_localizations
#
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.
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.
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 set for this command.
build
#
build(_: EntityFactory) -> MutableMapping[str, Any]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
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:
|
application |
The application to create this command for.
TYPE:
|
PARAMETER | DESCRIPTION |
---|---|
guild |
The guild to create this command for. If left undefined then this command will be declared globally.
TYPE:
|
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
TYPE:
|
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:
|
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:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
CommandBuilder
|
Object of this command builder to allow for chained calls. |
set_name_localizations
#
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
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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:
Creating a guild with an icon:
from hikari.files import WebResourceStream
guild_builder = rest.guild_builder("My Server!")
guild_builder.icon = WebResourceStream("cat.png", "http://...")
guild = await guild_builder.create()
Adding roles to your guild:
from hikari.permissions import Permissions
guild_builder = rest.guild_builder("My Server!")
everyone_role_id = guild_builder.add_role("@everyone")
admin_role_id = guild_builder.add_role("Admins", permissions=Permissions.ADMINISTRATOR)
await guild_builder.create()
Warning
The first role must always be the @everyone
role.
Adding a text channel to your guild:
guild_builder = rest.guild_builder("My Server!")
category_id = guild_builder.add_category("My safe place")
channel_id = guild_builder.add_text_channel("general", parent_id=category_id)
await guild_builder.create()
default_message_notifications
class-attribute
instance-attribute
#
default_message_notifications: UndefinedOr[GuildMessageNotificationsLevel] = (
field(default=UNDEFINED)
)
Default message notification level that can be overwritten.
If not overridden, this will use the Discord default level.
explicit_content_filter_level
class-attribute
instance-attribute
#
explicit_content_filter_level: UndefinedOr[GuildExplicitContentFilterLevel] = (
field(default=UNDEFINED)
)
Explicit content filter level that can be overwritten.
If not overridden, this will use the Discord default level.
icon
class-attribute
instance-attribute
#
icon: UndefinedOr[Resourceish] = field(default=UNDEFINED)
Guild icon to use that can be overwritten.
If not overridden, the guild will not have an icon.
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:
|
PARAMETER | DESCRIPTION |
---|---|
position |
If provided, the position of the category.
TYPE:
|
permission_overwrites |
If provided, the permission overwrites for the category.
TYPE:
|
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:
|
PARAMETER | DESCRIPTION |
---|---|
permissions |
If provided, the permissions for the role.
TYPE:
|
color |
If provided, the role's color.
TYPE:
|
colour |
An alias for
TYPE:
|
hoist |
If provided, whether to hoist the role.
TYPE:
|
mentionable |
If provided, whether to make the role mentionable.
TYPE:
|
position |
If provided, the position of the role.
TYPE:
|
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 |
TypeError
|
If you specify both |
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:
|
PARAMETER | DESCRIPTION |
---|---|
position |
If provided, the position of the channel (relative to the category, if any).
TYPE:
|
user_limit |
If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit.
TYPE:
|
bitrate |
If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers.
TYPE:
|
permission_overwrites |
If provided, the permission overwrites for the channel.
TYPE:
|
region |
If provided, the voice region to for this channel. Passing
TYPE:
|
parent_id |
The ID of the category to create the channel under.
TYPE:
|
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:
|
PARAMETER | DESCRIPTION |
---|---|
position |
If provided, the position of the channel (relative to the category, if any).
TYPE:
|
topic |
If provided, the channels topic. Maximum 1024 characters.
TYPE:
|
nsfw |
If provided, whether to mark the channel as NSFW.
TYPE:
|
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:
|
permission_overwrites |
If provided, the permission overwrites for the channel.
TYPE:
|
parent_id |
The ID of the category to create the channel under.
TYPE:
|
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:
|
PARAMETER | DESCRIPTION |
---|---|
position |
If provided, the position of the channel (relative to the category, if any).
TYPE:
|
user_limit |
If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit.
TYPE:
|
bitrate |
If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers.
TYPE:
|
video_quality_mode |
If provided, the new video quality mode for the channel.
TYPE:
|
permission_overwrites |
If provided, the permission overwrites for the channel.
TYPE:
|
region |
If provided, the voice region to for this channel. Passing
TYPE:
|
parent_id |
The ID of the category to create the channel under.
TYPE:
|
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
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
.
build
#
build(
_: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
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. |
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:
|
flags
property
#
flags: Union[UndefinedType, int, MessageFlag]
Message flags this response should have.
Note
As of writing the only message flags which can be set here are
hikari.messages.MessageFlag.EPHEMERAL
, hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS
and hikari.messages.MessageFlag.SUPPRESS_EMBEDS
.
build
#
build(
_: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
typing.Tuple[typing.MutableMapping[str, typing.Any], typing.Sequence[files.Resource[Files.AsyncReader]]
|
A tuple of the built json object representation of this builder and a sequence of up to 10 files to send with the response. |
set_flags
#
set_flags(flags: Union[UndefinedType, int, MessageFlag]) -> Self
Set message flags for this response.
Note
As of writing, the only message flags which can be set are hikari.messages.MessageFlag.EPHEMERAL
hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS
and
hikari.messages.MessageFlag.SUPPRESS_EMBEDS
.
PARAMETER | DESCRIPTION |
---|---|
flags |
The message flags to set for this response.
TYPE:
|
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:
|
PARAMETER | DESCRIPTION |
---|---|
content |
The content of this response, if supplied. This follows the same rules as "content" on create message.
TYPE:
|
attachments
property
#
attachments: UndefinedNoneOr[Sequence[Resourceish]]
Sequence of up to 10 attachments to send with the message.
components
property
#
components: UndefinedNoneOr[Sequence[ComponentBuilder]]
Sequence of up to 5 component builders to send in this response.
embeds
property
#
embeds: UndefinedNoneOr[Sequence[Embed]]
Sequence of up to 10 of the embeds included in this response.
flags
property
#
flags: Union[UndefinedType, int, MessageFlag]
Message flags this response should have.
Note
As of writing the only message flags which can be set here are
hikari.messages.MessageFlag.EPHEMERAL
,
hikari.messages.MessageFlag.SUPPRESS_NOTIFICATIONS
and hikari.messages.MessageFlag.SUPPRESS_EMBEDS
.
is_tts
property
#
is_tts: UndefinedOr[bool]
Whether this response's content should be treated as text-to-speech.
mentions_everyone
property
#
mentions_everyone: UndefinedOr[bool]
Whether @everyone and @here mentions should be enabled for this response.
role_mentions
property
#
role_mentions: UndefinedOr[Union[SnowflakeishSequence[PartialRole], bool]]
Whether and what role mentions should be enabled for this response.
Either a sequence of object/IDs of the roles mentions should be enabled
for, False
or hikari.undefined.UNDEFINED
to disallow any
role mentions or True
to allow all role mentions.
user_mentions
property
#
user_mentions: UndefinedOr[Union[SnowflakeishSequence[PartialUser], bool]]
Whether and what user mentions should be enabled for this response.
Either a sequence of object/IDs of the users mentions should be enabled
for, False
or hikari.undefined.UNDEFINED
to disallow any
user mentions or True
to allow all user mentions.
add_attachment
#
add_attachment(attachment: Resourceish) -> Self
Add an attachment to this response.
PARAMETER | DESCRIPTION |
---|---|
attachment |
The attachment to add.
TYPE:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
InteractionMessageBuilder
|
Object of this builder to allow for chained calls. |
build
#
build(
entity_factory: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
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 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:
|
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:
|
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:
|
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,
TYPE:
|
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:
|
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,
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
InteractionMessageBuilder
|
Object of this builder to allow for chained calls. |
InteractionModalBuilder
#
Bases: InteractionModalBuilder
Standard implementation of hikari.api.special_endpoints.InteractionModalBuilder
.
components
property
#
components: Sequence[ComponentBuilder]
Sequence of component builders to send in this modal.
custom_id
property
#
custom_id: str
Developer set custom ID used for identifying interactions with this modal.
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:
|
build
#
build(
entity_factory: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
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. |
InteractionPremiumRequiredBuilder
#
Bases: InteractionPremiumRequiredBuilder
Standard implementation of hikari.api.special_endpoints.InteractionPremiumRequiredBuilder
.
build
#
build(
entity_factory: EntityFactory,
) -> Tuple[MutableMapping[str, Any], Sequence[Resource[AsyncReader]]]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
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: Union[Snowflakeish, Emoji, str, UndefinedType]
Emoji which should appear on this button.
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.
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:
|
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:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
ButtonBuilder
|
The builder object to enable chained calls. |
LinkButtonBuilder
#
Bases: _ButtonBuilder
, LinkButtonBuilder
Builder class for link buttons.
emoji
property
#
emoji: Union[Snowflakeish, Emoji, str, UndefinedType]
Emoji which should appear on this button.
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.
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:
|
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:
|
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:
|
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
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values until any conditions are not matched. |
MessageActionRowBuilder
#
Bases: MessageActionRowBuilder
Standard implementation of hikari.api.special_endpoints.MessageActionRowBuilder
.
components
property
#
components: Sequence[ComponentBuilder]
Sequence of the component builders registered within this action row.
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:
|
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:
|
placeholder |
Placeholder text to show when no entries have been selected.
TYPE:
|
min_values |
The minimum amount of entries which need to be selected.
TYPE:
|
max_values |
The maximum amount of entries which can be selected.
TYPE:
|
is_disabled |
Whether this select menu should be marked as disabled.
TYPE:
|
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:
|
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:
|
custom_id |
The developer-defined custom identifier used to identify which button triggered component interactions.
TYPE:
|
emoji |
The button's display emoji.
TYPE:
|
label |
The button's display label.
TYPE:
|
is_disabled |
Whether the button should be marked as disabled.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
ActionRowBuilder
|
The action row builder to enable chained calls. |
add_link_button
#
add_link_button(
url: str,
/,
*,
emoji: Union[Snowflakeish, Emoji, str, UndefinedType] = undefined.UNDEFINED,
label: UndefinedOr[str] = undefined.UNDEFINED,
is_disabled: bool = False,
) -> Self
Add a link button component to this action row builder.
Either emoji
or label
(exclusively) must be provided to be the button's
displayed label.
PARAMETER | DESCRIPTION |
---|---|
url |
The URL the link button should redirect to.
TYPE:
|
emoji |
The button's display emoji.
TYPE:
|
label |
The button's display label.
TYPE:
|
is_disabled |
Whether the button should be marked as disabled.
TYPE:
|
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:
|
custom_id |
A developer-defined custom identifier used to identify which menu triggered component interactions.
TYPE:
|
placeholder |
Placeholder text to show when no entries have been selected.
TYPE:
|
min_values |
The minimum amount of entries which need to be selected.
TYPE:
|
max_values |
The maximum amount of entries which can be selected.
TYPE:
|
is_disabled |
Whether this select menu should be marked as disabled.
TYPE:
|
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:
|
placeholder |
Placeholder text to show when no entries have been selected.
TYPE:
|
min_values |
The minimum amount of entries which need to be selected.
TYPE:
|
max_values |
The maximum amount of entries which can be selected.
TYPE:
|
is_disabled |
Whether this select menu should be marked as disabled.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextSelectMenuBuilder
|
The text select menu builder.
|
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
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values until any conditions are not matched. |
ModalActionRowBuilder
#
Bases: ModalActionRowBuilder
Standard implementation of hikari.api.special_endpoints.ModalActionRowBuilder
.
components
property
#
components: Sequence[ComponentBuilder]
Sequence of the component builders registered within this action row.
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:
|
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:
|
label |
Label above this text input.
TYPE:
|
style |
The text input's style.
TYPE:
|
placeholder |
Placeholder text to display when the text input is empty.
TYPE:
|
value |
Default text to pre-fill the field with.
TYPE:
|
required |
Whether text must be supplied for this text input.
TYPE:
|
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:
|
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:
|
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
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values until any conditions are not matched. |
ReactorIterator
#
ReactorIterator(
entity_factory: EntityFactory,
request_call: _RequestCallSig,
channel: SnowflakeishOr[TextableChannel],
message: SnowflakeishOr[PartialMessage],
emoji: str,
)
Bases: BufferedLazyIterator['users.User']
Implementation of an iterator for message reactions.
awaiting
#
awaiting(window_size: int = 10) -> LazyIterator[ValueT]
Await each item concurrently in a fixed size window.
Warning
Setting a large window size, or setting it to 0 to await everything
is a dangerous thing to do if you are making API calls. Some
endpoints will get ratelimited and cause a backup of waiting
tasks, others may begin to spam global rate limits instead
(the fetch_user
endpoint seems to be notorious for doing this).
Note
This call assumes that the iterator contains awaitable values as
input. MyPy cannot detect this nicely, so any cast is forced
internally.
If the item is not awaitable, you will receive a
TypeError
instead.
You have been warned. You cannot escape the ways of the duck type
young grasshopper.
PARAMETER | DESCRIPTION |
---|---|
window_size |
The window size of how many tasks to await at once. You can set this
to
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values until any conditions are not matched. |
ScheduledEventUserIterator
#
ScheduledEventUserIterator(
entity_factory: EntityFactory,
request_call: _RequestCallSig,
newest_first: bool,
first_id: str,
guild: SnowflakeishOr[PartialGuild],
event: SnowflakeishOr[ScheduledEvent],
)
Bases: BufferedLazyIterator['scheduled_events.ScheduledEventUser']
Implementation of an iterator for retrieving the users subscribed to a scheduled event.
awaiting
#
awaiting(window_size: int = 10) -> LazyIterator[ValueT]
Await each item concurrently in a fixed size window.
Warning
Setting a large window size, or setting it to 0 to await everything
is a dangerous thing to do if you are making API calls. Some
endpoints will get ratelimited and cause a backup of waiting
tasks, others may begin to spam global rate limits instead
(the fetch_user
endpoint seems to be notorious for doing this).
Note
This call assumes that the iterator contains awaitable values as
input. MyPy cannot detect this nicely, so any cast is forced
internally.
If the item is not awaitable, you will receive a
TypeError
instead.
You have been warned. You cannot escape the ways of the duck type
young grasshopper.
PARAMETER | DESCRIPTION |
---|---|
window_size |
The window size of how many tasks to await at once. You can set this
to
TYPE:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[Sequence[ValueT]]
|
|
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:
|
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
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
|
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:
|
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. |
for_each
async
#
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:
|
Examples:
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 |
RETURNS | DESCRIPTION |
---|---|
LazyIterator[AnotherValueT]
|
|
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:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values once a condition has been met. All items before this are discarded. |
sort
async
#
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
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
TYPE:
|
**attrs |
Alternative to passing 2-tuples. Cannot specify nested attributes using this method.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
LazyIterator[ValueT]
|
LazyIterator that only emits values until any conditions are not matched. |
SelectMenuBuilder
#
Bases: SelectMenuBuilder
Builder class for select menus.
custom_id
property
#
custom_id: str
Developer set custom ID used for identifying interactions with this menu.
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.
build
#
build() -> MutableMapping[str, Any]
Build a JSON object from this builder.
RETURNS | DESCRIPTION |
---|---|
MutableMapping[str, Any]
|
The built json object representation of this builder. |
set_custom_id
#
set_custom_id(custom_id: str) -> Self
Set the custom ID used for identifying this menu.
PARAMETER | DESCRIPTION |
---|---|
custom_id |
Developer set custom ID used for identifying this menu.
TYPE:
|
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:
|
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:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
SelectMenuBuilder
|
The builder object to enable chained calls. |
SelectOptionBuilder
#
Bases: SelectOptionBuilder
Builder class for select menu options.
emoji
property
#
emoji: Union[Snowflakeish, Emoji, str, UndefinedType]
Emoji which should appear on this option.
build
#
build() -> MutableMapping[str, Any]
Build a JSON object from this builder.
RETURNS | DESCRIPTION |
---|---|
MutableMapping[str, Any]
|
The built json object representation of this builder. |
set_description
#
set_description(value: UndefinedOr[str]) -> Self
Set the option's description.
PARAMETER | DESCRIPTION |
---|---|
value |
Description to set for this option. This can be up to 100 characters long.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SelectOptionBuilder
|
The builder object to enable chained calls. |
set_emoji
#
set_emoji(emoji: Union[Snowflakeish, Emoji, str, UndefinedType]) -> Self
Set the emoji to display on this option.
PARAMETER | DESCRIPTION |
---|---|
emoji |
Object, ID or raw string of the emoji which should be displayed on this option.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SelectOptionBuilder
|
The builder object to enable chained calls. |
set_is_default
#
set_is_default(state: bool) -> Self
Set whether this option should be selected by default.
PARAMETER | DESCRIPTION |
---|---|
state |
Whether this option should be selected by default.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SelectOptionBuilder
|
The builder object to enable chained calls. |
set_label
#
set_label(label: str) -> Self
Set the option's label.
PARAMETER | DESCRIPTION |
---|---|
label |
Label to set for this option. This can be up to 100 characters long.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SelectOptionBuilder
|
The builder object to enable chained calls. |
set_value
#
set_value(value: str) -> Self
Set the option's value.
PARAMETER | DESCRIPTION |
---|---|
value |
Value to set for this option. This can be up to 100 characters long.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SelectOptionBuilder
|
The builder object to enable chained calls. |
SlashCommandBuilder
#
Bases: CommandBuilder
, SlashCommandBuilder
Builder class for slash commands.
default_member_permissions
property
#
default_member_permissions: Union[UndefinedType, Permissions, int]
Member permissions necessary to utilize this command by default.
If 0
, then it will be available for all members. Note that this doesn't affect
administrators of the guild and overwrites.
description
property
#
description: str
Command's description.
Warning
This should be inclusively between 1-100 characters in length.
description_localizations
property
#
Command's localised descriptions.
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.
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 set for this command.
options
property
#
options: Sequence[CommandOption]
Sequence of up to 25 of the options set for this command.
add_option
#
add_option(option: CommandOption) -> Self
Add an option to this command.
Note
A command can have up to 25 options.
PARAMETER | DESCRIPTION |
---|---|
option |
The option to add to this command.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SlashCommandBuilder
|
Object of this command builder to allow for chained calls. |
build
#
build(entity_factory: EntityFactory) -> MutableMapping[str, Any]
Build a JSON object from this builder.
PARAMETER | DESCRIPTION |
---|---|
entity_factory |
The entity factory to use to serialize entities within this builder.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
MutableMapping[str, Any]
|
The built json object representation of this builder. |
create
async
#
create(
rest: RESTClient,
application: SnowflakeishOr[PartialApplication],
/,
*,
guild: UndefinedOr[SnowflakeishOr[PartialGuild]] = undefined.UNDEFINED,
) -> SlashCommand
Create this command through a REST call.
This is a shorthand for calling hikari.api.rest.RESTClient.create_slash_command
with the builder's information.
PARAMETER | DESCRIPTION |
---|---|
rest |
The REST client to use to make this request.
TYPE:
|
application |
The application to create this command for.
TYPE:
|
PARAMETER | DESCRIPTION |
---|---|
guild |
The guild to create this command for. If left undefined then this command will be declared globally.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SlashCommand
|
The created command. |
set_default_member_permissions
#
set_default_member_permissions(
default_member_permissions: Union[UndefinedType, int, Permissions]
) -> Self
Set the member permissions necessary to utilize this command by default.
PARAMETER | DESCRIPTION |
---|---|
default_member_permissions |
The default member permissions to utilize this command by default. If
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
CommandBuilder
|
Object of this command builder. |
set_description
#
set_description(description: str) -> Self
Set the description for this command.
PARAMETER | DESCRIPTION |
---|---|
description |
The description to set for this command.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
SlashCommandBuilder
|
Object of this command builder. |
set_description_localizations
#
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:
|
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:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
CommandBuilder
|
Object of this command builder to allow for chained calls. |
set_name_localizations
#
TextInputBuilder
#
Bases: TextInputBuilder
Standard implementation of hikari.api.special_endpoints.TextInputBuilder
.
custom_id
property
#
custom_id: str
Developer set custom ID used for identifying this text input.
Note
This custom_id is never used in component interaction events. It is meant to be used purely for resolving components modal interactions.
placeholder
property
#
placeholder: UndefinedOr[str]
Placeholder text for when the text input is empty.
value
property
#
value: UndefinedOr[str]
Pre-filled text that will be sent if the user does not write anything.
build
#
build() -> MutableMapping[str, Any]
Build a JSON object from this builder.
RETURNS | DESCRIPTION |
---|---|
MutableMapping[str, Any]
|
The built json object representation of this builder. |
set_custom_id
#
set_custom_id(custom_id: str) -> Self
Set the custom ID used for identifying this text input.
PARAMETER | DESCRIPTION |
---|---|
custom_id |
Developer set custom ID used for identifying this text input.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_label
#
set_label(label: str) -> Self
Set the label above this text input.
PARAMETER | DESCRIPTION |
---|---|
label |
Label above this text input.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_max_length
#
set_max_length(max_length: int) -> Self
Set the maximum length the text should have.
PARAMETER | DESCRIPTION |
---|---|
max_length |
The maximum length the text should have.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_min_length
#
set_min_length(min_length: int) -> Self
Set the minimum length the text should have.
PARAMETER | DESCRIPTION |
---|---|
min_length |
The minimum length the text should have.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_placeholder
#
set_placeholder(placeholder: UndefinedOr[str]) -> Self
Set the placeholder text for when the text input is empty.
PARAMETER | DESCRIPTION |
---|---|
placeholder |
Placeholder text that will disappear when the user types anything.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_required
#
set_required(required: bool) -> Self
Set whether this text input is required to be filled-in.
PARAMETER | DESCRIPTION |
---|---|
required |
Whether this text input is required to be filled-in.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_style
#
set_style(style: Union[TextInputStyle, int]) -> Self
Set the style to use for the text input.
PARAMETER | DESCRIPTION |
---|---|
style |
Style to use for the text input. |
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
set_value
#
set_value(value: UndefinedOr[str]) -> Self
Pre-filled text that will be sent if the user does not write anything.
PARAMETER | DESCRIPTION |
---|---|
value |
Pre-filled text that will be sent if the user does not write anything.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextInputBuilder
|
The builder object to enable chained calls. |
TextSelectMenuBuilder
#
TextSelectMenuBuilder(
*,
custom_id: str,
parent: Optional[_ParentT] = None,
options: Sequence[SelectOptionBuilder] = (),
placeholder: UndefinedOr[str] = undefined.UNDEFINED,
min_values: int = 0,
max_values: int = 1,
is_disabled: bool = False
)
Bases: SelectMenuBuilder
, TextSelectMenuBuilder[_ParentT]
Builder class for text select menus.
custom_id
property
#
custom_id: str
Developer set custom ID used for identifying interactions with this menu.
max_values
property
#
max_values: int
Maximum number of options which can be chosen.
Defaults to 1.
Must be greater than or equal to hikari.api.special_endpoints.SelectMenuBuilder.min_values
and
less than or equal to 25.
min_values
property
#
min_values: int
Minimum number of options which must be chosen.
Defaults to 1.
Must be less than or equal to hikari.api.special_endpoints.SelectMenuBuilder.max_values
and greater
than or equal to 0.
options
property
#
options: Sequence[SelectOptionBuilder]
Sequence of the options set for this select menu.
placeholder
property
#
placeholder: UndefinedOr[str]
Placeholder text to display when no options are selected.
add_option
#
add_option(
label: str,
value: str,
/,
*,
description: UndefinedOr[str] = undefined.UNDEFINED,
emoji: Union[Snowflakeish, Emoji, str, UndefinedType] = undefined.UNDEFINED,
is_default: bool = False,
) -> Self
Add an option to this menu.
PARAMETER | DESCRIPTION |
---|---|
label |
The user-facing name of this option, max 100 characters.
TYPE:
|
value |
The developer defined value of this option, max 100 characters.
TYPE:
|
description |
The option's description. This can be up to 100 characters long.
TYPE:
|
emoji |
The option's display emoji.
TYPE:
|
is_default |
Whether this option should be selected by default.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
TextSelectMenuBuilder
|
The select menu builder to enable call chaining. |
build
#
build() -> MutableMapping[str, Any]
Build a JSON object from this builder.
RETURNS | DESCRIPTION |
---|---|
MutableMapping[str, Any]
|
The built json object representation of this builder. |
set_custom_id
#
set_custom_id(custom_id: str) -> Self
Set the custom ID used for identifying this menu.
PARAMETER | DESCRIPTION |
---|---|
custom_id |
Developer set custom ID used for identifying this menu.
TYPE:
|
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:
|
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:
|
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:
|
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:
|
RETURNS | DESCRIPTION |
---|---|
SelectMenuBuilder
|
The builder object to enable chained calls. |
TypingIndicator
#
TypingIndicator(
request_call: _RequestCallSig,
channel: SnowflakeishOr[TextableChannel],
rest_close_event: Event,
)
Bases: TypingIndicator
Result type of hikari.api.rest.RESTClient.trigger_typing
.
This is an object that can either be awaited like a coroutine to trigger the typing indicator once, or an async context manager to keep triggering the typing indicator repeatedly until the context finishes.
Note
This is a helper class that is used by hikari.api.rest.RESTClient
.
You should only ever need to use instances of this class that are
produced by that API.