parser module

Note

This module is imports as from .. import *. This means that there is no need to import it separately or use ezbotf.argumentparser.parser.Argument. You can simply use ezbotf.argumentparser.Argumentparser as example.

Argument

class ezbotf.argumentparser.Argument(arg_name: str, arg_type: ~ezbotf.argumentparser._casts.ArgTypeCast = <ezbotf.argumentparser._casts.ArgTypeCast object>, default: ~typing.Any | None = None, description: str = 'Sample argument')

Sample argument

__init__(arg_name: str, arg_type: ~ezbotf.argumentparser._casts.ArgTypeCast = <ezbotf.argumentparser._casts.ArgTypeCast object>, default: ~typing.Any | None = None, description: str = 'Sample argument')

Parameters:

arg_name – Name of the argument
arg_type – Type of the argument (NOTE: It must support type-casting with using str)
default – Defines default value of the argument. If it None - argument is marked as required
description – Description of the argument

typecast(input_arg: str) -> (<class 'bool'>, Exception | typing.Any)

Try to type-cast the string argument to the argument type

Parameters:: input_arg – Input argument in the str type
Returns:: Tuple with elements: first is bool (if True then type-casting is return exception, otherwise, if False it is successful), second is type-casted object or Exception (if first is True)

ReplyToArgument

class ezbotf.argumentparser.ReplyToArgument(arg_name: str, arg_type: ~ezbotf.argumentparser._casts.ArgTypeCast = <ezbotf.argumentparser._casts.ArgTypeCast object>, default: ~typing.Any | None = None, description: str = 'Sample argument')

Argument for the Reply-To functional. This is inherits Argument

__init__(arg_name: str, arg_type: ~ezbotf.argumentparser._casts.ArgTypeCast = <ezbotf.argumentparser._casts.ArgTypeCast object>, default: ~typing.Any | None = None, description: str = 'Sample argument')

Parameters:

arg_name – Name of the argument
arg_type – Type of the argument (NOTE: It must support type-casting with using str)
default – Defines default value of the argument. If it None - argument is marked as required
description – Description of the argument

typecast(input_arg: str) -> (<class 'bool'>, Exception | typing.Any)

Try to type-cast the string argument to the argument type

Parameters:: input_arg – Input argument in the str type
Returns:: Tuple with elements: first is bool (if True then type-casting is return exception, otherwise, if False it is successful), second is type-casted object or Exception (if first is True)

ArgumentParser

class ezbotf.argumentparser.ArgumentParser(parent_plugin: Plugin, arguments: list[Argument], allow_caching: bool = True, enable_escaping: bool = False, subcommands: bool = False, main_command_aliases: str | list[str] | None = None, stack_arguments: int = 0)

Helps to manage the arguments

Variables:

parent_plugin – Parent plugin of this parser
arguments – List with the arguments
allow_caching – Use the caching when it parses the arguments
logger – Logger of the argument parser
position_arguments – Number of the position arguments
default_arguments – Number of the default arguments
stack_arguments – Number of the stack arguments

__init__(parent_plugin: Plugin, arguments: list[Argument], allow_caching: bool = True, enable_escaping: bool = False, subcommands: bool = False, main_command_aliases: str | list[str] | None = None, stack_arguments: int = 0)

Parameters:

parent_plugin – Parent plugin of this parser
arguments – List with the arguments
allow_caching – Use the caching when it parses the arguments
enable_escaping – Enable the escaping by “” character
subcommands – Enable the subcommands feature
main_command_aliases – Name of the main commands (requires “subcommands”)
stack_arguments – Is number of “stack” arguments. This is a positional arguments, that doesn’t have name

_cached_check(string: str) → list[str]

Checker for the cached parsed value

Parameters:: string – String to use
Returns:: Executed + new cached result or already cached result of the parse_string() method

parse_string(string: str) → list[str]

Parses the string to the list with the arguments

Parameters:: string – String to parse
Returns:: List with the parsed arguments (raw, string type)

async parse(text: str, event, command_func: ~typing.Coroutine[~telethon.events.common.EventBuilder, ~ezbotf.context.Context, None]) -> (<class 'bool'>, ezbotf.context.Context | ezbotf.argumentparser.argumentparseerror.ArgumentParseError)

Parses text (with command) into the arguments

Parameters:

text – Message text with command
event – Telethon event
command_func – Command function to execute

Returns:

Tuple with elements: first is bool (True if success, False if result is error), second is Context with parsed arguments or ArgumentParseError (if first is False)

subcommand(aliases: str | list | None = None, ap=None)

Decorator, that helps register the new subcommand.: This is redirects to the parent_plugin.command decorator

Parameters:

aliases – Aliases to the command
ap – Argument parser

Returns:

Function with the changed attributes

Example standalone plugin with ArgumentParser usage:

import ezbotf

plugin = ezbotf.Plugin(ezbotf.PluginType.Standalone)

@plugin.on_load
def on_load():

    @plugin.command('lowercase',
                    [ezbotf.argumentparser.ReplyToArgument('rt_text', default='<notset>'),
                     ezbotf.argumentparser.Argument('text', default='<notset>')])
    async def lowercase(event, args):
        if args.rt_text == '<notset>' and args.text == '<notset>':
            await ezbotf.messages.error(event, 'You must reply to any message or write text as first argument')
            return

        text = args.text if args.text != '<notset>' else args.rt_text

        await event.respond(text.lowercase())

Example standalone plugin with ArgumentParser subcommands usage:

import ezbotf

plugin = ezbotf.Plugin(ezbotf.PluginType.Standalone)

@plugin.on_load
def on_load():

    # Define Argument Parser with subcommands
    text_operations_ap = ezbotf.ArgumentParser(
        plugin,
        [],
        subcommands=True,
        main_command_aliases='text'
    )

    # Because lowercase, uppercase is using the same argument scheme, there is created shared arguments list
    shared_text_ops_args = [ezbotf.argumentparser.ReplyToArgument('rt_text', default='<notset>'),
                            ezbotf.argumentparser.Argument('text', default='<notset>')]

    @text_operations_ap.subcommand('lowercase',
                                   shared_text_ops_args)
    async def text_lowercase(event, args):
        if args.rt_text == '<notset>' and args.text == '<notset>':
            await ezbotf.messages.error(event, 'You must reply to any message or write text as first argument')
            return

        text = args.text if args.text != '<notset>' else args.rt_text

        await event.respond(text.lowercase())

    @text_operations_ap.subcommand('uppercase',
                                   shared_text_ops_args)
    async def text_lowercase(event, args):
        if args.rt_text == '<notset>' and args.text == '<notset>':
            await ezbotf.messages.error(event, 'You must reply to any message or write text as first argument')
            return

        text = args.text if args.text != '<notset>' else args.rt_text

        await event.respond(text.uppercase())