tanjun.annotations#

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

with_annotated_args should be used to parse the options for both message commands and slash commands. follow_wrapped=True should be passed if you want this to parse options for all the commands being declared in a decorator call chain.

This implementation exposes 3 ways to mark an argument as a command option:

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 a command argument:
* These types are specific to slash commands and will raise an exception when set for a message command's parameter which has no real default.
```
@tanjun.with_annotated_args(follow_wrapped=True)
@tanjun.as_message_command("name")
@tanjun.as_slash_command("name", "description")
async def command(
    ctx: tanjun.abc.Context,

    # 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
```
When doing this the following objects can be included in a field's annotations to add extra configuration:
- annotations.Default Set the default for an option in the annotations (rather than using the argument's actual default).
- annotations.Flag Mark an option as being a flag option for message commands.
- annotations.Greedy Mark an option as consuming the rest of the provided positional values for message commands.
- annotations.Length Set the length restraints for a string option.
- annotations.Min Set the minimum valid size for float and integer options.
- annotations.Max Set the maximum valid size for float and integer options.
- annotations.Name Override the option's name.
- annotations.Positional Mark optional arguments as positional for message commands.
- annotations.Ranged Set range constraints for float and integer options.
- annotations.SnowflakeOr Indicate that a role, user, channel, member, role, or mentionable option should be left as the ID for message commands.
- annotations.TheseChannels Constrain the valid channel types for a channel option.
```
async def command(
    ctx: tanjun.abc.Context,
    name: Annotated[Str, Length(1, 20)],
    channel: Annotated[Role | hikari.Snowflake | None, SnowflakeOr()] = None,
) -> None:
    raise NotImplementedError
```
It should be noted that wrapping in typing.Annotated isn't required for message commands options as they don't have descriptions.
```
async def message_command(
    ctx: tanjun.abc.MessageContext,
    name: Str,
    value: Str,
    enable: Bool | None = None,
) -> None:
    raise NotImplementedError
```

By assigning tanjun.Converted 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.Context,
    value: Annotated[ParsedType, Converted(parse_value), "description"],
) -> None:
    raise NotImplementedError

When doing this the option type will be str.

By using any of the following default descriptors as the argument's default:
* These are specific to slash commands and will raise an exception when set for a message command's parameter which has no real default.
```
@tanjun.with_annotated_args(follow_wrapped=True)
@tanjun.as_message_command("e")
@tanjun.as_slash_command("e", "description")
async def command(
    ctx: tanjun.abc.Context,
    user_field: hikari.User | None = annotations.user_field(default=None),
    field: bool = annotations.bool_field(default=False, empty_value=True),
) -> None:
    raise NotImplementedError
```

A typing.TypedDict can be used to declare multiple options by typing the passed **kwargs dict as it using typing.Unpack. These options can be marked as optional using typing.NotRequired, total=False or Default.

class CommandOptions(typing.TypedDict):
    argument: Annotated[Str, "A required string argument"]
    other: NotRequired[Annotated[Bool, "An optional string argument"]]

@tanjun.with_annotated_args(follow_wrapped=True)
@tanjun.as_message_command("name")
@tanjun.as_slash_command("name", "description")
async def command(
    ctx: tanjun.abc.Context, **kwargs: Unpack[CommandOptions],
) -> None:
    raise NotImplementedError

Community Resources:

An extended implementation of this which parses callback docstrings to get the descriptions for slash commands and their options can be found in https://github.com/FasterSpeeding/Tan-chan.

Attachment `module-attribute` #

Attachment = Annotated[Attachment, _OptionMarker(Attachment)]

Type-hint for marking an argument which accepts a file.

Warning

This is currently only supported for slash commands.

Bool `module-attribute` #

Bool = Annotated[bool, _OptionMarker(bool)]

Type-hint for marking an argument which takes a bool-like value.

Channel `module-attribute` #

Channel = Annotated[PartialChannel, _OptionMarker(PartialChannel)]

Type-hint for marking an argument which takes a channel.

hikari.InteractionChannel will be passed for options typed as this when being called as a slash command.

Color `module-attribute` #

