Skip to content

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 installation and management, Fast Pluggy provides the PluginService class:

class PluginService:
    @staticmethod
    def install_module_requirements(module_name: str, fast_pluggy):
        """
        Install requirements for a module.

        Args:
            module_name: Name of the module
            fast_pluggy: FastPluggy instance
        """
        pass

    @staticmethod
    def install_plugin(plugin_url: str, fast_pluggy):
        """
        Install a plugin from a URL.

        Args:
            plugin_url: URL of the plugin
            fast_pluggy: FastPluggy instance

        Returns:
            Dict: Result of the installation
        """
        pass

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
    plugin_list_url: Optional[str] = 'https://registry.fastpluggy.xyz/plugins.json'

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

    session_secret_key: str = "your-secret-key"

REST API Endpoints

Fast Pluggy provides several REST API endpoints for managing plugins:

Plugin Management

  • GET /admin/api/plugins - List all plugins
  • GET /admin/api/plugins/{plugin_name} - Get plugin details
  • POST /admin/api/plugins - Install a plugin
  • DELETE /admin/api/plugins/{plugin_name} - Uninstall a plugin
  • PUT /admin/api/plugins/{plugin_name}/enable - Enable a plugin
  • PUT /admin/api/plugins/{plugin_name}/disable - Disable a plugin
  • PUT /admin/api/plugins/{plugin_name}/update - Update a plugin

Plugin Configuration

  • GET /admin/api/plugins/{plugin_name}/config - Get plugin configuration
  • PUT /admin/api/plugins/{plugin_name}/config - Update plugin configuration

Events

Fast Pluggy provides several events that plugins can hook into:

  • plugin_pre_install - Before a plugin is installed
  • plugin_post_install - After a plugin is installed
  • plugin_pre_uninstall - Before a plugin is uninstalled
  • plugin_post_uninstall - After a plugin is uninstalled
  • plugin_pre_enable - Before a plugin is enabled
  • plugin_post_enable - After a plugin is enabled
  • plugin_pre_disable - Before a plugin is disabled
  • plugin_post_disable - After a plugin is disabled
  • application_startup - When the application starts
  • application_shutdown - When the application shuts down

Example Usage

from fastapi import FastAPI
from fastpluggy import FastPluggy
from fastpluggy.core.plugin.installer import PluginInstaller

# 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}")

# Install a plugin
plugin_installer = PluginInstaller(plugin_manager=pluggy.get_manager())
result = plugin_installer.install_plugin("https://github.com/example/fastpluggy-auth.git")
print(f"Installation result: {result}")

# 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}")