plugin module

Note

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

There is defined one of main classes - Plugin. This module is contains all required to write a plugin.

There is example of a standalone plugin:

import ezbotf

plugin = Plugin(PluginType.Standalone)

@plugin.on_load
def on_load():

    @plugin.command('example')
    async def example(event, args):
        await ezbotf.messages.info(event, 'This is an example')

Note

You must follow plugin developing guide, check Quick start

PluginType

Enum with possible types of the plugin.

class ezbotf.PluginType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Enum of the plugin types

Variables:

CoreLibrary – Marks plugin as Core Library
Core – Marks plugin as Core
Library – Marks plugin as Library
Standalone – Marks plugin as Standalone

Plugin

Warning

Examples there does not use translations system. This is only examples. In real cases, recommended to use translation system! Also, these examples doesn’t use permissions system. Of course, in real cases, you must use it!

class ezbotf.Plugin(type_: PluginType = PluginType.Standalone)

Class of the plugins

Variables:

type – Type of the plugin
logger – Logger of the plugin
context – Link to the working context (InstanceContext)
translator – Translator instance
dir – Path to the plugin directory
runtime_config – TOML dictionary with the runtime config
loaded – Plugin is loaded? When plugin is not loaded, almost all variables is None
enabled – Plugin is enabled? When plugin is disabled, all commands and other will not work
failed – Plugin is failed? When plugin is failed, it works as disabled. Failing is going on exceptions
commands – Dictionary with the commands of the plugin
mod – Module of this plugin
on_install_funcs – List with the binders to on_install event
on_setup_funcs – List with the binders to on_setup event
on_load_funcs – List with the binders to on_load event
on_unload_funcs – List with the binders to on_unload event
on_start_funcs – List with the binders to on_start event

__init__(type_: PluginType = PluginType.Standalone)

Parameters:: type – Type of the plugin

fail(): Marks a plugin as failed and logs an error about plugin fail

is_installed() → bool

Checks for the .installed file in the plugin directory.

Returns:: True if the file is exists, otherwise False

is_disabled()

Checks for the .disabled file in the plugin directory.

Returns:: True if the file is exists, otherwise False

_install(): Calls all on_install wrappers and marks it installed

_setup(): Setups a plugin and calls all on_setup wrappers

_load(): Calls all on_load wrappers

_unload(): Calls all on_unload wrappers

_start(): Calls all on_start wrappers

on_install(func: Callable[[Self], None]) → Callable[[Self], None]

Decorator takes function that be called on plugin installation. on_install event checks output of all wrappers to event. If any return False, installation is failed. If all on_install event wrappers returned True, then installation is successful and plugin marks as installed.

Note

This event called only once, when plugin is installing. After installation, plugin marks as installed, and on_install event never be called.

Example:

Plugin config “plugin.toml”:

name     = 'ExampleRequirements'  # name of the plugin
version  = '1.0.0'                # version of the plugin
author   = 'ftdot'                # paste here your name

description       = 'Test requirements'  # small description of the plugin

# full description of the plugin (you may describe plugin in details)
full_description  = 'This is the test only plugin. There no big functional'

[executable]
main_file   = 'main.py'  # file with the main plugin class
main_class  = 'plugin'   # name of the plugin instance

[lang]
default  = 'en'      # default language of the plugin
langs    = [ 'en' ]  # supported languages

[requirements]
file = 'requirements.txt'
framework = []
plugins = [['ExampleLib', ['>=', '1.0.0'], ['<=', '1.0.1']]]

Note

To get code of required ExampleLib plugin, see bottom (in on_load() example)

Plugin “requirements.txt”:

prettytable

Plugin executable “main.py”:

import ezbotf

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

@plugin.on_install
def install_requirements():
    return ezbotf.utils.install_requirements(plugin)

@plugin.on_install
def check_required_plugins():
    return ezbotf.utils.check_required_plugins(plugin)

