Builtins Parser Implementations

Parser implementations for (mostly) builtin types.

Classes

Attributes

• strict

Methods

• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.NoneParser(*, strict=True)

Bases: Parser[None]

Parser implementation for None.

Mainly relevant for Optional[…] parsers.

Parameters:

strict (bool) –

Whether this parser should be set to strict mode.

To prevent unforeseen bugs, this defaults to True.

Attributes

strict: bool

Whether this parser is set to strict mode.

See loads() and dumps() for the implications of strict-mode.

Methods

await dumps(argument, /)

Dump None into a string.

If strict is set to True, this will fail if the provided argument isn’t exactly None. Otherwise, this parser will always return None.

Parameters:

argument (None) – The value that is to be dumped.

Raises:

ValueError: – The parser is in strict mode, and the provided argument was not None.

await loads(argument, /)

Load None from a string.

If strict is set to True, this will fail if the provided argument isn’t the empty string (""). Otherwise, this parser will always return None.

Parameters:

argument (str) – The string that is to be converted to None.

Raises:

ValueError: – The parser is in strict mode, and the provided argument was not the empty string.

Methods

• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.FloatParser

Bases: Parser[float]

Parser implementation for floats.

Methods

await dumps(argument, /)

Dump a floating point number into a string.

Strips trailing “.0” where possible.

Parameters:

argument (float) – The string that is to be converted into a floating point number.

await loads(argument, /)

Load a floating point number from a string.

Parameters:

argument (str) – The value that is to be loaded into a floating point number.

Attributes

• base
• signed

Methods

• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.IntParser(signed=True, base=36)

Bases: Parser[int]

Parser implementation for ints.

Parameters:

• signed (bool) – Whether the parser supports signed integers. Defaults to True.

• base (int) – The base to use to use for storing integers. This is limited to 2 <= base <= 36. Defaults to 36.

Attributes

base: int

The base to use to use for storing integers. This is limited to 2 <= base <= 36 as this is the range supported by python’s int constructor.

If a greater base is required, a custom integer parser will have to be implemented.

signed: bool

Whether the parser supports signed integers.

Methods

await dumps(argument, /)

Dump an integer into a string.

Parameters:

argument (int) – The value that is to be dumped.

await loads(argument, /)

Load an integer from a string.

Parameters:

argument (str) – The string that is to be converted to an int.

Raises:

ValueError: – The parser has signed set to False but the argument was a negative number. Alternatively, the provided argument is not a valid integer at all.

Attributes

• falses
• trues

Methods

• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.BoolParser(trues=NOTHING, falses=NOTHING)

Bases: Parser[bool]

Parser type with support for bools.

This parser type can be supplied with a collection of strings for the values that should be considered true and false. By default, "true", "t", "yes", "y", "1" are considered True, while "false", "f", "no", "n", "0" are considered False. Note that this is case-insensitive.

Parameters:

• trues (Collection[str]) – Values that should be considered True by this parser.

• falses (Collection[str]) – Values that should be considered False by this parser.

Attributes

falses: Collection[str]

A collection of values that should be considered False by this parser.

trues: Collection[str]

A collection of values that should be considered True by this parser.

Methods

await dumps(argument, /)

Dump a boolean into a string.

By default, this opts to dump as "1" for True or "0" for False to only use one character’s worth of space from the custom id.

Parameters:

argument (bool) – The value that is to be dumped.

await loads(argument, /)

Load a boolean from a string.

Parameters:

argument (str) – The string that is to be converted into a boolean.

Raises:

ValueError: – The string is not in trues or falses.

Methods

• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.StringParser

Bases: Parser[str]

Parser type with support for strings.

Both loads and dumps are essentially no-ops.

Methods

await dumps(argument, /)

Dump a string into a string.

Parameters:

argument (str) – The value that is to be dumped.

await loads(argument, /)

Load a string from a string.

Parameters:

argument (str) – The string that is to be converted into a string.

Attributes

• inner_parsers
• sep
• tuple_cls

Methods

• clsdefault
• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.TupleParser(*inner_parsers, sep=', ', tuple_cls=<class 'tuple'>)

Bases: Parser[_TupleT]

Parser type with support for tuples.

The benefit of a tuple parser is fixed-length checks and the ability to set multiple types. For example, a Tuple[str, int, bool] parser will actually return a tuple with a str, int, and bool inside.

Parameters:

• *inner_parsers (parser_api.Parser[typing.Any]) –

  The parsers to use to parse the items inside the tuple.

  Defaults to a single string parser, i.e. a one-element tuple containing exactly one string.

• sep (str) –

  The separator to use.

  Defaults to “,”.

Attributes

inner_parsers: tuple[parser_api.Parser[typing.Any], ...]

The parsers to use to parse the items inside the tuple.

These define the inner types and the allowed number of items in the in the tuple.

sep: str

The separator to use.

Can be any string, though a single character is recommended.

Warning

