utils module

Note

This module is imports as from .. import utils. This means that you must use ezbotf.utils.check_config as example.

Some utilities (in most for plugins) of framework

System functions

These utility functions is created for framework base.

ezbotf.utils.check_config(config: dict[str, Any], requires: list[str]) → bool

Checks if given config is valid by requires list

Parameters:

  • config – Config dictionary to check

  • requires – List with the required fields

Returns:

True if config is valid by all required fields, otherwise False

ezbotf.utils.check_config_by_path(config: dict[str, Any], requires: dict[str, Any]) → bool

Advanced check for the config is valid. Uses requires as dictionary. Uses check_config().

Parameters:

  • config – Config dictionary to check

  • requires – Dictionary with required fields

Returns:

True if config is valid by all required fields, otherwise False

ezbotf.utils.get_translator_for_plugin(plugin: Plugin, desired_lang: str) → Translator

Loads a translator from the Plugin with desired language

Parameters:

  • plugin – Plugin from get all required configurations to load translator

  • desired_lang – Desired language to use in translations

Returns:

Initialized Translator object

ezbotf.utils.load_runtime_config(plugin: Plugin) → dict[str, Any]

Loads runtime configuration from the Plugin

Parameters:

plugin – Plugin from get all required configurations to get runtime configuration

Returns:

TOML dictionary with the runtime configuration

Requirement management functions

This usable for the plugins on_install event. These functions that implements functional of of installing requirements and checking required plugins.

See also

ezbotf.Plugin.on_install() - Example with utilities usage

ezbotf.utils.install_requirements_by_path(requirements_path: Path, pip_logs_dir: Path) → bool | Exception

Tries to install a requirements file by path. With output log of pip

Parameters:

  • requirements_path – Path to the requirements file

  • pip_logs_dir – Path to the directory with the pip logs store

Returns:

True if pip successfully installed, otherwise returns an Exception

ezbotf.utils.install_requirements(plugin: Plugin) → bool

Installs requirements for the Plugin

Parameters:

plugin – Plugin from get required configuration to install requirements

Returns:

True if install is successful, otherwise False

ezbotf.utils.check_required_plugins_by_list(plugin: Plugin, plugins: list[Plugin], required_plugins: list[list[str, list[str, str]] | list[str, list[str, str], list[str, str]]]) → bool

Check if the required plugins with the required versions are alive. Required plugins gets from plugin config file by path requirements.plugins

Parameters:

  • plugin – Plugin that uses this function

  • plugins – Current plugins list

  • required_plugins – Required plugins list

Returns:

True if all checks are passed, otherwise False

ezbotf.utils.check_required_plugins(plugin: Plugin) → bool

Checks all required plugins for a Plugin. Shorthand for the check_required_plugins_by_list()

Parameters:

plugin – Plugin from get all required configurations to check all required plugins

Returns:

True if all checks are passed, otherwise False

Permission management functions

There is functions to loadsave permissions and check permissions for some user.

ezbotf.utils.load_permissions(permissions_dir: Path, name: str) → dict[str, Any]

Loads the permissions from the permissions directory by the instance name

Parameters:

  • permissions_dir – Path to the directory with the permissions

  • name – Name of the instance

Returns:

TOML dictionary with the permissions

ezbotf.utils.save_permissions(permissions_dir: Path, name: str, permissions: dict[int, list[str | Permissions]])

Saves the permissions to the permissions directory by the instance name

Parameters:

  • permissions_dir – Path to the directory with the permissions

  • name – Name of the instance

  • permissions – Permissions dictionary to save

ezbotf.utils.have_permissions(user_id: int, permissions: dict[int, list[str | Permissions]], required_permissions: list[str | Permissions]) → bool

Checks if the user (by id) have some permissions

Parameters:

  • user_id – ID of the user

  • permissions – Dictionary with the all permissions defined

  • required_permissions – Required permissions

Returns:

True if the user have required permissions (or above), otherwise False

Other

ezbotf.utils.run_coroutine_without_await(coroutine: Coroutine) → Any

Runs a coroutine without “await” construction (outside of event loop)

Parameters:

coroutine – Coroutine to run

Returns:

Result of the coroutine

ezbotf.utils.compare_versions(operation: list[str, str, str], logger: Logger) → bool

Compares versions

Parameters:

  • operation – An operation (versions specific) to compare

  • logger – Logger to use

Returns:

True if comparing is passed, otherwise False

ezbotf.utils.mask_phone_number(number: str) → str

Mask phone number with *, but show last four numbers. Also, adds a “+” at the start of number string

Parameters:

number – Strings number to mask

Returns:

Masked number string

ezbotf.utils.sort_by_priority(plugins: list[Plugin]) → list[Plugin]

Sorts given plugin list by priority

Parameters:

plugins – Plugin list to sort

Returns:

List with the sorted plugins