Skip to content

tanjun.conversion#

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

defragment_url module-attribute #

defragment_url = _build_url_parser(urldefrag)

Convert an argument to a defragmented URL.

Parameters:

  • value (str) –

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

Returns:

Raises:

  • ValueError –

    If the argument couldn't be parsed.

parse_channel_id module-attribute #

parse_channel_id = _make_snowflake_parser(_CHANNEL_ID_REGEX)

Parse a channel ID from a string or int value.

Parameters:

  • value (str | int | float) –

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

  • message (str) –

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

Returns:

Raises:

parse_emoji_id module-attribute #

parse_emoji_id = _make_snowflake_parser(_EMOJI_ID_REGEX)

Parse an Emoji ID from a string or int value.

Parameters:

  • value (str | int | float) –

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

  • message (str) –

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

    Defaults to "No valid mention or ID found".

Returns:

Raises:

parse_role_id module-attribute #

parse_role_id = _make_snowflake_parser(_ROLE_ID_REGEX)

Parse a role ID from a string or int value.

Parameters:

  • value (str | int | float) –

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

  • message (str) –

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

    Defaults to "No valid mention or ID found".

Returns:

Raises:

parse_snowflake module-attribute #

parse_snowflake = _make_snowflake_parser(_SNOWFLAKE_REGEX)

Parse a snowflake from a string or int value.

Parameters:

  • value (str | int | float) –

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

  • message (str) –

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

Returns:

Raises:

parse_url module-attribute #

parse_url = _build_url_parser(urlparse)

Convert an argument to a parsed URL.

Parameters:

  • value (str) –

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

Returns:

Raises:

  • ValueError –

    If the argument couldn't be parsed.

parse_user_id module-attribute #

parse_user_id = _make_snowflake_parser(_USER_ID_REGEX)

Parse a user ID from a string or int value.

Parameters:

  • value (str | int | float) –

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

  • message (str) –

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

    Defaults to "No valid mention or ID found".

Returns:

Raises:

search_channel_ids module-attribute #

search_channel_ids = _make_snowflake_searcher(_CHANNEL_ID_REGEX)

Get the channel IDs in a string.

Parameters:

  • value (str | int | float) –

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

Returns:

search_emoji_ids module-attribute #

search_emoji_ids = _make_snowflake_searcher(_EMOJI_ID_REGEX)

Get the emoji IDs in a string.

Parameters:

  • value (str | int | float) –

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

Returns:

search_role_ids module-attribute #

search_role_ids = _make_snowflake_searcher(_ROLE_ID_REGEX)

Get the role IDs in a string.

Parameters:

  • value (str | int | float) –

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

Returns:

search_snowflakes module-attribute #

search_snowflakes = _make_snowflake_searcher(_SNOWFLAKE_REGEX)

Get the snowflakes in a string.

Parameters:

  • value (str | int | float) –

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

Returns:

search_user_ids module-attribute #

search_user_ids = _make_snowflake_searcher(_USER_ID_REGEX)

Get the user IDs in a string.

Parameters:

  • value (str | int | float) –

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

Returns:

split_url module-attribute #

split_url = _build_url_parser(urlsplit)

Convert an argument to a split URL.

Parameters:

  • value (str) –

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

Returns:

Raises:

  • ValueError –

    If the argument couldn't be parsed.

to_channel module-attribute #

to_channel = ToChannel()

Convert user input to a hikari.PartialChannel object.

to_colour module-attribute #

to_colour = to_color

Convert user input to a hikari.Color object.

to_emoji module-attribute #

to_emoji = ToEmoji()

Convert user input to a cached hikari.KnownCustomEmoji object.

Note

If you just want to convert input to a hikari.Emoji, hikari.CustomEmoji or hikari.UnicodeEmoji without making any cache or REST calls then you can just use the relevant Emoji.parse, CustomEmoji.parse or UnicodeEmoji.parse methods.

to_guild module-attribute #

to_guild = ToGuild()

Convert user input to a hikari.Guild object.

to_invite module-attribute #

to_invite = ToInvite()