Ensure that this does not match ComponentManager.sep on the component manager that corresponds to this parser’s component.

tuple_cls: type[_TupleT]

The tuple type to use.

This mainly exists to support NamedTuples.

Methods

classmethod default(type_, /)

Return the default implementation of this parser type.

By default, this will just create the parser class with no arguments, but this can be overwritten on child classes for customised behaviour.

Parameters:

target_type – The exact type that this parser should be created for

Returns:

The default parser instance for this parser type.

Return type:

Parser

await dumps(argument, /)

Dump a tuple into a string.

Parameters:

argument (_TupleT) – The value that is to be dumped.

Raises:

RuntimeError – The length of the argument tuple does not match the number of inner parsers.

await loads(argument, /)

Load a tuple from a string.

Parameters:

argument (str) –

The string that is to be converted into a tuple.

This is split over sep and then each individual substring is passed to its respective inner parser.

Raises:

RuntimeError: – The number of substrings after splitting does not match the number of inner parsers.

Attributes

• collection_type
• inner_parser
• sep

Methods

• clsdefault
• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.CollectionParser(inner_parser=None, *, collection_type=None, sep=',')

Bases: Parser[_CollectionT]

Parser type with support for typing.Collections.

This supports types such as list, set, etc.; but also abstract types such as typing.Collection itself.

Note

This parser does not support tuples.

Parameters:

• inner_parser (parser_api.Parser[typing.Any] | None) –

  The parser to use to parse the items inside the collection.

  This defines the inner type for the collection.

  Defaults to a StringParser.

• collection_type (type[_CollectionT] | None) –

  The type of collection to use. This does not specify the inner type.

  Defaults to list.

• sep (str) –

  The separator to use.

  Can be any string, though a single character is recommended.

  Defaults to ",".

Attributes

collection_type: type[_CollectionT]

The collection type for this parser.

This is the type that holds the items, e.g. a list.

Note

This has to support being instantiated from an iterable as collection_type(iterable_of_values); e.g. set([1,2,3])

inner_parser: parser_api.Parser[typing.Any]

The parser to use to parse the items inside the collection.

Note that, unlike a TupleParser, a collection parser requires all items to be of the same type.

sep: str

The separator to use.

Can be any string, though a single character is recommended.

Warning

Ensure that this does not match ComponentManager.sep on the component manager that corresponds to this parser’s component.

Methods

classmethod default(type_, /)

Return the default implementation of this parser type.

By default, this will just create the parser class with no arguments, but this can be overwritten on child classes for customised behaviour.

Parameters:

target_type – The exact type that this parser should be created for

Returns:

The default parser instance for this parser type.

Return type:

Parser

await dumps(argument, /)

Dump a collection into a string.

Parameters:

argument (_CollectionT) – The value that is to be dumped.

await loads(argument, /)

Load a collection from a string.

Parameters:

argument (str) –

The string that is to be converted into a collection.

This is split over sep and then each individual substring is passed to its respective inner parser.

Attributes

• inner_parsers
• optional
• strict

Methods

• clsdefault
• asyncdumps
• asyncloads

class disnake_compass.impl.parser.builtins.UnionParser(*inner_parsers)

Bases: Parser[_T], Generic[_T]

Parser type with support for Unions.

The provided parsers are sequentially tried until one passes. If none work, an exception is raised instead.

Important

Unlike NoneParser, strict for this class is set via the underlying none parser, if any. Note that this class does proxy it through the strict property, which supports both getting and setting; but only if this parser is optional.

Parameters:

*inner_parsers (parser_api.Parser[typing.Any] | None) –

The parsers with which to sequentially try to parse the argument.

None can be provided as one of the parameters to make it optional; this will automatically add a strict NoneParser.

Attributes

inner_parsers: typing.Sequence[parser_api.Parser[typing.Any]]

The parsers with which to sequentially try to parse the argument.

optional: bool

Whether this parser is optional.

property strict: bool

Whether this parser is strict.

This is only meaningful when the parser is optional, in which case it directly reflects NoneParser.strict.

Methods

classmethod default(type_, /)

Return the default implementation of this parser type.

By default, this will just create the parser class with no arguments, but this can be overwritten on child classes for customised behaviour.

Parameters:

target_type – The exact type that this parser should be created for

Returns:

The default parser instance for this parser type.

Return type:

Parser

await dumps(argument, /)

Dump a union of types into a string.

Parameters:

argument (_T) –

The value that is to be dumped.

This finds a parser that is registered for the type of the provided argument.

Raises:

RuntimeError – None of the inner_parsers succeeded to dump the argument.

await loads(argument, /)

Load a union of types from a string.

If optional is True and strict is False, this returns None if all parsers fail. Otherwise, an exception is raised.

Parameters:

argument (str) –

The string that is to be converted into one of the types in this union.

Each inner parser is tried in the order they are provided, and the first to load the argument successfully short-circuits and returns.

Raises:

RuntimeError – None of the inner_parsers succeeded to load the argument.