@plugin.on_load
def on_load():

    from prettytable import PrettyTable  # you must import your requirements inside on_load event!

    @plugin.command('test')
    async def test(event, args):

        # check if examplelib is exists in working context
        if 'examplelib' not in dir(plugin.context):
            await ezbotf.message.error(event, 'To this plugin is work required `ExampleLib` library!')
            return

        # Example table
        x = PrettyTable()
        x.field_names = ['Num 1', 'Num 2', 'Operation', 'Result']
        x.add_row((1, 1, '+', 2))
        x.add_row((1, 2, '*', 2))
        x.add_row((20, 5, '/', 4))

        await plugin.context.examplelib.example(event)  # Call function of our example library
        await event.respond(str(x))                     # Send example table

Plugin directory hierarchy must be view as:

examplerequirements/
|- config/
|  |- default.toml
|
|- lang/
|  |- en.toml
|
|- requirements.txt
|- main.py
|- plugin.toml

on_setup(func: Callable[[Self], None]) → Callable[[Self], None]: Decorator takes function that be called on plugin setup

Note

Called only once, when plugin is initializing

Warning

This event is not recommended to use as “on load” to initialize all variables. Use on_load() instead of.

on_load(func: Callable[[Self], None]) → Callable[[Self], None]

Decorator takes function that be called on plugin loads

Note

This event called when plugin is loading. It recommended to declare all working variables there. But, do not forget delete them in on_unload() event. Also, plugins must declare there all commands.

Example:

Plugin config “plugin.toml”:

name     = 'ExampleLib'   # name of the plugin
version  = '1.0.0'        # version of the plugin
author   = 'ftdot'        # paste here your name

description       = 'Provides example function'  # small description of the plugin

# full description of the plugin (you may describe plugin in details)
full_description  = 'This is example library plugin for EzBotF. This is provides an example function, that deletes message from event'

[executable]
main_file   = 'main.py'  # file with the main plugin class
main_class  = 'plugin'   # name of the plugin instance

[lang]
default  = 'en'      # default language of the plugin
langs    = [ 'en' ]  # supported languages

Plugin executable “main.py”:

import ezbotf

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

@plugin.on_load
def on_load():

    async def example(event):
        """Example library function, that deletes message from event,
        that given to it command. Must be awaited!

        :param event: Event from get message to delete
        """

        await event.message.delete()

    plugin.context.examplelib = Context()        # Create new context for our library
    plugin.context.examplelib.example = example  # Link my_lib.example to example function

@plugin.on_unload
def on_unload():
    # About on_unload event see bottom

    # Don't forget to delete our library context
    del plugin.context.examplelib

on_unload(func: Callable[[Self], None]) → Callable[[Self], None]

Decorator takes function that be called on plugin unloads

Note

This event is called when plugin is unloading. You must delete all plugin things, such as library contexts, working variables and etc. that defined in on_load() event.

Note

You isn’t required to delete all commands in this event. When plugin is unloaded, all commands automatically disables.

For examples you can view on_load().

on_start(func: Callable[[Self], None]) → Callable[[Self], None]: Decorator takes function that be called on plugin starts

Note

This event is called only once, when bot instance is start. You can use context.instance.client (TelegramClient, from Telethon, see https://docs.telethon.dev/ for more information about it). But note, that telethon is async library, and you must use :func:ezbotf.utils.run_coroutine_without_await() to run coroutines outside of event loop.

Registers a command. You may use command() decorator to more comfortable

Parameters:

function – Function to register
names – Names of the command
arguments – Arguments of the command
permissions – Permissions for the command

remove_command(command_names_or_function: str | list[str | Coroutine[EventBuilder, Context, None]] | Coroutine[EventBuilder, Context, None]) → bool

Removes a command

Parameters:: command_names_or_function – String name of the command or list with the strings or functions or a function
Returns:: True if command deleted successfully, otherwise False

Registers a command

Parameters:

names – Names of the command
arguments – Arguments of the command
permissions – Permissions for the command

Example:

import ezbotf

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

@plugin.on_load
def on_load():

    @plugin.command('sum',  # name of command
                    [argumentparser.Argument('num1', argumentparser.Cast.FloatCast),  # Arguments
                     argumentparser.Argument('num2', argumentparser.Cast.FloatCast)]
                    ['myplugin.test',    # Permissions
                     Permissions.User])
    async def test(event, args):
        await event.respond(event, str(args.num1 + args.num2))