Color = Annotated[Color, Converted(to_color)]

An argument which takes a color.

Colour `module-attribute` #

Colour = Color

An argument which takes a colour.

Datetime `module-attribute` #

Datetime = Annotated[datetime, Converted(to_datetime)]

An argument which takes a datetime.

Float `module-attribute` #

Float = Annotated[float, _OptionMarker(float)]

Type-hint for marking an argument which takes a floating point number.

Int `module-attribute` #

Int = Annotated[int, _OptionMarker(int)]

Type-hint for marking an argument which takes an integer.

InteractionChannel `module-attribute` #

InteractionChannel = Annotated[InteractionChannel, _OptionMarker(InteractionChannel)]

Type-hint for marking an argument which takes a channel with interaction specific metadata.

Warning

This is only supported for slash commands and will not work for message commands (unlike annotations.Channel).

InteractionMember `module-attribute` #

InteractionMember = Annotated[InteractionMember, _OptionMarker(InteractionMember)]

Type-hint for marking an argument which takes an interactio.

Warning

This is only supported for slash commands and will not work for message commands (unlike annotations.Member).

Member `module-attribute` #

Member = Annotated[Member, _OptionMarker(Member)]

Type-hint for marking an argument which takes a guild member.

hikari.InteractionMember will be passed for options typed as this when being called as a slash command.

Mentionable `module-attribute` #

Mentionable = Annotated[User | Role, _OptionMarker(_MentionableUnion)]

Type-hint for marking an argument which takes a user or role.

Role `module-attribute` #

Role = Annotated[Role, _OptionMarker(Role)]

Type-hint for marking an argument which takes a role.

Snowflake `module-attribute` #

Snowflake = Annotated[Snowflake, Converted(parse_snowflake)]

An argument which takes a snowflake.

Str `module-attribute` #

Str = Annotated[str, _OptionMarker(str)]

Type-hint for marking an argument which takes string input.

User `module-attribute` #

User = Annotated[User, _OptionMarker(User)]

Type-hint for marking 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:

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

choices `property` #

choices

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

init #

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

Create a choices instance.

Parameters:

mapping (Mapping[str, _ChoiceT] | Sequence[tuple[str, _ChoiceT]] | Sequence[_ChoiceT], default: () ) –

Either a mapping of names to the choices values or a sequence of tuple[name, value] or a sequence of choice values.
**kwargs (_ChoiceT, default: {} ) –

Choice values.

Converted #

Bases: _ConfigIdentifier

Marked an argument as type Str with converters.

Examples:

@with_annotated_args
@tanjun.as_slash_command("beep", "boop")
async def command(
    ctx: tanjun.abc.SlashContext,
    argument: Annotated[OtherType, Converted(callback, other_callback), "description"]
) -> None:
    raise NotImplementedError

converters `property` #

converters

A sequence of the converters.

init #

__init__(converter, /, *other_converters)

Create a converted instance.

Parameters:

converter (Callable[[str, ...], Coroutine[Any, Any, Any] | Any]) –

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

Only the first converter to pass will be used.
*other_converters (Callable[[str, ...], Coroutine[Any, Any, Any] | Any], default: () ) –

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.

Default #

Bases: _ConfigIdentifier

Explicitly configure an argument's default.

Examples:

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

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

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

default `property` #

default

The option's default.

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

init #

__init__(default=tanjun.NO_DEFAULT)

Initialise a default.

Parameters:

default (Any, default: NO_DEFAULT ) –

The argument's default.

If left as tanjun.abc.NO_DEFAULT then the argument will be required regardless of the signature default.

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 positionally for message parsing and doesn't effect slash command options.

Examples:

@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

aliases `property` #

aliases

The aliases set for this flag.

These do not override the flag's name.

default `property` #

default

The flag's default.

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

empty_value `property` #

empty_value

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

If this is tanjun.abc.NO_DEFAULT then a value will be required for this flag.

init #

__init__(*, aliases: collections.Sequence[str] | None = None, empty_value: typing.Any = tanjun.NO_DEFAULT) -> None

__init__(*, aliases: collections.Sequence[str] | None = None, default: typing.Any = tanjun.NO_DEFAULT, empty_value: typing.Any = tanjun.NO_DEFAULT) -> None

