Parser Base Implementation#

Implementation of parser base classes upon which actual parsers are built.

Functions#

components.impl.parser.base.get_parser(type_)[source]#

Get the default parser for the provided type.

Note that type annotations such as Union[int, str] are also valid.

Parameters:

type_ (Type[_T]) – The type for which to return the default parser.

Returns:

The default parser for the provided type.

Return type:

Parser[T]

Raises:

TypeError – Could not create a parser for the provided type.

components.impl.parser.base.register_parser(parser, *types, force=True)[source]#

Register a parser class as the default parser for the provided type.

The default parser will automatically be used for any field annotated with that type. For example, the default parser for integers is components.IntParser, an instance of which will automatically be assigned to any custom id fields annotated with int.

Parameters:

  • parser (Type[Parser[_T]]) – The parser to register.

  • *types (Type[_T]) – The types for which to register the provided parser as the default.

  • force (bool) – Whether or not to overwrite existing defaults. Defaults to True.

Classes#

Methods
class components.impl.parser.base.Parser(*args, **kwargs)[source]#

Bases: Parser[_T], Protocol[_T]

Class that handles parsing of one custom id field to and from a desired type.

A parser contains two main methods, loads() and dumps(). loads, like json.loads() serves to turn a string value into a different type. Similarly, dumps serves to convert that type back into a string.

Simpler parsers can also be generated from loads and dumps functions using from_funcs(), so as to not have to define an entire class.

classmethod default()[source]#

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.

Returns:

The default parser instance for this parser type.

Return type:

Parser

classmethod default_types()[source]#

Return the types for which this parser type is the default implementation.

Returns:

The types for which this parser type is the default implementation.

Return type:

Sequence[type]

dumps(argument, /)[source]#

Dump a value from a given type and convert it to a string.

In most cases it is imperative to ensure that this is done in a reversible way, such that calling loads() on the result of this function returns the original input. For example:

>>> parser = IntParser()
>>> input_str = "1"
>>> parsed_int = parser.loads(input_str)
>>> dumped_int = parser.dumps(parsed_int)
>>> input_str == dumped_int
True

Any errors raised inside this method remain unmodified, and should be handled externally.

Note

This method can be either sync or async.

Parameters:

argument (_T) – The argument to parse into the desired type.

Returns:

  • str – In case the parser method was sync, the resulting dumped argument.

  • Coroutine[str] – In case the parser method was async, the parser naturally returns a coroutine. Awaiting this coroutine returns the dumped argument.

classmethod from_funcs(loads, dumps, *, is_default_for=None)[source]#

Generate a parser class from loads and dumps functions.

Warning

The loads and dumps functions must not have a self argument. They are treated as static methods. If a self argument is required, consider making a parser class through inheritance instead.

Parameters:

  • loads (Callable[[Any, str], Coroutine[None, None, _T] | _T]) – A function that serves to turn a string value into a different type, similar to json.loads(). This function can be either sync or async.

  • dumps (Callable[[_T], Coroutine[None, None, str] | str]) – A function that serves to turn a value of a given type back into a string, similar to json.dumps(). This function can be either sync or async.

  • is_default_for (Optional[Sequence[type]]) – The types for which to register the newly created parser class as the default parser. By default, the parser is not registered as the default for any types.

Returns:

The newly created parser class.

Return type:

type[Parser]

loads(source, argument, /)[source]#

Load a value from a string and apply the necessary conversion logic.

Any errors raised inside this method remain unmodified, and should be handled externally.

Note

This method can be either sync or async.

Parameters:

  • source (Any) – The source object with which the argument should be parsed. For example, parsing a disnake.Member uses the source to determine the guild from which the member should be derived. In this case, the source should be any object that defines .guild.

  • argument (str) – The argument to parse into the desired type.

Returns:

  • ParserType – In case the parser method was sync, the parsed result is returned as-is.

  • Coroutine[ParserType] – In case the parser method was async, the parser naturally returns a coroutine. Awaiting this coroutine returns the parser result.