tanjun.conversion#
Functions and classes used to enable more Discord oriented argument converters.
ChannelConverter
module-attribute
#
ChannelConverter = ToChannel
Deprecated alias of tanjun.conversion.ToChannel.
EmojiConverter
module-attribute
#
EmojiConverter = ToEmoji
Deprecated alias of tanjun.conversion.ToEmoji.
GuildConverter
module-attribute
#
GuildConverter = ToGuild
Deprecated alias of tanjun.conversion.ToGuild.
InviteConverter
module-attribute
#
InviteConverter = ToInvite
Deprecated alias of tanjun.conversion.ToInvite.
InviteWithMetadataConverter
module-attribute
#
InviteWithMetadataConverter = ToInviteWithMetadata
Deprecated alias of tanjun.conversion.ToInviteWithMetadata.
MemberConverter
module-attribute
#
MemberConverter = ToMember
Deprecated alias of tanjun.conversion.ToMember.
PresenceConverter
module-attribute
#
PresenceConverter = ToPresence
Deprecated alias of tanjun.conversion.ToPresence.
RoleConverter
module-attribute
#
RoleConverter = ToRole
Deprecated alias of tanjun.conversion.ToRole.
UserConverter
module-attribute
#
UserConverter = ToUser
Deprecated alias of tanjun.conversion.ToUser.
VoiceStateConverter
module-attribute
#
VoiceStateConverter = ToVoiceState
Deprecated alias of tanjun.conversion.ToVoiceState.
defragment_url
module-attribute
#
defragment_url: collections.Callable[[str], urlparse.DefragResult] = _build_url_parser(urlparse.urldefrag)
Convert an argument to a defragmented URL.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally).
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
urllib.parse.DefragResult
|
The parsed URL. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the argument couldn't be parsed. |
parse_channel_id
module-attribute
#
parse_channel_id: _IDMatcherSigProto = _make_snowflake_parser(_CHANNEL_ID_REGEX)
Parse a channel ID from a string or int value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally). |
message |
The error message to raise if the value cannot be parsed.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
hikari.Snowflake
|
The parsed channel ID. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |
parse_emoji_id
module-attribute
#
parse_emoji_id: _IDMatcherSigProto = _make_snowflake_parser(_EMOJI_ID_REGEX)
Parse an Emoji ID from a string or int value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally). |
message |
The error message to raise if the value cannot be parsed. Defaults to "No valid mention or ID found".
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
hikari.Snowflake
|
The parsed Emoji ID. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |
parse_role_id
module-attribute
#
parse_role_id: _IDMatcherSigProto = _make_snowflake_parser(_ROLE_ID_REGEX)
Parse a role ID from a string or int value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally). |
message |
The error message to raise if the value cannot be parsed. Defaults to "No valid mention or ID found".
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
hikari.Snowflake
|
The parsed role ID. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |
parse_snowflake
module-attribute
#
parse_snowflake: _IDMatcherSigProto = _make_snowflake_parser(_SNOWFLAKE_REGEX)
Parse a snowflake from a string or int value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally). |
message |
The error message to raise if the value cannot be parsed.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
hikari.Snowflake
|
The parsed snowflake. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |
parse_url
module-attribute
#
parse_url: collections.Callable[[str], urlparse.ParseResult] = _build_url_parser(urlparse.urlparse)
Convert an argument to a parsed URL.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally).
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
urllib.parse.ParseResult
|
The parsed URL. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the argument couldn't be parsed. |
parse_user_id
module-attribute
#
parse_user_id: _IDMatcherSigProto = _make_snowflake_parser(_USER_ID_REGEX)
Parse a user ID from a string or int value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally). |
message |
The error message to raise if the value cannot be parsed. Defaults to "No valid mention or ID found".
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
hikari.Snowflake
|
The parsed user ID. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |
search_channel_ids
module-attribute
#
search_channel_ids: _IDSearcherSig = _make_snowflake_searcher(_CHANNEL_ID_REGEX)
search_emoji_ids
module-attribute
#
search_emoji_ids: _IDSearcherSig = _make_snowflake_searcher(_EMOJI_ID_REGEX)
search_role_ids
module-attribute
#
search_role_ids: _IDSearcherSig = _make_snowflake_searcher(_ROLE_ID_REGEX)
search_snowflakes
module-attribute
#
search_snowflakes: _IDSearcherSig = _make_snowflake_searcher(_SNOWFLAKE_REGEX)
search_user_ids
module-attribute
#
search_user_ids: _IDSearcherSig = _make_snowflake_searcher(_USER_ID_REGEX)
split_url
module-attribute
#
split_url: collections.Callable[[str], urlparse.SplitResult] = _build_url_parser(urlparse.urlsplit)
Convert an argument to a split URL.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally).
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
urllib.parse.SplitResult
|
The split URL. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the argument couldn't be parsed. |
to_channel
module-attribute
#
to_channel: typing.Final[ToChannel] = ToChannel()
Convert user input to a hikari.channels.PartialChannel object.
to_colour
module-attribute
#
to_colour: typing.Final[collections.Callable[[_SnowflakeIsh], hikari.Color]] = to_color
Convert user input to a hikari.colors.Color object.
to_emoji
module-attribute
#
to_emoji: typing.Final[ToEmoji] = ToEmoji()
Convert user input to a cached hikari.emojis.KnownCustomEmoji object.
Note
If you just want to convert input to a hikari.emojis.Emoji, hikari.emojis.CustomEmoji or hikari.emojis.UnicodeEmoji without making any cache or REST calls then you can just use the relevant hikari.emojis.Emoji.parse, hikari.emojis.CustomEmoji.parse or hikari.emojis.UnicodeEmoji.parse methods.
to_guild
module-attribute
#
to_guild: typing.Final[ToGuild] = ToGuild()
Convert user input to a hikari.guilds.Guild object.
to_invite
module-attribute
#
to_invite: typing.Final[ToInvite] = ToInvite()
Convert user input to a cached hikari.invites.InviteWithMetadata object.
to_invite_with_metadata
module-attribute
#
to_invite_with_metadata: typing.Final[ToInviteWithMetadata] = ToInviteWithMetadata()
Convert user input to a hikari.invites.Invite object.
to_member
module-attribute
#
to_member: typing.Final[ToMember] = ToMember()
Convert user input to a hikari.guilds.Member object.
to_message
module-attribute
#
to_message: typing.Final[ToMessage] = ToMessage()
Convert user input to a hikari.messages.Message object.
to_presence
module-attribute
#
to_presence: typing.Final[ToPresence] = ToPresence()
Convert user input to a cached hikari.presences.MemberPresence.
to_role
module-attribute
#
to_role: typing.Final[ToRole] = ToRole()
Convert user input to a hikari.guilds.Role object.
to_snowflake
module-attribute
#
to_snowflake: typing.Final[collections.Callable[[_SnowflakeIsh], hikari.Snowflake]] = parse_snowflake
Convert user input to a hikari.snowflakes.Snowflake.
Note
This also range validates the input.
to_user
module-attribute
#
to_user: typing.Final[ToUser] = ToUser()
Convert user input to a hikari.users.User object.
to_voice_state
module-attribute
#
to_voice_state: typing.Final[ToVoiceState] = ToVoiceState()
Convert user input to a cached hikari.voices.VoiceState.
BaseConverter #
Base class for the standard converters.
Warning
Inheriting from this is completely unnecessary and should be avoided for people using the library unless they know what they're doing.
This is detail of the standard implementation and isn't guaranteed to work between implementations but will work for implementations which provide the standard dependency injection or special cased support for these.
While it isn't necessary to subclass this to implement your own converters since dependency injection can be used to access fields like the current Context, this class introduces some niceties around stuff like state warnings.
caches
property
#
caches: collections.Sequence[tuple[typing.Any, hikari.api.CacheComponents, hikari.Intents]]
Caches the converter takes advantage of.
This returns a tuple of async cache types and the relevant cache components which will be needed if said async cache isn't implemented.
Note
Unless tanjun.conversion.BaseConverter.requires_cache is True, these cache components aren't necessary but simply avoid the converter from falling back to REST requests.
requires_cache
property
#
requires_cache: bool
Whether this converter relies on the relevant cache stores to work.
If this is True then this converter will not function properly in an environment tanjun.conversion.BaseConverter.intents or tanjun.conversion.BaseConverter.cache_components isn't satisfied and will never fallback to REST requests.
check_client #
check_client(client, parent_name)
Check that this converter will work with the given client.
This never raises any errors but simply warns the user if the converter is not compatible with the given client.
PARAMETER | DESCRIPTION |
---|---|
client |
The client to check against. |
parent_name |
The name of the converter's parent, used for warning messages.
TYPE:
|
ToChannel #
Bases: BaseConverter
Standard converter for channels mentions/IDs.
For a standard instance of this see tanjun.conversion.to_channel.
__init__ #
__init__(*, allowed_types=None, include_dms=True)
Initialise a to channel converter.
PARAMETER | DESCRIPTION |
---|---|
allowed_types |
Collection of channel types and classes to allow. If this is None then all channel types will be allowed.
TYPE:
|
include_dms |
Whether to include DM channels in the results. May lead to a lot of extra fallbacks to REST requests if the client doesn't have a registered async cache for DMs.
TYPE:
|
ToEmoji #
Bases: BaseConverter
Standard converter for custom emojis.
For a standard instance of this see tanjun.conversion.to_emoji.
Note
If you just want to convert inpute to a hikari.emojis.Emoji, hikari.emojis.CustomEmoji or hikari.emojis.UnicodeEmoji without making any cache or REST calls then you can just use the relevant Emoji.parse, CustomEmoji.parse or UnicodeEmoji.parse methods.
ToGuild #
Bases: BaseConverter
Stanard converter for guilds.
For a standard instance of this see tanjun.conversion.to_guild.
ToInvite #
ToInviteWithMetadata #
Bases: BaseConverter
Standard converter for invites with metadata.
For a standard instance of this see tanjun.conversion.to_invite_with_metadata.
Note
Unlike tanjun.conversion.InviteConverter, this converter is cache dependent.
ToMember #
Bases: BaseConverter
Standard converter for guild members.
For a standard instance of this see tanjun.conversion.to_member.
This converter allows both mentions, raw IDs and partial usernames/nicknames and only works within a guild context.
ToMessage #
Bases: BaseConverter
Standard converter for messages.
For a standard instance of this see tanjun.conversion.to_message.
ToPresence #
Bases: BaseConverter
Standard converter for presences.
For a standard instance of this see tanjun.conversion.to_presence.
This converter is cache dependent and only works in a guild context.
ToRole #
Bases: BaseConverter
Standard converter for guild roles.
For a standard instance of this see tanjun.conversion.to_role.
ToUser #
Bases: BaseConverter
Standard converter for users.
For a standard instance of this see tanjun.conversion.to_user.
ToVoiceState #
Bases: BaseConverter
Standard converter for voice states.
For a standard instance of this see tanjun.conversion.to_voice_state.
Note
This converter is cache dependent and only works in a guild context.
from_datetime #
from_datetime(value, /, *, style='f')
Format a datetime as Discord's datetime format.
More information on this format can be found at https://discord.com/developers/docs/reference#message-formatting-timestamp-styles
PARAMETER | DESCRIPTION |
---|---|
value |
The datetime to format. If a timedelta is passed here then this is treated as a date that's relative to the current time. |
style |
The style to use. The valid styles can be found at https://discord.com/developers/docs/reference#message-formatting-formats. This is always "R" when
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
str
|
The formatted datetime. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the provided datetime is timezone naive. If an invalid style is provided. |
parse_message_id #
parse_message_id(value, /, *, message='No valid message link or ID found')
Parse a user ID from a string or int value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse (this argument can only be passed positionally).
TYPE:
|
message |
The error message to raise if the value cannot be parsed.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
tuple[hikari.Snowflake | None, hikari.Snowflake]
|
The parsed channel and message IDs. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |
to_bool #
to_bool(value)
Convert user string input into a boolean value.
PARAMETER | DESCRIPTION |
---|---|
value |
The value to convert.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
bool
|
The converted value. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be converted. |
to_datetime #
to_datetime(value)
Parse a datetime from Discord's datetime format.
More information on this format can be found at https://discord.com/developers/docs/reference#message-formatting-timestamp-styles
PARAMETER | DESCRIPTION |
---|---|
value |
The value to parse.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
datetime.datetime
|
The parsed datetime. |
RAISES | DESCRIPTION |
---|---|
ValueError
|
If the value cannot be parsed. |