Converters¶

The following section outlines all the converters discord_tools offers.

RegexConverter¶

class discord_tools.RegexConverter(pattern, *, use_clean_content=False)[source]¶

A converter that finds a regex on an argument.

Added in version 1.0.

This converter can be used as it follows:

# pattern = re.compile(r"some-regex")

@commands.command()
# async def test(ctx, arg: RegexConverter[pattern]):
async def test(ctx, arg: RegexConverter[r"some-regex"]):
    await ctx.reply(f'{arg} matches!')

Or if you want to have more precise options:

@commands.command()
async def test(ctx, arg: RegexConverter(pattern, **options)):
    await ctx.reply(f'{arg} matches!')

As Python does not know this returns a re.Match object using the previous shown ways, the recommended way is to use Annotated[re.Match[str], RegexConverter[...]]. For example:

@commands.command()
async def test(ctx, arg: typing.Annotated[re.Match[str], RegexConverter[...]]):
    await ctx.reply(f'{arg} matches!')

Parameters:

pattern (Union[re.Pattern, str]) – The pattern to search for. If it is a string it is compiled into a re.Pattern object without any flags.
use_clean_content (bool) – Whether to use the message clean content or not.

Implicit Boolean Flag Converters¶

discord_tools.flag(*, name=..., aliases=..., default=..., max_args=..., override=..., converter=..., description=..., positional=..., implicit=...)[source]¶

Override default functionality and parameters of the underlying FlagConverter class attributes.

Added in version 1.0.

Parameters:

name (str) – The flag name. If not given, defaults to the attribute name.
aliases (List[str]) – Aliases to the flag name. If not given no aliases are set.
default (Any) – The default parameter. This could be either a value or a callable that takes Context as its sole parameter. If not given then it defaults to the default value given to the attribute.
max_args (int) – The maximum number of arguments the flag can accept. A negative value indicates an unlimited amount of arguments. The default value depends on the annotation given.
override (bool) – Whether multiple given values overrides the previous value. The default value depends on the annotation given.
converter (Any) – The converter to use for this flag. This replaces the annotation at runtime which is transparent to type checkers.
description (str) – The description of the flag. Shown for hybrid commands when they’re used as application commands.
positional (bool) – Whether the flag is positional or not. There can only be one positional flag.
implicit (bool) –
Whether the flag is implicit or not. This means that only being present makes the flag value be True, and if not present, False`.

Warning

This can only be used on subclasses of ImplicitBoolFlagConverter.

Note

Settings this to True will change the default and converter values to False and bool, respectively.

Return type:

Any

Flag¶

Attributes

aliases
annotation
attribute
default
description
implicit
max_args
name
override
positional

class discord_tools.Flag(name=..., aliases=<factory>, attribute=..., annotation=..., default=..., max_args=..., override=..., description=..., positional=..., cast_to_dict=False, implicit=...)[source]¶

Represents a flag parameter for a FlagConverter.

The flag() function helps with the creation of these flag objects, but it is not necessary to do so. These cannot be constructed manually.

Added in version 1.0.

name¶

The name of the flag.

Type:: str

aliases¶

The aliases of the flag name.

Type:: List[str]

attribute¶

The attribute in the class that corresponds to this flag.

Type:: str

default¶

The default value of the flag, if available.

Type:: Any

annotation¶

The underlying evaluated annotation of the flag.

Type:: Any

max_args¶

The maximum number of arguments the flag can accept. A negative value indicates an unlimited amount of arguments.

Type:: int

override¶

Whether multiple given values override the previous one.

Type:: bool

description¶

The description of the flag. Shown for hybrid commands when they’re used as application commands.

Type:: str

positional¶

Whether the flag is positional or not. There can only be one positional flag.

Type:: bool

implicit¶

Whether the flag is implicit, this means that only being present makes the flag value True, and if not present, False.

Warning

This can only be used on subclasses of ImplicitBoolFlagConverter.

Note

Settings this to True will change the default and annotation to False and bool, respectively.

Type:: bool

ImplicitBoolFlagConverter¶

class discord_tools.ImplicitBoolFlagConverter[source]¶

A custom discord.ext.commands.FlagConverter subclass that allows boolean flags to not have a value.

Added in version 1.0.

For example:

from discord_tools import ImplicitBoolFlagConverter, flag

class MyFlags(ImplicitBoolFlagConverter):
    some_flag = flag(implicit=True)