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
instancedir – 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.
- register_command(function: Coroutine[EventBuilder, Context, None], names: list[str] | str | None = None, arguments: list[ezbotf.argumentparser.parser.Argument] | ArgumentParser | None = None, permissions: list[str | ezbotf.permissions.Permissions] | None = None) Coroutine[EventBuilder, Context, None] ¶
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[Union[str, Coroutine[telethon.events.common.EventBuilder, ezbotf.context.Context, NoneType]]] | 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
- command(names: list[str] | str | None = None, arguments: list[ezbotf.argumentparser.parser.Argument] | ArgumentParser | None = None, permissions: list[str | ezbotf.permissions.Permissions] | None = None)¶
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))