__init__(*, aliases=None, default=tanjun.NO_DEFAULT, empty_value=tanjun.NO_DEFAULT)

Create a flag instance.

Parameters:

aliases (Sequence[str] | None, default: None ) –

Other names the flag may be triggered by.

This does not override the argument's name and all the aliases must be prefixed with "-".
empty_value (Any, default: NO_DEFAULT ) –

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.

tanjun.abc.NO_PASS is not supported for this.

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:

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

Length #

Bases: _ConfigIdentifier

Define length restraints for a string option.

Note

Length constraints are applied before conversion for slash commands but after conversion for message commands.

Examples:

@with_annotated_args
@tanjun.as_slash_command("meow", "blam")
async def command(
    ctx: tanjun.abc.Context,
    max_and_min: typing.Annotated[Str, Length(123, 321)],
    max_only: typing.Annotated[Str, Length(123)],
) -> None:
    raise NotImplementedError

@with_annotated_args
@tanjun.as_slash_command("meow", "description")
async def command(
    ctx: tanjun.abc.SlashContext,
    argument: Annotated[Str, range(5, 100), "description"],
    other_argument: Annotated[Str, 4:64, "description"],
) -> None:
    raise NotImplementedError

Alternatively, the slice syntax and range may be used to set the length restraints for a string argument (where the start is inclusive and stop is exclusive). These default to a min_length of 0 if the start isn't specified and ignores any specified step.

max_length `property` #

max_length

The maximum length of this string option.

min_length `property` #

min_length

The minimum length of this string option.

init #

__init__(max_length: int) -> None

__init__(min_length: int, max_length: int) -> None

__init__(min_or_max_length, max_length=None)

Initialise a length constraint.

Parameters:

min_or_max_length (int) –

If max_length is left as None then this will be used as the maximum length and the minimum length will be 0.

Otherwise this will be the minimum length this string option can be.
max_length (int | None, default: None ) –

The maximum length this string argument can be.

If not specified then min_or_max_length will be used as the max length.

Max #

Bases: _ConfigIdentifier

Inclusive maximum value for a Float or Int argument.

Examples:

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

value `property` #

value

The maximum allowed value.

init #

__init__(value)

Create an argument maximum value.

Parameters:

value (int | float) –

The maximum allowed value allowed for an argument.

Min #

Bases: _ConfigIdentifier

Inclusive minimum value for a Float or Int argument.

Examples:

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

value `property` #

value

The minimum allowed value.

init #

__init__(value)

Create an argument minimum value.

Parameters:

value (int | float) –

The minimum value allowed for an argument.

Name #

Bases: _ConfigIdentifier

Override the inferred name used to declare an option.

Examples:

@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

message_name `property` #

message_name

The name to use for this option in message commands.

slash_name `property` #

slash_name

The name to use for this option in slash commands.

init #

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

Create an argument name override.

Parameters:

both (str | None, default: None ) –

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.
message (str | None, default: None ) –

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.
slash (str | None, default: None ) –

The name to use for this option in slash commands.

This takes priority over both.

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:

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

Ranged #

Bases: _ConfigIdentifier

Declare the range limit for an Int or Float argument.

Examples:

@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), "description"],
    other_number_arg: Annotated[Float, Ranged(13.69, 420.69), "description"],
) -> None:
    raise NotImplementedError

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

Alternatively, the slice syntax and range may be used to set the range for a float or integer argument (where the start is inclusive and stop is exclusive). These default to a min_value of 0 if the start isn't specified and ignores any specified step.

max_value `property` #

max_value

The maximum allowed value for this argument.

min_value `property` #

min_value

The minimum allowed value for this argument.

init #

__init__(min_value, max_value)

Create an argument range limit.

Parameters:

min_value (int | float) –

The minimum allowed value for this argument.
max_value (int | Float) –

The maximum 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:

User
Role
Member
Channel
Mentionable

Examples:

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

parse_id `property` #

parse_id

Callback used to parse this argument's ID.

init #

__init__(*, parse_id=conversion.parse_snowflake)