Convert user input to a cached hikari.InviteWithMetadata object.

to_invite_with_metadata module-attribute #

to_invite_with_metadata = ToInviteWithMetadata()

Convert user input to a hikari.Invite object.

to_member module-attribute #

to_member = ToMember()

Convert user input to a hikari.Member object.

to_message module-attribute #

to_message = ToMessage()

Convert user input to a hikari.Message object.

to_presence module-attribute #

to_presence = ToPresence()

Convert user input to a cached hikari.MemberPresence.

to_role module-attribute #

to_role = ToRole()

Convert user input to a hikari.Role object.

to_snowflake module-attribute #

to_snowflake = parse_snowflake

Convert user input to a hikari.Snowflake.

Note

This also range validates the input.

to_user module-attribute #

to_user = ToUser()

Convert user input to a hikari.User object.

to_voice_state module-attribute #

to_voice_state = ToVoiceState()

Convert user input to a cached hikari.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

Deprecated property.

cache_components property #

cache_components

Deprecated property.

caches property #

caches

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

Deprecated property.

requires_cache property #

requires_cache

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 BaseConverter.intents or 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.

Parameters:

  • client (Client) –

    The client to check against.

  • parent_name (str) –

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

ChannelConverter #

Bases: ToChannel

Deprecated alias of ToChannel.

EmojiConverter #

Bases: ToEmoji

Deprecated alias of ToEmoji.

GuildConverter #

Bases: ToGuild

Deprecated alias of ToGuild.

InviteConverter #

Bases: ToInvite

Deprecated alias of ToInvite.

InviteWithMetadataConverter #

Bases: ToInviteWithMetadata

Deprecated alias of ToInviteWithMetadata.

MemberConverter #

Bases: ToMember

Deprecated alias of ToMember.

PresenceConverter #

Bases: ToPresence

Deprecated alias of ToPresence.

RoleConverter #

Bases: ToRole

Deprecated alias of ToRole.

ToChannel #

Bases: BaseConverter

Standard converter for channels mentions/IDs.

For a standard instance of this see to_channel.

__init__ #

__init__(*, allowed_types=None, include_dms=True)

Initialise a to channel converter.

Parameters:

  • allowed_types (Optional[Collection[Union[type[PartialChannel], int]]], default: None ) –

    Collection of channel types and classes to allow.

    If this is None then all channel types will be allowed.

  • include_dms (bool, default: True ) –

    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.

ToEmoji #

Bases: BaseConverter

Standard converter for custom emojis.

For a standard instance of this see to_emoji.

Note

If you just want to convert inpute to a hikari.Emoji, hikari.CustomEmoji or hikari.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

Standard converter for guilds.

For a standard instance of this see 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 to_invite_with_metadata.

Note

Unlike InviteConverter, this converter is cache dependent.

ToMember #

Bases: BaseConverter

Standard converter for guild members.

For a standard instance of this see 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 to_message.

ToPresence #

Bases: BaseConverter

Standard converter for presences.

For a standard instance of this see 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 to_role.

ToUser #

Bases: BaseConverter

Standard converter for users.

For a standard instance of this see to_user.

ToVoiceState #

Bases: BaseConverter

Standard converter for voice states.

For a standard instance of this see to_voice_state.

Note

This converter is cache dependent and only works in a guild context.

UserConverter #

Bases: ToUser

Deprecated alias of ToUser.

VoiceStateConverter #

Bases: ToVoiceState

Deprecated alias of ToVoiceState.

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

Parameters:

Returns:

  • str –

    The formatted datetime.

Raises:

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

Parameters:

  • value (_SnowflakeIsh) –

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

  • message (str, default: 'No valid message link or ID found' ) –

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

Returns:

Raises:

to_bool #

to_bool(value)

Convert user string input into a boolean value.

Parameters:

  • value (str) –

    The value to convert.

Returns:

  • bool –

    The converted value.

Raises:

  • ValueError –

    If the value cannot be converted.

to_color #

to_color(argument)

Convert user input to a hikari.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

Parameters:

  • value (str) –

    The value to parse.

Returns:

Raises: