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

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

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). 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 module-attribute

search_channel_ids: _IDSearcherSig = _make_snowflake_searcher(_CHANNEL_ID_REGEX)

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

search_emoji_ids: _IDSearcherSig = _make_snowflake_searcher(_EMOJI_ID_REGEX)

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

search_role_ids: _IDSearcherSig = _make_snowflake_searcher(_ROLE_ID_REGEX)

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

search_snowflakes: _IDSearcherSig = _make_snowflake_searcher(_SNOWFLAKE_REGEX)

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

search_user_ids: _IDSearcherSig = _make_snowflake_searcher(_USER_ID_REGEX)

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

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.

async_caches property

async_caches: collections.Sequence[typing.Any]

Deprecated property.

cache_components property

cache_components: hikari.api.CacheComponents

Deprecated property.

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.

intents property

intents: hikari.Intents

Deprecated property.

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. TYPE: tanjun.Client
parent_name	The name of the converter's parent, used for warning messages. TYPE: str

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: typing.Optional[collections.Collection[typing.Union[type[hikari.PartialChannel], int]]] DEFAULT: None
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

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

Bases: BaseConverter

Standard converter for invites.

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. TYPE: typing.Union[datetime.datetime, datetime.timedelta]
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 value is a datetime.timedelta. 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

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

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

to_color(argument)

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

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

RETURNS	DESCRIPTION
datetime.datetime	The parsed datetime.

RAISES	DESCRIPTION
ValueError	If the value cannot be parsed.