Skip to content

tanjun.annotations#

Parameter annotation based strategy for declaring slash and message command arguments.

Community Resources:

Attachment = typing.Annotated[hikari.Attachment, _OptionMarker(hikari.Attachment] module-attribute #

An argument which accepts a file.

Warning

This is currently only supported for slash commands.

Bool = typing.Annotated[bool, _OptionMarker(bool] module-attribute #

An argument which takes a bool-like value.

Channel = typing.Annotated[hikari.PartialChannel, _OptionMarker(hikari.PartialChannel] module-attribute #

An argument which takes a channel.

Color = Converted[conversion.to_color] module-attribute #

An argument which takes a color.

Colour = Color module-attribute #

An argument which takes a colour.

Datetime = Converted[conversion.to_datetime] module-attribute #

An argument which takes a datetime.

Float = typing.Annotated[float, _OptionMarker(float] module-attribute #

An argument which takes a floating point number.

Int = typing.Annotated[int, _OptionMarker(int] module-attribute #

An argument which takes an integer.

Member = typing.Annotated[hikari.Member, _OptionMarker(hikari.Member] module-attribute #

An argument which takes a guild member.

Mentionable = typing.Annotated[typing.Union[hikari.User, hikari.Role], _OptionMarker(_MentionableUnion] module-attribute #

An argument which takes a user or role.

Role = typing.Annotated[hikari.Role, _OptionMarker(hikari.Role] module-attribute #

An argument which takes a role.

Snowflake = Converted[conversion.parse_snowflake] module-attribute #

An argument which takes a snowflake.

Str = typing.Annotated[str, _OptionMarker(str] module-attribute #

An argument which takes string input.

User = typing.Annotated[hikari.User, _OptionMarker(hikari.User] module-attribute #

An argument which takes a user.

Choices #

Bases: _ConfigIdentifier

Assign up to 25 choices for a slash command option.

Warning

This is currently ignored for message commands and is only valid for string, integer and float options.

Examples:

@annotations.with_annotated_args
@tanjun.as_slash_command("beep", "meow")
async def command(
    ctx: tanjun.abc.Context,
    location: Annotated[annotations.Int, "where do you live?", Choices("London", "Paradise", "Nowhere")],
) -> None:
    raise NotImplementedError

__init__(mapping=(), /, **kwargs) #

Create a choices instance.

PARAMETER DESCRIPTION
mapping

Either a mapping of names to the choices values or a sequence of tuple[name, value] or a sequence of choice values.

TYPE: typing.Union[collections.Mapping[str, _ChoiceT], collections.Sequence[tuple[str, _ChoiceT]], collections.Sequence[_ChoiceT]] DEFAULT: ()

**kwargs

Choice values.

TYPE: _ChoiceT DEFAULT: {}

choices() property #

Mapping of up to 25 choices for the slash command option.

Converted #

Bases: _ConfigIdentifier

Marked an argument as type tanjun.annotations.Str with converters.

Examples:

@annotations.with_annotated_args
@tanjun.as_slash_command("beep", "boop")
async def command(
    ctx: tanjun.abc.SlashContext,
    value: Converted[callback, other_callback],
)

__init__(converter, /, *other_converters) #

Create a converted instance.

PARAMETER DESCRIPTION
converter

The first converter this argument should use to handle values passed to it during parsing.

Only the first converter to pass will be used.

TYPE: collections.abc.Callable

*other_converters

Other first converter(s) this argument should use to handle values passed to it during parsing.

Only the first converter to pass will be used.

TYPE: collections.abc.Callable DEFAULT: ()

converters() property #

A sequence of the converters.

Default #

Bases: _ConfigIdentifier

Explicitly configure an argument's default.

Examples:

@annotations.with_annotated_args
@tanjun.as_slash_command("name", "description")
async def command(
    ctx: tanjun.abc.Context,
    argument: Annotated[Str, Default(""), "description],
    other_argument: Annotated[Default[Str, ""], "description"],
) -> None:
    ...

@annotations.with_annotated_args
@tanjun.as_slash_command("name", "description)
async def command(
    ctx: tanjun.abc.Context,
    required_argument: Annotated[Default[Str], "description"] = "yeet",
    other_required: Annotated[Int, Default(), "description"] = 123,
) -> None:
    ...

Passing an empty Default allows you to mark an argument that's optional in the signature as being a required option.

__init__(default=parsing.UNDEFINED) #

Initialise a default.

PARAMETER DESCRIPTION
default

The argument's default.

If left as tanjun.parsing.UNDEFINED then the argument will be required regardless of the signature default.

TYPE: typing.Union[typing.Any, parsing.UndefinedT] DEFAULT: parsing.UNDEFINED

default() property #

The option's default.

This will override the default in the signature for this parameter.

Flag #

Bases: _ConfigIdentifier

Mark an argument as a flag/option for message command parsing.

This indicates that the argument should be specified by name (e.g. --name) rather than positonally for message parsing and doesn't effect slash command options.

Examples:

@annotations.with_annotated_args
@tanjun.as_message_command("message")
async def command(
    ctx: tanjun.abc.MessageContext,
    flag_value: Annotated[Bool, Flag(empty_value=True, aliases=("-f",))] = False,
) -> None:
    raise NotImplementedError

__init__(*, aliases=None, default=parsing.UNDEFINED, empty_value=parsing.UNDEFINED) #

Create a flag instance.

PARAMETER DESCRIPTION
aliases

Other names the flag may be triggered by.

This does not override the argument's name.

TYPE: typing.Optional[collections.Sequence[str]] DEFAULT: None

default

Deprecated argument used to specify the option's default.

Use tanjun.annotations.Default instead.

TYPE: typing.Union[typing.Any, parsing.UndefinedT] DEFAULT: parsing.UNDEFINED

empty_value

Value to pass for the argument if the flag is provided without a value.

If left undefined then an explicit value will always be needed.

TYPE: typing.Union[parsing.UndefinedT, typing.Any] DEFAULT: parsing.UNDEFINED

aliases() property #

The aliases set for this flag.

These do not override the flag's name.

default() property #

The flag's default.

If not specified then the default in the signature for this argument will be used.

empty_value() property #

The value to pass for the argument if the flag is provided without a value.

If this is undefined then a value will always need to be passed for the flag.

Greedy #

Bases: _ConfigIdentifier

Mark an argument as "greedy" for message command parsing.

This means that it'll consume the rest of the positional arguments, can only be applied to one positional argument and is no-op for slash commands and flags.

Examples:

@annotations.with_annotated_args
@tanjun.as_message_command("message")
async def command(
    ctx: tanjun.abc.MessageContext,
    greedy_arg: Greedy[Str],
    other_greedy_arg: Annotated[Str, Greedy()],
) -> None:
    raise NotImplementedError

Max #

Bases: _ConfigIdentifier

Inclusive maximum value for a tanjun.annotations.Float or tanjun.annotations.Int argument.

Examples:

@annotations.with_annotated_args
@tanjun.as_slash_command("beep", "meow")
async def command(
    ctx: tanjun.abc.Context,
    age: Annotated[annotations.Int, Max(130), Min(13)],
) -> None:
    raise NotImplementedError

Alternatively, the slice syntax and range may be used to set the min and max values for a float or integesr arguments (where the start is inclusive and stop is exclusive). These default to a min_value of 0 if the start isn't specified.

@annotations.with_annotated_args
@tanjun.as_slash_command("meow", "description")
async def command(
    ctx: tanjun.abc.SlashContext,
    float_value: Annotated[annotations.Float, 1.5:101.5],
    int_value: Annotated[annotations.Int, range(5, 100)],
) -> None:
    raise NotImplementedError

__init__(value) #

Create an argument maximum value.

PARAMETER DESCRIPTION
value

The maximum allowed value allowed for an argument.

TYPE: typing.Union[int, float]

value() property #

The maximum allowed value.

Min #

Bases: _ConfigIdentifier

Inclusive minimum value for a tanjun.annotations.Float or tanjun.annotations.Int argument.

Examples:

@annotations.with_annotated_args
@tanjun.as_slash_command("beep", "meow")
async def command(
    ctx: tanjun.abc.Context,
    age: Annotated[annotations.Int, "How old are you?", Max(130), Min(13)],
) -> None:
    raise NotImplementedError

Alternatively, the slice syntax and range may be used to set the min and max values for a float or integesr arguments (where the start is inclusive and stop is exclusive). These default to a min_value of 0 if the start isn't specified.

@annotations.with_annotated_args
@tanjun.as_slash_command("meow", "description")
async def command(
    ctx: tanjun.abc.SlashContext,
    float_value: Annotated[annotations.Float, 1.5:101.5],
    int_value: Annotated[annotations.Int, range(5, 100)],
) -> None:
    raise NotImplementedError

__init__(value) #

Create an argument minimum value.

PARAMETER DESCRIPTION
value

The minimum value allowed for an argument.

TYPE: typing.Union[int, float]

value() property #

The minimum allowed value.

Name #

Bases: _ConfigIdentifier

Override the inferred name used to declare an option.

Examples:

@annotations.with_annotated_args(follow_wrapped=True)
@tanjun.as_slash_command("meow", "nyaa")
@tanjun.as_message_command("meow")
async def command(
    ctx: tanjun.abc.Context,
    resource_type: Annotated[Str, Name("type"), "The type of resource to get."],
) -> None:
    raise NotImplementedError

__init__(both=None, /, *, message=None, slash=None) #

Create an argument name override.

PARAMETER DESCRIPTION
both

If provided, the name to use for this option in message and slash commands.

This will be reformatted a bit for message commands (prefixed with -- and .replace("_", "-")) and is only used for message flag options.

TYPE: typing.Optional[str] DEFAULT: None

message

The name to use for this option in message commands.

This takes priority over both, is not reformatted and only is only used for flag options.

TYPE: typing.Optional[str] DEFAULT: None

slash

The name to use for this option in slash commands.

This takes priority over both.

TYPE: typing.Optional[str] DEFAULT: None

message_name() property #

The name to use for this option in message commands.

slash_name() property #

The name to use for this option in slash commands.

Positional #

Bases: _ConfigIdentifier

Mark an argument as being passed positionally for message command parsing.

Arguments will be positional by default (unless it has a default) and this allows for marking positional arguments as optional.

This only effects message option parsing.

Examples:

@annotations.with_annotated_args
@tanjun.as_message_command("message")
async def command(
    ctx: tanjun.abc.MessageContext,
    positional_arg: Positional[Str] = None,
    other_positional_arg: Annotated[Str, Positional()] = None,
) -> None:
    raise NotImplementedError

__init__() #

Create a positional instance.

Ranged #

Bases: _ConfigIdentifier

Declare the range limit for an Int or Float argument.

Examples:

@annotations.with_annotated_args(follow_wrapped=True)
@tanjun.as_slash_command("meow", "nyaa")
@tanjun.as_message_command("meow")
async def command(
    ctx: tanjun.abc.Context,
    number_arg: Annotated[Int, Ranged(0, 69)],
) -> None:
    raise NotImplementedError


@annotations.with_annotated_args(follow_wrapped=True)
@tanjun.as_slash_command("meow", "nyaa")
@tanjun.as_message_command("meow")
async def command(
    ctx: tanjun.abc.Context,
    number_arg: Ranged[0, 69],
) -> None:
    raise NotImplementedError
Here the argument type is inferred from whether integers or floats are passed to Ranged[...]

__init__(min_value, max_value) #

Create an argument range limit.

PARAMETER DESCRIPTION
min_value

The minimum allowed value for this argument.

TYPE: typing.Union[int, float]

max_value

The maximum allowed value for this argument.

TYPE: typing.Union[int, Float]

max_value() property #

The maximum allowed value for this argument.

min_value() property #

The minimum allowed value for this argument.

SnowflakeOr #

Bases: _ConfigIdentifier

Mark an argument as taking an object or its ID.

This allows for the argument to be declared as taking the object for slash commands without requiring that the message command equivalent fetch the object each time for the following types:

Examples:

@annotations.with_annotated_args(follow_wrapped=True)
@tanjun.as_slash_command("meow", "nyaa")
@tanjun.as_message_command("meow")
async def command(
    ctx: tanjun.abc.Context,
    user: Annotated[User, SnowflakeOr(parse_id=parse_user_id), "The user to target."],
) -> None:
    user_id = hikari.Snowflake(user)

@annotations.with_annotated_args(follow_wrapped=True)
@tanjun.as_slash_command("meow", "nyaa")
@tanjun.as_message_command("meow")
async def command(
    ctx: tanjun.abc.Context,

    # When using SnowflakeOr as a type-hint, the `parse_id` callback is
    # automatically set to the mention format for the specified for the
    # passed type if applicable.
    user: Annotated[SnowflakeOr[User], "The user to target."],
) -> None:
    user_id = hikari.Snowflake(user)

__init__(*, parse_id=conversion.parse_snowflake) #

Create a snowflake or argument marker.

PARAMETER DESCRIPTION
parse_id

The function used to parse the argument's ID.

This can be used to restrain this to only accepting certain mention formats.

TYPE: collections.Callable[[str], hikari.Snowflake] DEFAULT: conversion.parse_snowflake

parse_id() property #

Callback used to parse this argument's ID.

TheseChannels #

Bases: _ConfigIdentifier

Declare the type of channels a slash command partial channel argument can target.

This is no-op for message commands and will not restrain the argument right now.

__init__(channel_type, /, *other_types) #

Create a slash command argument channel restraint.

PARAMETER DESCRIPTION
channel_type

A channel type to restrain this argument by.

TYPE: _ChannelTypeIsh

*other_types

Other channel types to restrain this argument by.

TYPE: _ChannelTypeIsh DEFAULT: ()

channel_types() property #

Sequence of the channel types this is constrained by.

with_annotated_args(command=None, /, *, follow_wrapped=False) #

Set a command's arguments based on its signature.

To declare arguments a you will have to do one of two things:

  1. Using any of the following types as an argument's type-hint (this may be as the first argument to typing.Annotated) will mark it as injected:

    @tanjun.with_annotated_args(follow_wrapped=True)
@tanjun.as_message_command("name")
@tanjun.as_slash_command("name", "description")
async def command(
    ctx: tanjun.abc.SlashContext,

    # Here the option's description is passed as a string to Annotated:
    # this is necessary for slash commands but ignored for message commands.
    name: Annotated[Str, "The character's name"],

    # `= False` declares this field as optional, with it defaulting to `False`
    # if not specified.
    lawyer: Annotated[Bool, "Whether they're a lawyer"] = False,
) -> None:
    raise NotImplementedError

  2. By assigning tanjun.annotations.Converted...

    Either as one of the other arguments to typing.Annotated

    @tanjun.with_annotated_args(follow_wrapped=True)
@tanjun.as_message_command("e")
@tanjun.as_slash_command("e", "description")
async def command(
    ctx: tanjun.abc.SlashContext,
    value: Annotated[OtherType, Converted(parse_value), "description"],
) -> None:
    raise NotImplementedError

    or as the type hint

    @tanjun.with_annotated_args(follow_wrapped=True)
@tanjun.as_message_command("e")
@tanjun.as_slash_command("e", "description")
async def command(
    ctx: tanjun.abc.SlashContext,
    value: Annotated[Converted[CustomType.from_str], "description"],
) -> None:
    raise NotImplementedError

It should be noted that wrapping in typing.Annotated isn't necessary for message commands options as they don't have descriptions.

async def message_command(
    ctx: tanjun.abc.MessageContext,
    name: Str,
    converted: Converted[Type.from_str],
    enable: typing.Optional[Bool] = None,
) -> None:
    ...
PARAMETER DESCRIPTION
command

The message or slash command to set the arguments for.

TYPE: tanjun.SlashCommand | tanjun.MessageCommand DEFAULT: None

follow_wrapped

Whether this should also set the arguments on any other command objects this wraps in a decorator call chain.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
tanjun.SlashCommand | tanjun.MessageCommand

The command object to enable using this as a decorator.