Create a snowflake or argument marker.

Parameters:

parse_id (Callable[[str], Snowflake], default: parse_snowflake ) –

The function used to parse the argument's ID.

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

TheseChannels #

Bases: _ConfigIdentifier

Restrain the type of channels a channel argument can target.

channel_types `property` #

channel_types

Sequence of the channel types this is constrained by.

init #

__init__(channel_type, /, *other_types)

Create a channel argument restraint.

Parameters:

channel_type (_ChannelTypeIsh) –

A channel type to restrain this argument by.
*other_types (_ChannelTypeIsh, default: () ) –

Other channel types to restrain this argument by.

attachment_field #

attachment_field(*, default=tanjun.NO_DEFAULT, description='', slash_name='')

Mark a parameter as an attachment option using a descriptor.

Warning

This is currently only supported for slash commands.

Examples:

async def command(
    ctx: tanjun.abc.SlashContext,
    field: hikari.Attachment | None = annotations.attachment_field(default=None),
) -> None:
    ...

Parameters:

default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required.
description (str, default: '' ) –

The option's description.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

bool_field #

bool_field(*, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), positional=None, slash_name='')

Mark a parameter as a bool option using a descriptor.

Examples:

async def command(
    ctx: tanjun.abc.SlashContext,
    field: bool | None = annotations.bool_field(default=None),
) -> None:
    ...

Parameters:

default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

channel_field #

channel_field(*, channel_types: collections.Sequence[_ChannelTypeIsh] = (), default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[False] = False, positional: bool | None = None, slash_name: str = '') -> hikari.PartialChannel | _T

channel_field(*, channel_types: collections.Sequence[_ChannelTypeIsh] = (), default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[True], positional: bool | None = None, slash_name: str = '') -> hikari.PartialChannel | hikari.Snowflake | _T

channel_field(*, channel_types=(), default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), or_snowflake=False, positional=None, slash_name='')

Mark a parameter as a channel option using a descriptor.

async def command(
    ctx: tanjun.abc.Context,
    field: hikari.PartialChannel | None = annotations.channel_field(default=None),
) -> None:
    ...

Parameters:

channel_types (Sequence[_ChannelTypeIsh], default: () ) –

Sequence of the channel types allowed for this option.

If left as an empty sequence then all channel types will be allowed.
default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
or_snowflake (bool, default: False ) –

Whether this should just pass the parsed channel ID as a hikari.Snowflake for message command calls.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

float_field #

float_field(*, choices=None, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), min_value=None, max_value=None, positional=None, slash_name='')

Mark a parameter as a float option using a descriptor.

async def command(
    ctx: tanjun.abc.Context,
    field: float | None = annotations.float_field(default=None),
) -> None:
    ...

Parameters:

choices (Mapping[str, float] | None, default: None ) –

A mapping of up to 25 names to the choices values for this option.

This is ignored for message command parsing.
default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
min_value (float | None, default: None ) –

The minimum allowed value for this argument.
max_value (float | None, default: None ) –

The maximum allowed value for this argument.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

int_field #

int_field(*, choices=None, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), min_value=None, max_value=None, positional=None, slash_name='')

Mark a parameter as a int option using a descriptor.

async def command(
    ctx: tanjun.abc.Context,
    field: int | None = annotations.int_field(default=None),
) -> None:
    ...

Parameters:

choices (Mapping[str, int] | None, default: None ) –

A mapping of up to 25 names to the choices values for this option.

This is ignored for message command parsing.
default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
min_value (int | None, default: None ) –

The minimum allowed value for this argument.
max_value (int | None, default: None ) –

The maximum allowed value for this argument.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

member_field #

member_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[False] = False, positional: bool | None = None, slash_name: str = '') -> hikari.Member | _T

member_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[True], positional: bool | None = None, slash_name: str = '') -> hikari.Member | hikari.Snowflake | _T

member_field(*, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), or_snowflake=False, positional=None, slash_name='')

Mark a parameter as a guild member option using a descriptor.

async def command(
    ctx: tanjun.abc.Context,
    field: hikari.Member | None = annotations.member_field(default=None),
) -> None:
    ...

