PluginForge

Application-agnostic Python plugin framework built on pluggy.

PluginForge adds the layers that pluggy is missing: YAML configuration, plugin lifecycle management, enable/disable per config, dependency resolution, FastAPI integration, and i18n support.

Installation

pip install pluginforge

With optional FastAPI support:

pip install pluginforge[fastapi]

Quickstart

1. Create a plugin

from pluginforge import BasePlugin

class HelloPlugin(BasePlugin):
    name = "hello"
    version = "1.0.0"
    description = "A hello world plugin"

    def activate(self):
        print(f"Hello plugin activated with config: {self.config}")

    def get_routes(self):
        from fastapi import APIRouter
        router = APIRouter()

        @router.get("/hello")
        def hello():
            return {"message": self.config.get("greeting", "Hello!")}

        return [router]

2. Configure your app

# config/app.yaml
app:
  name: "MyApp"
  version: "1.0.0"
  default_language: "en"

plugins:
  entry_point_group: "myapp.plugins"
  enabled:
    - "hello"
  disabled: []

# config/plugins/hello.yaml
greeting: "Hello from PluginForge!"

3. Use PluginManager

from pluginforge import PluginManager

pm = PluginManager("config/app.yaml")

# Register plugins directly (or use entry points for auto-discovery)
pm.register_plugins([HelloPlugin])

# Access plugins
for plugin in pm.get_active_plugins():
    print(f"Active: {plugin.name} v{plugin.version}")

# Mount FastAPI routes
from fastapi import FastAPI
app = FastAPI()
pm.mount_routes(app)  # Routes under /api/ (configurable prefix)

Features

• YAML Configuration - App config, per-plugin config, and i18n strings
• Plugin Lifecycle - init, activate, deactivate with error handling
• Hot-Reload - Swap plugins at runtime without app restart
• Enable/Disable - Control plugins via config lists
• Dependency Resolution - Topological sorting with circular dependency detection
• Extension Points - Query plugins by interface with get_extensions(type)
• Config Schema Validation - Declare expected config types per plugin
• Health Checks - Monitor plugin status via health_check()
• Pre-Activate Hooks - Reject plugins before activation (license checks, etc.)
• FastAPI Integration - Mount plugin routes with configurable prefix
• Alembic Support - Collect migration directories from plugins
• i18n - Multi-language strings from YAML with fallback
• Security - Plugin name validation and path traversal prevention

For detailed documentation, see the Wiki.

Entry Point Discovery

Register plugins as entry points in your pyproject.toml:

[project.entry-points."myapp.plugins"]
hello = "myapp.plugins.hello:HelloPlugin"

Then use discover_plugins() instead of register_plugins():

pm = PluginManager("config/app.yaml")
pm.discover_plugins()  # Auto-discovers from entry points

i18n

# config/i18n/en.yaml
common:
  save: "Save"
  cancel: "Cancel"

pm.get_text("common.save", "en")  # "Save"
pm.get_text("common.save", "de")  # "Speichern"

Documentation

The full documentation is available in the Wiki:

• Getting Started
• BasePlugin
• PluginManager
• Configuration
• Discovery and Dependencies
• Lifecycle
• Hooks
• Extensions
• FastAPI Integration
• Alembic Integration
• i18n
• Security
• Examples
• Changelog
• Roadmap

Development

make install-dev   # Install with dev dependencies
make test          # Run tests
make lint          # Run ruff linter
make format        # Format code
make ci            # Full CI pipeline (lint + format-check + test)
make help          # Show all available targets

License

MIT