Skip to content

tanjun.parsing#

Standard implementation of message command argument parsing.

ConverterSig module-attribute #

ConverterSig = collections.Callable[typing_extensions.Concatenate[str, ...], typing.Union[collections.Coroutine[typing.Any, typing.Any, _T], _T]]

Type hint of a converter used within a parser instance.

This represents the signatures def (str, ...) -> Any and async def (str, ...) -> Any where dependency injection is supported.

UNDEFINED module-attribute #

UNDEFINED = tanjun.NO_DEFAULT

Deprecated alias of tanjun.abc.NO_DEFAULT.

UNDEFINED_DEFAULT module-attribute #

UNDEFINED_DEFAULT = tanjun.NO_DEFAULT

Deprecated alias of tanjun.abc.NO_DEFAULT.

UndefinedDefaultT module-attribute #

UndefinedDefaultT = UndefinedT

Deprecated alias of typing.Literal[tanjun.abc.NO_DEFAULT].

UndefinedT module-attribute #

UndefinedT = tanjun.NoDefault

Deprecated alias of typing.Literal[tanjun.abc.NO_DEFAULT].

AbstractOptionParser #

Bases: MessageParser, ABC

Abstract interface of a message content parser.

arguments abstractmethod property #

arguments: collections.Sequence[Argument]

Sequence of the positional arguments registered with this parser.

options abstractmethod property #

options: collections.Sequence[Option]

Sequence of the named options registered with this parser.

add_argument abstractmethod #