Parameters:

default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
or_snowflake (bool, default: False ) –

Whether this should just pass the parsed user ID as a hikari.Snowflake for message command calls.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

mentionable_field #

mentionable_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[False] = False, positional: bool | None = None, slash_name: str = '') -> hikari.User | hikari.Role | _T

mentionable_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[True], positional: bool | None = None, slash_name: str = '') -> hikari.User | hikari.Role | hikari.Snowflake | _T

mentionable_field(*, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), or_snowflake=False, positional=None, slash_name='')

Mark a parameter as a "mentionable" option using a descriptor.

Mentionable options allow both user and roles.

async def command(
    ctx: tanjun.abc.Context,
    field: hikari.Role | hikari.User | None = annotations.mentionable_field(default=None),
) -> None:
    ...

Parameters:

default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
or_snowflake (bool, default: False ) –

Whether this should just pass the parsed ID as a hikari.Snowflake for message command calls.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

parse_annotated_args #

parse_annotated_args(command, /, *, descriptions=None, follow_wrapped=False)

Set a command's arguments based on its signature.

For more information on how this works see with_annotated_args which acts as the decorator equivalent of this. The only difference is function allows passing a mapping of argument descriptions.

Parameters:

command (SlashCommand[Any] | MessageCommand[Any]) –

The message or slash command to set the arguments for.
descriptions (Mapping[str, str] | None, default: None ) –

Mapping of descriptions to use for this command's slash command options.

If an option isn't included here then this will default back to getting the description from its annotation.
follow_wrapped (bool, default: False ) –

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

role_field #

role_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[False] = False, positional: bool | None = None, slash_name: str = '') -> hikari.Role | _T

role_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[True], positional: bool | None = None, slash_name: str = '') -> hikari.Role | hikari.Snowflake | _T

role_field(*, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), or_snowflake=False, positional=None, slash_name='')

Mark a parameter as a guild role option using a descriptor.

async def command(
    ctx: tanjun.abc.Context,
    field: hikari.Role | None = annotations.role_field(default=None),
) -> None:
    ...

Parameters:

default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
or_snowflake (bool, default: False ) –

Whether this should just pass the parsed role ID as a hikari.Snowflake for message command calls.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

str_field #

str_field(*, choices: collections.Mapping[str, str] | None = None, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), min_length: int | None = None, max_length: int | None = None, positional: bool | None = None, slash_name: str = '') -> str | _T

str_field(*, choices: collections.Mapping[str, str] | None = None, converters: _ConverterSig[_OtherT] | collections.Sequence[_ConverterSig[_OtherT]], default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), min_length: int | None = None, max_length: int | None = None, positional: bool | None = None, slash_name: str = '') -> _OtherT | _T

str_field(*, choices=None, converters=(), default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), min_length=None, max_length=None, positional=None, slash_name='')

Mark a parameter as a string option using a descriptor.

Examples:

async def command(
    ctx: tanjun.abc.Context,
    field: str | None = annotations.str_field(default=None),
) -> None:
    ...

Parameters:

choices (Mapping[str, str] | None, default: None ) –

A mapping of up to 25 names to the choices values for this option.

This is ignored for message command parsing.
converters (_ConverterSig[_OtherT] | Sequence[_ConverterSig[_OtherT]], default: () ) –

The option's converters.

This may be either one or multiple converter callbacks used to convert the option's value to the final form. If no converters are provided then the raw value will be passed.

Only the first converter to pass will be used.
default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
min_length (int | None, default: None ) –

The minimum length this argument can be.
max_length (int | None, default: None ) –

The maximum length this string argument can be.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

user_field #

user_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[False] = False, positional: bool | None = None, slash_name: str = '') -> hikari.User | _T

user_field(*, default: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, description: str = '', empty_value: _T | tanjun.NoDefault = tanjun.NO_DEFAULT, greedy: bool | None = None, message_names: collections.Sequence[str] = (), or_snowflake: typing.Literal[True], positional: bool | None = None, slash_name: str = '') -> hikari.User | hikari.Snowflake | _T

