Plugin Management

zwylib.PluginUtils groups together helpers for looking up, installing, reloading, and inspecting plugins through exteraGram’s PluginsController.

zwylib.PluginUtils

class PluginUtils

Methods

get_plugin

PluginUtils.get_plugin(plugin_id: str) -> Optional[Plugin]

Retrieves a plugin’s (Java) Plugin model from PluginsController by its identifier — this describes the plugin’s metadata and enabled state, not its running Python instance.

Parameters

• plugin_id (str): Identifier of the plugin to retrieve.

Example

plugin = zwylib.PluginUtils.get_plugin("example_plugin")
if plugin:
    print(f"Found plugin: {plugin}")

get_plugin_instance

PluginUtils.get_plugin_instance(plugin_id: str) -> Optional[BasePlugin]

Retrieves the running Python BasePlugin instance for a loaded plugin.

Parameters

• plugin_id (str): Identifier of the plugin to retrieve.

Example

instance = zwylib.PluginUtils.get_plugin_instance("example_plugin")

get_plugins

PluginUtils.get_plugins() -> Optional[Dict[str, Plugin]]

Returns a dict of all known plugins, keyed by plugin ID, mapped to their (Java) Plugin model.

Example

for plugin_id, plugin in zwylib.PluginUtils.get_plugins().items():
    print(plugin_id, plugin.isEnabled())

get_plugin_path

PluginUtils.get_plugin_path(plugin_id: str) -> str

Builds the on-disk path to a plugin’s .py source file, without checking whether it actually exists.

Parameters

• plugin_id (str): Identifier of the plugin.

Example

path = zwylib.PluginUtils.get_plugin_path("example_plugin")

is_plugin_loaded_or_loading

PluginUtils.is_plugin_loaded_or_loading(plugin_id: str) -> bool

Checks whether a plugin is currently enabled, or in the process of loading.

Parameters

• plugin_id (str): Identifier of the plugin.

Example

if zwylib.PluginUtils.is_plugin_loaded_or_loading("example_plugin"):
    ...

reload_plugin

PluginUtils.reload_plugin(plugin_id: str) -> None

Requests that the Python plugins engine reload a plugin from disk.

Parameters

• plugin_id (str): Identifier of the plugin to reload.

Example

zwylib.PluginUtils.reload_plugin("example_plugin")

install_plugin

PluginUtils.install_plugin(file_path: str) -> bool

Coroutine — installs a plugin from a local .plugin/.py file path, returning whether installation succeeded.

Parameters

• file_path (str): Path to the plugin file on disk.

Example

async def install():
    success = await zwylib.PluginUtils.install_plugin("/sdcard/Download/example_plugin.plugin")

async_download_and_install_plugin

PluginUtils.async_download_and_install_plugin(
    msg_obj: MessageObject,
    plugin_id: str,
    skip_media_download=False,
    max_tries=3
) -> None

Coroutine — downloads a plugin file attached to a message (if not already downloaded) and installs it. Retries the download up to max_tries times, waiting for it to complete via ensure_media_downloaded before giving up.

Parameters

• msg_obj (MessageObject): Message whose attached document is the plugin file.
• plugin_id (str): Identifier of the plugin being installed, used for logging.
• skip_media_download (bool, default False): If True, assumes the file is already downloaded and skips straight to installation.
• max_tries (int, default 3): Maximum number of download attempts.

Example

async def install_from_message(msg_obj):
    await zwylib.PluginUtils.async_download_and_install_plugin(msg_obj, "example_plugin")

zwylib.ensure_media_downloaded

zwylib.ensure_media_downloaded(msg_obj: MessageObject) -> bool

Coroutine — makes sure a message’s attached media (photo or document) is fully downloaded to disk, downloading it first if necessary, and returns whether it’s now available. Used internally by the auto-updater and async_download_and_install_plugin, but generally useful whenever a plugin needs guaranteed local access to a message’s attachment.

Parameters

• msg_obj (MessageObject): The message whose media should be ensured downloaded.

Example

async def read_attached_file(msg_obj):
    if not await zwylib.ensure_media_downloaded(msg_obj):
        return
    # the file is now safely on disk