Parser API#

Protocols for parser types.

Typing#

components.api.parser.ParserType = ~ParserType#

A typevar denoting the type of the parser.

A parser of a given type takes (any subclass of) that type as argument to Parser.dumps(), and returns (any subclass of) that type from Parser.loads().

Classes#

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

Bases: Protocol[ParserType]

The baseline protocol for any kind of parser.

Any and all parser types must implement this protocol in order to be properly handled by disnake-ext-components.

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 (ParserType) – 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.

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 (object) – 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.