▶️ Loader & Manager Usage

To interact with the module loading system or perform module management tasks (install, update, uninstall), your module needs to request the use_loader permission.

WARNING

Requesting use_loader grants significant control over the bot's modules. Only enable this for modules you trust completely.

Requesting Permission

Add use_loader to the permissions list in your module's config.yaml:

# config.yaml
info:
  name: ModuleManagerUI
  # ... other info ...
permissions:
  - use_loader # Request access to the loader/manager API
# ... config ...

Accessing the Loader

If permission is granted, the ModuleLoader instance (base.loader.ModuleLoader) will be available in your module instance as self.loader.

Accessing the Module Manager

The ModuleLoader itself holds an instance of the ModuleManager (base.mod_manager.ModuleManager) in its mod_manager attribute. So, you access manager functions via self.loader.mod_manager.

# Inside your BaseModule class method
if self.loader: # Check if loader access was granted
    manager = self.loader.mod_manager
    # Now you can call manager methods
    # e.g., await manager.install_from_git(...)
else:
    await message.reply("Error: Loader access not granted to this module.")
    return

Available Functions

Here's a summary of key functions available through self.loader and self.loader.mod_manager. For exact parameters, return types, and behavior, always refer to the source code documentation (docstrings) in base/loader.py and base/mod_manager.py.

Via self.loader (ModuleLoader):

• load_module(name: str, skip_deps: bool = False) -> Optional[str]: Loads a module by its directory name. Returns user-friendly name on success, None on failure.
• unload_module(name: str): Unloads a module by its directory name.
• get_module(name: str) -> Optional[BaseModule]: Gets the instance of a loaded module.
• get_modules_info() -> dict[str, ModuleInfo]: Gets info for all currently loaded modules.
• get_all_modules_info() -> dict[str, ModuleInfo]: Gets info for all modules (loaded or not) found in the modules directory.
• get_module_info(name: str) -> Optional[ModuleInfo]: Gets info for a specific module, regardless of load status.
• get_module_help(name: str) -> Optional[Union[HelpPage, str]]: Gets the help page for a loaded module.
• get_module_perms(name: str) -> list[Permissions]: Gets the permissions declared by a loaded module.
• get_modules_deps() -> dict[str, list[str]]: Gets the dependency list for loaded modules that have requirements.txt.
• get_int_name(name: str) -> Optional[str]: Gets the internal directory name from a user-friendly module name.
• prepare_for_module_update(name: str) -> Optional[BaseModule]: Unloads a module to prepare for an update, returning the instance if it was loaded.

Via self.loader.mod_manager (ModuleManager):

• install_from_git(url: str) -> Tuple[int, str]: Clones a module from a Git URL into the modules/ directory. Returns Git exit code and output.
• check_for_updates(name: str, directory: str) -> Optional[bool]: Checks if a Git-based module/extension has remote updates. Returns True (updates available), False (up-to-date), or None (error). directory is typically "modules" or "extensions".
• update_from_git(name: str, directory: str, module: Optional[BaseModule] = None) -> Tuple[int, str, Optional[str]]: Updates a module/extension from Git. Creates a backup, pulls changes, handles potential DB migrations (if module instance provided). Returns Git exit code, output, and backup path.
• revert_update(name: str, directory: str) -> bool: Reverts the last Git update for a module/extension using the stored pre-update commit hash.
• restore_from_backup(name: str, directory: str, backup_path: Optional[str] = None) -> bool: Restores a module/extension from a specified backup zip file (or the latest if backup_path is None). Handles Git repo restoration correctly if metadata exists in the backup.
• list_backups(name: Optional[str] = None) -> list[str]: Lists paths to available backup files, optionally filtered by module/extension name.
• install_deps(name: str, directory: str) -> Tuple[int, Union[str, list[str]]]: Installs/updates dependencies from requirements.txt. Returns pip exit code and output/requirements list.
• uninstall_mod_deps(name: str, modules_deps: dict[str, list[str]]): Uninstalls dependencies specific to a module, avoiding removal if shared by others. (Requires the current dependency map).
• uninstall_packages(pkgs: list[str], modules_deps: dict[str, list[str]]): Uninstalls specified packages if not required by any loaded module.
• uninstall_module(name: str, modules_deps: dict[str, list[str]]) -> bool: Removes a module's directory and its unique dependencies. Returns success status.
• set_module_auto_load(name: str, auto_load: bool) -> bool: Sets the auto_load flag in the module's config.yaml. Returns success status.
• cleanup_old_backups(name: str, keep_count: int = 5) -> int: Removes older backups for a module/extension, keeping the specified number. Returns the count of deleted backups.

INFO

Remember to handle potential errors and check return values when using these functions.