user_field(*, default=tanjun.NO_DEFAULT, description='', empty_value=tanjun.NO_DEFAULT, greedy=None, message_names=(), or_snowflake=False, positional=None, slash_name='')

Mark a parameter as a user option using a descriptor.

Examples:

async def command(
    ctx: tanjun.abc.Context,
    field: hikari.User | None = annotations.user_field(default=None),
) -> None:
    ...

Parameters:

default (Any, default: NO_DEFAULT ) –

Default value to pass if this option wasn't provided.

If not passed then this option will be required. Otherwise, this will mark the option as being a flag for message commands unless positional=False is also passed.
description (str, default: '' ) –

The option's description.
empty_value (Any, default: NO_DEFAULT ) –

Value to pass when this is used as a message flag without a value (i.e. --name).

If not passed then a value will be required and is ignored unless default is also passed.
greedy (bool | None, default: None ) –

Whether this option should be marked as "greedy" form message command parsing.

A greedy option will consume the rest of the positional arguments. This can only be applied to one positional argument and is no-op for slash commands and flags.
message_names (Sequence[str], default: () ) –

The names this option may be triggered by as a message command flag option.

These must all be prefixed with "-" and are ignored unless default is also passed.
or_snowflake (bool, default: False ) –

Whether this should just pass the parsed user ID as a hikari.Snowflake for message command calls.
positional (bool | None, default: None ) –

Whether this should be a positional argument.

Arguments will be positional by default unless default is provided.
slash_name (str, default: '' ) –

The name to use for this option in slash commands.

with_annotated_args #

with_annotated_args(command: _CommandUnionT) -> _CommandUnionT

with_annotated_args(*, follow_wrapped: bool = False) -> collections.Callable[[_CommandUnionT], _CommandUnionT]

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

Set a command's arguments based on its signature.

For more information on how this works see tanjun.annotations.

Parameters:

command (SlashCommand | MessageCommand, default: None ) –

The message or slash command to set the arguments for.
follow_wrapped (bool, default: False ) –

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

Returns:

SlashCommand | MessageCommand –

The command object to enable using this as a decorator.

tanjun.annotations#

Attachment module-attribute #

Bool module-attribute #

Channel module-attribute #

Color module-attribute #

Colour module-attribute #

Datetime module-attribute #

Float module-attribute #

Int module-attribute #

InteractionChannel module-attribute #

InteractionMember module-attribute #

Member module-attribute #

Mentionable module-attribute #

Role module-attribute #

Snowflake module-attribute #

Str module-attribute #

User module-attribute #

Choices #

choices property #

__init__ #

Converted #

converters property #

__init__ #

Default #

default property #

__init__ #

Flag #

aliases property #

default property #

empty_value property #

__init__ #

Greedy #

Length #

max_length property #

min_length property #

__init__ #

Max #

value property #

__init__ #

Min #

value property #

__init__ #

Name #

message_name property #

slash_name property #

__init__ #

Positional #

Ranged #

max_value property #

min_value property #

__init__ #

SnowflakeOr #

parse_id property #

__init__ #

TheseChannels #

channel_types property #

__init__ #

attachment_field #

bool_field #

channel_field #

float_field #

int_field #

member_field #

mentionable_field #

parse_annotated_args #

role_field #

str_field #

user_field #

with_annotated_args #

Attachment `module-attribute` #

Bool `module-attribute` #

Channel `module-attribute` #

Color `module-attribute` #

Colour `module-attribute` #

Datetime `module-attribute` #

Float `module-attribute` #

Int `module-attribute` #

InteractionChannel `module-attribute` #

InteractionMember `module-attribute` #

Member `module-attribute` #

Mentionable `module-attribute` #

Role `module-attribute` #

Snowflake `module-attribute` #

Str `module-attribute` #

User `module-attribute` #

choices `property` #

init #

converters `property` #

init #

default `property` #

init #

aliases `property` #

default `property` #

empty_value `property` #

init #

max_length `property` #

min_length `property` #

init #

value `property` #

init #

value `property` #

init #

message_name `property` #

slash_name `property` #

init #

max_value `property` #

min_value `property` #

init #

parse_id `property` #

init #

channel_types `property` #

init #