Skip to content

tanjun.conversion#

Functions and classes used to enable more Discord oriented argument converters.

ChannelConverter = ToChannel module-attribute #

Deprecated alias of tanjun.conversion.ToChannel.

EmojiConverter = ToEmoji module-attribute #

Deprecated alias of tanjun.conversion.ToEmoji.

GuildConverter = ToGuild module-attribute #

Deprecated alias of tanjun.conversion.ToGuild.

InviteConverter = ToInvite module-attribute #

Deprecated alias of tanjun.conversion.ToInvite.

InviteWithMetadataConverter = ToInviteWithMetadata module-attribute #

MemberConverter = ToMember module-attribute #

Deprecated alias of tanjun.conversion.ToMember.

PresenceConverter = ToPresence module-attribute #

Deprecated alias of tanjun.conversion.ToPresence.

RoleConverter = ToRole module-attribute #

Deprecated alias of tanjun.conversion.ToRole.

UserConverter = ToUser module-attribute #

Deprecated alias of tanjun.conversion.ToUser.

VoiceStateConverter = ToVoiceState module-attribute #

Deprecated alias of tanjun.conversion.ToVoiceState.

defragment_url: collections.Callable[[str], urlparse.DefragResult] = _build_url_parser(urlparse.urldefrag) module-attribute #

Convert an argument to a defragmented URL.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str

RETURNS DESCRIPTION
urllib.parse.DefragResult

The parsed URL.

RAISES DESCRIPTION
ValueError

If the argument couldn't be parsed.

parse_channel_id: _IDMatcherSigProto = _make_snowflake_parser(_CHANNEL_ID_REGEX) module-attribute #

Parse a channel ID from a string or int value.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

message

The error message to raise if the value cannot be parsed.

TYPE: str

RETURNS DESCRIPTION
hikari.Snowflake

The parsed channel ID.

RAISES DESCRIPTION
ValueError

If the value cannot be parsed.

parse_emoji_id: _IDMatcherSigProto = _make_snowflake_parser(_EMOJI_ID_REGEX) module-attribute #

Parse an Emoji ID from a string or int value.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

message

The error message to raise if the value cannot be parsed.

Defaults to "No valid mention or ID found".

TYPE: str

RETURNS DESCRIPTION
hikari.Snowflake

The parsed Emoji ID.

RAISES DESCRIPTION
ValueError

If the value cannot be parsed.

parse_role_id: _IDMatcherSigProto = _make_snowflake_parser(_ROLE_ID_REGEX) module-attribute #

Parse a role ID from a string or int value.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

message

The error message to raise if the value cannot be parsed.

Defaults to "No valid mention or ID found".

TYPE: str

RETURNS DESCRIPTION
hikari.Snowflake

The parsed role ID.

RAISES DESCRIPTION
ValueError

If the value cannot be parsed.

parse_snowflake: _IDMatcherSigProto = _make_snowflake_parser(_SNOWFLAKE_REGEX) module-attribute #

Parse a snowflake from a string or int value.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

message

The error message to raise if the value cannot be parsed.

TYPE: str

RETURNS DESCRIPTION
hikari.Snowflake

The parsed snowflake.

RAISES DESCRIPTION
ValueError

If the value cannot be parsed.

parse_url: collections.Callable[[str], urlparse.ParseResult] = _build_url_parser(urlparse.urlparse) module-attribute #

Convert an argument to a parsed URL.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str

RETURNS DESCRIPTION
urllib.parse.ParseResult

The parsed URL.

RAISES DESCRIPTION
ValueError

If the argument couldn't be parsed.

parse_user_id: _IDMatcherSigProto = _make_snowflake_parser(_USER_ID_REGEX) module-attribute #

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: str | int | float

message

The error message to raise if the value cannot be parsed.

Defaults to "No valid mention or ID found".

TYPE: str

RETURNS DESCRIPTION
hikari.Snowflake

The parsed user ID.

RAISES DESCRIPTION
ValueError

If the value cannot be parsed.

search_channel_ids: _IDSearcherSig = _make_snowflake_searcher(_CHANNEL_ID_REGEX) module-attribute #

Get the channel IDs in a string.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

RETURNS DESCRIPTION
list[hikari.Snowflake]

List of the channel IDs in the string.

search_emoji_ids: _IDSearcherSig = _make_snowflake_searcher(_EMOJI_ID_REGEX) module-attribute #

Get the emoji IDs in a string.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

RETURNS DESCRIPTION
list[hikari.Snowflake]

List of the emoji IDs in the string.

search_role_ids: _IDSearcherSig = _make_snowflake_searcher(_ROLE_ID_REGEX) module-attribute #

Get the role IDs in a string.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

RETURNS DESCRIPTION
list[hikari.Snowflake]

List of the role IDs in the string.

search_snowflakes: _IDSearcherSig = _make_snowflake_searcher(_SNOWFLAKE_REGEX) module-attribute #

Get the snowflakes in a string.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

RETURNS DESCRIPTION
list[hikari.Snowflake]

List of the snowflakes in the string.

search_user_ids: _IDSearcherSig = _make_snowflake_searcher(_USER_ID_REGEX) module-attribute #

Get the user IDs in a string.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str | int | float

RETURNS DESCRIPTION
list[hikari.Snowflake]

List of the user IDs in the string.

split_url: collections.Callable[[str], urlparse.SplitResult] = _build_url_parser(urlparse.urlsplit) module-attribute #

Convert an argument to a split URL.

PARAMETER DESCRIPTION
value