add_argument(key, /, converters=(), *, default=tanjun.NO_DEFAULT, greedy=False, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Add a positional argument type to the parser..

Note

Order matters for positional arguments.

Parameters:

  • key (str) –

    The string identifier of this argument (may be used to pass the result of this argument to the command's callback during execution).

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • default (Any, default: NO_DEFAULT ) –

    The default value of this argument, if left as tanjun.abc.NO_DEFAULT then this will have no default.

    If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.

  • greedy (bool, default: False ) –

    Whether or not this argument should be greedy (meaning that it takes in the remaining argument values).

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • multi (bool, default: False ) –

    Whether this argument can be passed multiple times.

Returns:

  • Self –

    This parser to enable chained calls.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this parser is linked to where validate_arg_keys is True.

add_option abstractmethod #

add_option(key, name, /, *names, converters=(), default, empty_value=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Add an named option to this parser.

Parameters:

  • key (str) –

    The string identifier of this option which will be used to pass the result of this option to the command's callback during execution as a keyword argument.

  • name (str) –

    The name of this option used for identifying it in the parsed content.

  • *names (str, default: () ) –

    Other names of this option used for identifying it in the parsed content.

  • default (Any) –

    The default value of this option, unlike arguments this is required for options.

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

    The converter(s) this option should use to handle values passed to it during parsing.

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • empty_value (Any, default: NO_DEFAULT ) –

    The value to use if this option is provided without a value.

    If left as tanjun.abc.NO_DEFAULT then this option will error if it's provided without a value.

    tanjun.abc.NO_PASS is not supported for this.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • multi (bool, default: False ) –

    If this option can be provided multiple times.

Returns:

  • Self –

    This parser to enable chained calls.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this parser is linked to where validate_arg_keys is True.

copy abstractmethod #

copy()

Copy the parser.

Returns:

  • Self –

    A copy of the parser.

parse abstractmethod async #

parse(ctx)

Parse a message context.

Warning

This relies on the prefix and command name(s) having been removed from MessageContext.content.

Parameters:

Returns:

  • dict[str, Any] –

    Dictionary of argument names to the parsed values for them.

Raises:

validate_arg_keys abstractmethod #

validate_arg_keys(callback_name, names)

Validate that callback's keyword arguments are all valid for this parser.

Parameters:

  • callback_name (str) –

    The callback's name for use in raised errors.

  • names (abc.Container[str]) –

    Key names of the callback's keyword arguments.

Raises:

  • ValueError –

    If any of the parameter keys aren't valid for this parser.

AbstractParser #

Bases: AbstractOptionParser

Deprecated alias of AbstractOptionParser.

arguments abstractmethod property #

arguments: collections.Sequence[Argument]

Sequence of the positional arguments registered with this parser.

options abstractmethod property #

options: collections.Sequence[Option]

Sequence of the named options registered with this parser.

add_argument abstractmethod #

add_argument(key, /, converters=(), *, default=tanjun.NO_DEFAULT, greedy=False, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Add a positional argument type to the parser..

Note

Order matters for positional arguments.

Parameters:

  • key (str) –

    The string identifier of this argument (may be used to pass the result of this argument to the command's callback during execution).

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • default (Any, default: NO_DEFAULT ) –

    The default value of this argument, if left as tanjun.abc.NO_DEFAULT then this will have no default.

    If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.

  • greedy (bool, default: False ) –

    Whether or not this argument should be greedy (meaning that it takes in the remaining argument values).

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • multi (bool, default: False ) –

    Whether this argument can be passed multiple times.

Returns:

  • Self –

    This parser to enable chained calls.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this parser is linked to where validate_arg_keys is True.

add_option abstractmethod #

add_option(key, name, /, *names, converters=(), default, empty_value=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Add an named option to this parser.

Parameters:

  • key (str) –

    The string identifier of this option which will be used to pass the result of this option to the command's callback during execution as a keyword argument.

  • name (str) –

    The name of this option used for identifying it in the parsed content.

  • *names (str, default: () ) –

    Other names of this option used for identifying it in the parsed content.

  • default (Any) –

    The default value of this option, unlike arguments this is required for options.

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

    The converter(s) this option should use to handle values passed to it during parsing.

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • empty_value (Any, default: NO_DEFAULT ) –

    The value to use if this option is provided without a value.

    If left as tanjun.abc.NO_DEFAULT then this option will error if it's provided without a value.

    tanjun.abc.NO_PASS is not supported for this.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • multi (bool, default: False ) –

    If this option can be provided multiple times.

Returns:

  • Self –

    This parser to enable chained calls.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this parser is linked to where validate_arg_keys is True.

copy abstractmethod #

copy()

Copy the parser.

Returns:

  • Self –

    A copy of the parser.

parse abstractmethod async #

parse(ctx)

Parse a message context.

Warning

This relies on the prefix and command name(s) having been removed from MessageContext.content.

Parameters:

Returns:

  • dict[str, Any] –

    Dictionary of argument names to the parsed values for them.

Raises:

validate_arg_keys abstractmethod #

validate_arg_keys(callback_name, names)

Validate that callback's keyword arguments are all valid for this parser.

Parameters:

  • callback_name (str) –

    The callback's name for use in raised errors.

  • names (abc.Container[str]) –

    Key names of the callback's keyword arguments.

Raises:

  • ValueError –

    If any of the parameter keys aren't valid for this parser.

Argument #

Bases: Parameter

Representation of a positional argument used by the standard parser.

converters property #

converters: collections.Sequence[ConverterSig[typing.Any]]

Sequence of the converters registered for this parameter.

default property #

default: typing.Any

The parameter's default.

If this is tanjun.abc.NO_DEFAULT then this parameter is required.

If this is tanjun.abc.NO_PASS then the parameter won't be passed when no value was provided.

is_greedy property #

is_greedy: bool

Whether this parameter is greedy.

Greedy parameters will consume the remaining message content as one string (with converters also being passed the whole string).

Note

Greedy and multi parameters cannot be used together.

is_multi property #

is_multi: bool

Whether this parameter is "multi".

Multi parameters will be passed a list of all the values provided for this parameter (with each entry being converted separately).

key property #

key: str

The key of this parameter used to pass the result to the command's callback.

max_length property #

max_length: typing.Optional[int]

If set, this parameters's parsed values will have to have lengths less than or equal to this.

If any converters are provided then this should be compatible with the result of them.

max_value property #

max_value: typing.Optional[_CmpProto[typing.Any]]

If set, this parameters's parsed values will have to be less than or equal to this.

If any converters are provided then this should be compatible with the result of them.

min_length property #

min_length: typing.Optional[int]

If set, this parameters's parsed values will have to have lengths greater than or equal to this.

If any converters are provided then this should be compatible with the result of them.

min_value property #

min_value: typing.Optional[_CmpProto[typing.Any]]

If set, this parameters's parsed values will have to be greater than or equal to this.

If any converters are provided then this should be compatible with the result of them.

__init__ #

__init__(key, /, *, converters=(), default=tanjun.NO_DEFAULT, greedy=False, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Initialise a positional argument.

Parameters:

  • key (str) –

    The string identifier of this argument (may be used to pass the result of this argument to the command's callback during execution).

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • default (Any, default: NO_DEFAULT ) –

    The default value of this argument, if left as tanjun.abc.NO_DEFAULT then this will have no default.

    If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.

  • greedy (bool, default: False ) –

    Whether or not this argument should be greedy (meaning that it takes in the remaining argument values).

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

multi Whether this argument can be passed multiple times.

convert async #

convert(ctx, value)

Convert the given value to the type of this parameter.

copy #

copy()

Copy the parameter.

Returns:

  • Self –

    A copy of the parameter.

Option #

Bases: Parameter

Representation of a named optional parameter used by the standard parser.

converters property #

converters: collections.Sequence[ConverterSig[typing.Any]]

Sequence of the converters registered for this parameter.

default property #

default: typing.Any

The parameter's default.

If this is tanjun.abc.NO_DEFAULT then this parameter is required.

If this is tanjun.abc.NO_PASS then the parameter won't be passed when no value was provided.

empty_value property #

empty_value: typing.Any

The value to return if the option is empty.

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

is_multi property #

is_multi: bool

Whether this parameter is "multi".

Multi parameters will be passed a list of all the values provided for this parameter (with each entry being converted separately).

key property #

key: str

The key of this parameter used to pass the result to the command's callback.

max_length property #

max_length: typing.Optional[int]

If set, this parameters's parsed values will have to have lengths less than or equal to this.

If any converters are provided then this should be compatible with the result of them.

max_value property #

max_value: typing.Optional[_CmpProto[typing.Any]]

If set, this parameters's parsed values will have to be less than or equal to this.

If any converters are provided then this should be compatible with the result of them.

min_length property #

min_length: typing.Optional[int]

If set, this parameters's parsed values will have to have lengths greater than or equal to this.

If any converters are provided then this should be compatible with the result of them.

min_value property #

min_value: typing.Optional[_CmpProto[typing.Any]]

If set, this parameters's parsed values will have to be greater than or equal to this.

If any converters are provided then this should be compatible with the result of them.

names property #

names: collections.Sequence[str]

Sequence of the CLI names of this option.

__init__ #

__init__(key, name, /, *names, converters=(), default, empty_value=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None, multi=True)

Initialise a named optional parameter.

Parameters:

  • key (str) –

    The string identifier of this option which will be used to pass the result of this argument to the command's callback during execution as a keyword argument.

  • name (str) –

    The name of this option used for identifying it in the parsed content.

  • *names (str, default: () ) –

    Other names of this option used for identifying it in the parsed content.

  • default (Any) –

    The default value of this argument, unlike arguments this is required for options.

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • empty_value (Any, default: NO_DEFAULT ) –

    The value to use if this option is provided without a value.

    If left as tanjun.abc.NO_DEFAULT then this option will error if it's provided without a value.

    tanjun.abc.NO_PASS is not supported for this.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

multi If this option can be provided multiple times.

convert async #

convert(ctx, value)

Convert the given value to the type of this parameter.

copy #

copy()

Copy the parameter.

Returns:

  • Self –

    A copy of the parameter.

Parameter #

Base class for parameters for the standard parser(s).

converters property #

converters: collections.Sequence[ConverterSig[typing.Any]]

Sequence of the converters registered for this parameter.

default property #

default: typing.Any

The parameter's default.

If this is tanjun.abc.NO_DEFAULT then this parameter is required.

If this is tanjun.abc.NO_PASS then the parameter won't be passed when no value was provided.

is_multi property #

is_multi: bool

Whether this parameter is "multi".

Multi parameters will be passed a list of all the values provided for this parameter (with each entry being converted separately).

key property #

key: str

The key of this parameter used to pass the result to the command's callback.

max_length property #

max_length: typing.Optional[int]

If set, this parameters's parsed values will have to have lengths less than or equal to this.

If any converters are provided then this should be compatible with the result of them.

max_value property #

max_value: typing.Optional[_CmpProto[typing.Any]]

If set, this parameters's parsed values will have to be less than or equal to this.

If any converters are provided then this should be compatible with the result of them.

min_length property #

min_length: typing.Optional[int]

If set, this parameters's parsed values will have to have lengths greater than or equal to this.

If any converters are provided then this should be compatible with the result of them.

min_value property #

min_value: typing.Optional[_CmpProto[typing.Any]]

If set, this parameters's parsed values will have to be greater than or equal to this.

If any converters are provided then this should be compatible with the result of them.

__init__ #

__init__(key, /, *, converters=(), default=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Initialise a parameter.

convert async #

convert(ctx, value)

Convert the given value to the type of this parameter.

copy #

copy()

Copy the parameter.

Returns:

  • Self –

    A copy of the parameter.

ShlexParser #

Bases: AbstractOptionParser

A shlex based AbstractOptionParser implementation.

__init__ #

__init__()

Initialise a shlex parser.

with_argument #

with_argument(key, /, converters=(), *, default=tanjun.NO_DEFAULT, greedy=False, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Add an argument to a message command through a decorator call.

Warning

Since order matters for positional arguments, you'll want to keep in mind that decorator execution starts at the decorator closest to the command and goes upwards with this deciding where a positional argument is located in a command's signature.

Note

If no parser is explicitly set on the command this is decorating before this decorator call then this will set ShlexParser as the parser.

Examples:

import tanjun

@tanjun.parsing.with_argument("command", converters=int, default=42)
@tanjun.parsing.with_parser
@tanjun.component.as_message_command("command")
async def command(self, ctx: tanjun.abc.Context, /, argument: int):
    ...

Parameters:

  • key (str) –

    The string identifier of this argument (may be used to pass the result of this argument to the command's callback during execution).

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • default (Any, default: NO_DEFAULT ) –

    The default value of this argument, if left as tanjun.abc.NO_DEFAULT then this will have no default.

    If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.

  • greedy (bool, default: False ) –

    Whether or not this argument should be greedy (meaning that it takes in the remaining argument values).

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

multi Whether this argument can be passed multiple times.

Returns:

  • collections.abc.Callable[[tanjun.abc.MessageCommand], tanjun.abc.MessageCommand]: –

    Decorator function for the message command this argument is being added to.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this command's parser is linked to where validate_arg_keys is True.

with_greedy_argument #

with_greedy_argument(key, /, converters=(), *, default=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None)

Add a greedy argument to a message command through a decorator call.

A greedy argument will consume the remaining positional arguments and pass them through to the converters as one joined string while also requiring that at least one more positional argument is remaining unless a default is set.

Warning

Since order matters for positional arguments, you'll want to keep in mind that decorator execution starts at the decorator closest to the command and goes upwards with this deciding where a positional argument is located in a command's signature.

Note

If no parser is explicitly set on the command this is decorating before this decorator call then this will set ShlexParser as the parser.

Examples:

import tanjun

@tanjun.parsing.with_greedy_argument("command", converters=StringView)
@tanjun.parsing.with_parser
@tanjun.component.as_message_command("command")
async def command(self, ctx: tanjun.abc.Context, /, argument: StringView):
    ...

Parameters:

  • key (str) –

    The string identifier of this argument (may be used to pass the result of this argument to the command's callback during execution).

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • default (Any, default: NO_DEFAULT ) –

    The default value of this argument, if left as tanjun.abc.NO_DEFAULT then this will have no default.

    If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.

    If any converters are provided then this should be compatible with the result of them.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

Returns:

  • collections.abc.Callable[[tanjun.abc.MessageCommand], tanjun.abc.MessageCommand]: –

    Decorator function for the message command this argument is being added to.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this command's parser is linked to where validate_arg_keys is True.

with_multi_argument #

with_multi_argument(key, /, converters=(), *, default=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None)

Add a multi-argument to a message command through a decorator call.

A multi argument will consume the remaining positional arguments and pass them to the converters through multiple calls while also requiring that at least one more positional argument is remaining unless a default is set and passing through the results to the command's callback as a sequence.

Warning

Since order matters for positional arguments, you'll want to keep in mind that decorator execution starts at the decorator closest to the command and goes upwards with this deciding where a positional argument is located in a command's signature.

Note

If no parser is explicitly set on the command this is decorating before this decorator call then this will set ShlexParser as the parser.

Examples:

import tanjun

@tanjun.parsing.with_multi_argument("command", converters=int)
@tanjun.parsing.with_parser
@tanjun.component.as_message_command("command")
async def command(self, ctx: tanjun.abc.Context, /, argument: collections.abc.Sequence[int]):
    ...

Parameters:

  • key (str) –

    The string identifier of this argument (may be used to pass the result of this argument to the command's callback during execution).

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • default (Any, default: NO_DEFAULT ) –

    The default value of this argument, if left as tanjun.abc.NO_DEFAULT then this will have no default.

    If this is tanjun.abc.NO_PASS then the key parameter won't be passed when no value was provided.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this argument are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

Returns:

  • collections.abc.Callable[[tanjun.abc.MessageCommand], tanjun.abc.MessageCommand]: –

    Decorator function for the message command this argument is being added to.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this command's parser is linked to where validate_arg_keys is True.

with_multi_option #

with_multi_option(key, name, /, *names, converters=(), default, empty_value=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None)

Add an multi-option to a command's parser through a decorator call.

A multi option will consume all the values provided for an option and pass them through to the converters as an array of strings while also requiring that at least one value is provided for the option unless a default is set.

Note

If no parser is explicitly set on the command this is decorating before this decorator call then this will set ShlexParser as the parser.

Examples:

import tanjun

@tanjun.parsing.with_multi_option("command", converters=int, default=())
@tanjun.parsing.with_parser
@tanjun.component.as_message_command("command")
async def command(self, ctx: tanjun.abc.Context, /, argument: collections.abc.Sequence[int]):
    ...

Parameters:

  • key (str) –

    The string identifier of this option which will be used to pass the result of this argument to the command's callback during execution as a keyword argument.

  • name (str) –

    The name of this option used for identifying it in the parsed content.

  • *names (str, default: () ) –

    Other names of this option used for identifying it in the parsed content.

  • default (Any) –

    The default value of this argument, unlike arguments this is required for options.

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • empty_value (Any, default: NO_DEFAULT ) –

    The value to use if this option is provided without a value.

    If left as tanjun.abc.NO_DEFAULT then this option will error if it's provided without a value.

    tanjun.abc.NO_PASS is not supported for this.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

Returns:

  • collections.abc.Callable[[tanjun.abc.MessageCommand], tanjun.abc.MessageCommand]: –

    Decorator function for the message command this option is being added to.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this command's parser is linked to where validate_arg_keys is True.

with_option #

with_option(key, name, /, *names, converters=(), default, empty_value=tanjun.NO_DEFAULT, min_length=None, max_length=None, min_value=None, max_value=None, multi=False)

Add an option to a message command through a decorator call.

Note

If no parser is explicitly set on the command this is decorating before this decorator call then this will set ShlexParser as the parser.

Examples:

import tanjun

@tanjun.parsing.with_option("command", converters=int, default=42)
@tanjun.parsing.with_parser
@tanjun.component.as_message_command("command")
async def command(self, ctx: tanjun.abc.Context, /, argument: int):
    ...

Parameters:

  • key (str) –

    The string identifier of this option which will be used to pass the result of this argument to the command's callback during execution as a keyword argument.

  • name (str) –

    The name of this option used for identifying it in the parsed content.

  • *names (str, default: () ) –

    Other names of this option used for identifying it in the parsed content.

  • default (Any) –

    The default value of this argument, unlike arguments this is required for options.

  • converters (_MaybeIterable[ConverterSig[typing.Any]], default: () ) –

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

    If no converters are provided then the raw string value will be passed.

    Only the first converter to pass will be used.

  • empty_value (Any, default: NO_DEFAULT ) –

    The value to use if this option is provided without a value.

    If left as tanjun.abc.NO_DEFAULT then this option will error if it's provided without a value.

    tanjun.abc.NO_PASS is not supported for this.

  • min_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_length (typing.Optional[int], default: None ) –

    Assert that a string argument's length is less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • min_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are greater than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • max_value (typing.Optional[_CmpProto[typing.Any]], default: None ) –

    Assert that the parsed value(s) for this option are less than or equal to this.

    If any converters are provided then this should be compatible with the result of them.

  • multi (bool, default: False ) –

    If this option can be provided multiple times.

Returns:

  • collections.abc.Callable[[tanjun.abc.MessageCommand], tanjun.abc.MessageCommand]: –

    Decorator function for the message command this option is being added to.

Raises:

  • ValueError –

    If key isn't valid for any of the commands this command's parser is linked to where validate_arg_keys is True.

with_parser #

with_parser(command)

Add a shlex parser command parser to a supported command.

Example#

@tanjun.with_argument("arg", converters=int)
@tanjun.with_parser
@tanjun.as_message_command("hi")
async def hi(ctx: tanjun.MessageContext, arg: int) -> None:
    ...

Parameters:

  • command (_CommandT) –

    The message command to set the parser on.

Returns:

  • MessageCommand –

    The command with the parser set.

Raises:

  • ValueError –

    If the command already has a parser set.