API Reference

This page provides detailed information about the Fast Pluggy API.

FastPluggy Class

The main class for integrating Fast Pluggy with your FastAPI application.

class FastPluggy(GlobalRegistry):
    def __init__(
        self, 
        app: FastAPI, 
        app_root_dir=None, 
        path_plugins=None, 
        path_modules=None, 
        auth_manager=None
    ):
        """
        Initialize Fast Pluggy.

        Args:
            app: The FastAPI application instance
            app_root_dir: Root directory of the application (defaults to current directory)
            path_plugins: Directory where plugins are stored (defaults to {app_root_dir}/plugins)
            path_modules: Directory where domain modules are stored (defaults to {app_root_dir}/domains)
            auth_manager: Authentication manager instance (optional)
        """
        pass

The initialization process happens automatically in the constructor. There's no need to call an additional init() method.

Module Manager

Fast Pluggy uses a module manager to handle plugin discovery, initialization, and management.

class BaseModuleManager:
    def __init__(self, app: FastAPI, fast_pluggy):
        """
        Initialize the module manager.

        Args:
            app: The FastAPI application instance
            fast_pluggy: The FastPluggy instance
        """
        pass

    def discover_plugins(self, folder: str, module_type: str):
        """
        Discover plugins in the specified folder.

        Args:
            folder: Path to the folder containing plugins
            module_type: Type of modules to discover ('plugin' or 'domain')
        """
        pass

    def initialize_plugins_in_order(self):
        """
        Initialize plugins in dependency order.

        Returns:
            Dict: Result of the initialization process
        """
        pass

    def is_module_loaded(self, module_or_name) -> bool:
        """
        Check if a module is loaded.

        Args:
            module_or_name: Module name or PluginState instance

        Returns:
            bool: True if the module is enabled and loaded
        """
        pass

    def register_all_routes(self):
        """
        Register routes for all loaded modules.
        """
        pass

    def get_template_loaders(self) -> Dict:
        """
        Get template loaders for all loaded modules.

        Returns:
            Dict: Dictionary of template loaders
        """
        pass

    def execute_all_module_hook(self, hook_name: str, require_loaded: bool = True):
        """
        Execute a hook for all modules.

        Args:
            hook_name: Name of the hook to execute
            require_loaded: Whether to require modules to be loaded
        """
        pass

For plugin enable/disable/removal, Fast Pluggy provides the PluginService class:

class PluginService:
    @staticmethod
    def enable_plugin(plugin_name: str, fast_pluggy): ...

    @staticmethod
    def disable_plugin(plugin_name: str, fast_pluggy): ...

    @staticmethod
    def install_module_requirements(module_name: str, fast_pluggy): ...

    @staticmethod
    def remove_plugin(plugin_name: str, fast_pluggy): ...

Each method returns a FlashMessage (or, for remove_plugin, a list mixing FlashMessage and a RedirectResponse) — see Flash Messages.

Plugin Base Class

Plugins in Fast Pluggy are created by inheriting from the FastPluggyBaseModule class.

class FastPluggyBaseModule(BaseModel):
    """
    Base class for FastPluggy plugins.

    Plugins must inherit from this class and implement at least the `on_load()` method.
    They can optionally define metadata fields and attributes for integration (e.g., router, settings).
    """

    # --- Identity / version ---
    module_name: Optional[str] = ""
    module_version: Optional[str] = "0.0.0"
    module_settings: Optional[Any] = None
    depends_on: Optional[Dict[str, str]] = Field(default_factory=dict)

    # --- Menu Metadata ---
    module_menu_name: str = ""
    module_menu_icon: str = "fas fa-cube"
    module_menu_type: Optional[str] = "main"

    # --- JS & CSS ---
    extra_js_files: List[str] = Field(default_factory=list)
    extra_css_files: List[str] = Field(default_factory=list)

    # --- Optional Router ---
    module_router: ModuleRouterType = None
    module_mount_url: Optional[str] = None

    # --- Path ---
    module_path: Optional[Path] = None

    # --- Lifecycle Hooks ---
    def on_load_complete(self, fast_pluggy: "FastPluggy") -> None:
        """
        This method will be called when all plugins are loaded.
        """
        pass

    def after_setup_templates(self, fast_pluggy: "FastPluggy") -> None:
        """
        This method will be called when the jinja env is set up.
        """
        pass

Configuration

Fast Pluggy uses a configuration class to manage settings.

class FastPluggyConfig(BaseDatabaseSettings):
    app_name: Optional[str] = 'FastPluggy'

    # admin config
    admin_enabled: Optional[bool] = True
    fp_admin_base_url: Optional[str] = '/admin'
    include_in_schema_fp:Optional[bool] = True

    show_empty_menu_entries: Optional[bool] = True
    install_module_requirement_at_start: Optional[bool] = True

    session_secret_key: str = "your-secret-key"

Plugin Management Routes

Plugin management is an HTML admin UI, not a JSON REST API — there is no /admin/api/* surface. The real routes (all gated by the fp_admin role):

• GET /admin/plugins (list_plugins) - the plugin list + admin action buttons
• GET /admin/base_module/{plugin_name}/overview (get_overview_module) - per-plugin detail page
• GET /admin/base_module/{plugin_name}/settings (get_plugin_settings) - per-plugin settings form
• POST /admin/plugins/{plugin_name}/toggle (toggle_plugin_status) - enable/disable
• POST /admin/base_module/{plugin_name}/install-requirements (install_module_requirements_route)
• POST /admin/base_module/{plugin_name}/remove (remove_plugin_route) - disable + delete
• POST /admin/reload (reload_fast_pluggy_route), POST /admin/restart[/force]

(Paths assume the default fp_admin_base_url = "/admin" — see Configuration.)

See Plugin Module for the plugin-authoring side of this.

Events

Fast Pluggy's event bus uses the fp.* namespace for its own lifecycle events, plus menu.overrides_changed from the menu manager — see Built-in lifecycle events for the full, accurate list and how to subscribe.

Example Usage

from fastapi import FastAPI
from fastpluggy import FastPluggy

# Create the FastAPI application
app = FastAPI()

# Initialize Fast Pluggy with custom plugin and module paths
pluggy = FastPluggy(
    app,
    app_root_dir=".",
    path_plugins="./plugins",
    path_modules="./domains"
)

# Access the module manager
module_manager = pluggy.module_manager

# Check if a module is loaded
is_loaded = module_manager.is_module_loaded("my-plugin")
print(f"Plugin loaded: {is_loaded}")

# Execute a hook for all modules
module_manager.execute_all_module_hook(hook_name="on_load_complete")

# Access configuration
config = pluggy.settings
print(f"Admin URL: {config.fp_admin_base_url}")