The value to parse (this argument can only be passed positionally).

TYPE: str

RETURNS DESCRIPTION
urllib.parse.SplitResult

The split URL.

RAISES DESCRIPTION
ValueError

If the argument couldn't be parsed.

to_channel: typing.Final[ToChannel] = ToChannel() module-attribute #

Convert user input to a hikari.channels.PartialChannel object.

to_colour: typing.Final[collections.Callable[[_ArgumentT], hikari.Color]] = to_color module-attribute #

Convert user input to a hikari.colors.Color object.

to_emoji: typing.Final[ToEmoji] = ToEmoji() module-attribute #

Convert user input to a cached hikari.emojis.KnownCustomEmoji object.

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 hikari.emojis.Emoji.parse, hikari.emojis.CustomEmoji.parse or hikari.emojis.UnicodeEmoji.parse methods.

to_guild: typing.Final[ToGuild] = ToGuild() module-attribute #

Convert user input to a hikari.guilds.Guild object.

to_invite: typing.Final[ToInvite] = ToInvite() module-attribute #

Convert user input to a cached hikari.invites.InviteWithMetadata object.

to_invite_with_metadata: typing.Final[ToInviteWithMetadata] = ToInviteWithMetadata() module-attribute #

Convert user input to a hikari.invites.Invite object.

to_member: typing.Final[ToMember] = ToMember() module-attribute #

Convert user input to a hikari.guilds.Member object.

to_message: typing.Final[ToMessage] = ToMessage() module-attribute #

Convert user input to a hikari.messages.Message object.

to_presence: typing.Final[ToPresence] = ToPresence() module-attribute #

Convert user input to a cached hikari.presences.MemberPresence.

to_role: typing.Final[ToRole] = ToRole() module-attribute #

Convert user input to a hikari.guilds.Role object.

to_snowflake: typing.Final[collections.Callable[[_ArgumentT], hikari.Snowflake]] = parse_snowflake module-attribute #

Convert user input to a hikari.snowflakes.Snowflake.

Note

This also range validates the input.

to_user: typing.Final[ToUser] = ToUser() module-attribute #

Convert user input to a hikari.users.User object.

to_voice_state: typing.Final[ToVoiceState] = ToVoiceState() module-attribute #

Convert user input to a cached hikari.voices.VoiceState.

BaseConverter #

Bases: typing.Generic[_ValueT], abc.ABC

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.

async_caches() abstractmethod property #

Collection of the asynchronous caches that this converter relies on.

This will only be necessary if the suggested intents or cache_components aren't enabled for a converter which requires cache.

cache_components() abstractmethod property #

Cache component(s) the converter takes advantage of.

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.

This will be hikari.api.config.CacheComponents.NONE if the converter doesn't make cache calls.

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.

TYPE: tanjun.Client

parent_name

The name of the converter's parent, used for warning messages.

TYPE: str

intents() abstractmethod property #

Gateway intents this converter takes advantage of.

Note

This field is supplementary to tanjun.conversion.BaseConverter.cache_components and is used to detect when the relevant component might not actually be being kept up to date or filled by gateway events.

Unless tanjun.conversion.BaseConverter.requires_cache is True, these intents being disabled won't stop this converter from working as it'll still fall back to REST requests.

requires_cache() abstractmethod property #

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.

ToChannel #

Bases: BaseConverter[hikari.PartialChannel]

Standard converter for channels mentions/IDs.

For a standard instance of this see tanjun.conversion.to_channel.

__init__(*, include_dms=True) #

Initialise a to channel converter.

PARAMETER DESCRIPTION
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: bool DEFAULT: True

ToEmoji #

Bases: BaseConverter[hikari.KnownCustomEmoji]

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 hikari.emojis.Emoji.parse, hikari.emojis.CustomEmoji.parse or hikari.emojis.UnicodeEmoji.parse methods.

ToGuild #

Bases: BaseConverter[hikari.Guild]

Stanard converter for guilds.

For a standard instance of this see tanjun.conversion.to_guild.

ToInvite #

Bases: BaseConverter[hikari.Invite]

Standard converter for invites.

ToInviteWithMetadata #

Bases: BaseConverter[hikari.InviteWithMetadata]

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[hikari.Member]

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[hikari.Message]

Standard converter for messages.

For a standard instance of this see tanjun.conversion.to_message.

ToPresence #

Bases: BaseConverter[hikari.MemberPresence]

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[hikari.Role]

Standard converter for guild roles.

For a standard instance of this see tanjun.conversion.to_role.

ToUser #

Bases: BaseConverter[hikari.User]

Standard converter for users.

For a standard instance of this see tanjun.conversion.to_user.

ToVoiceState #

Bases: BaseConverter[hikari.VoiceState]

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

TYPE: datetime.datetime

style

The style to use.

The valid styles can be found at https://discord.com/developers/docs/reference#message-formatting-formats.

TYPE: str DEFAULT: 'f'

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(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: _ArgumentT

message

The error message to raise if the value cannot be parsed.

TYPE: str DEFAULT: 'No valid message link or ID found'

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

Convert user string input into a boolean value.

PARAMETER DESCRIPTION
value

The value to convert.

TYPE: str

RETURNS DESCRIPTION
bool

The converted value.

RAISES DESCRIPTION
ValueError

If the value cannot be converted.

to_color(argument) #

Convert user input to a hikari.colors.Color object.

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

RETURNS DESCRIPTION
datetime.datetime

The parsed datetime.

RAISES DESCRIPTION
ValueError

If the value cannot be parsed.