Home

PluginForge Wiki

Application-agnostic plugin framework built on pluggy.

PluginForge wraps pluggy and adds the layers that pluggy does not provide: YAML configuration, plugin lifecycle, enable/disable, dependency resolution, FastAPI integration, Alembic migration support, and i18n.

Quick Links

• Getting Started - Installation and first plugin
• BasePlugin - Plugin base class and lifecycle methods
• PluginManager - Central orchestration class
• Configuration - YAML config system (app, plugin, i18n)
• Discovery and Dependencies - Entry points and dependency resolution
• Lifecycle - Init, activate, deactivate state machine
• Hooks - pluggy hook integration
• Extensions - Extension point pattern
• Cross-Plugin Communication - Patterns for plugins to interact
• FastAPI Integration - Mounting plugin routes
• Alembic Integration - Plugin database migrations
• i18n - Internationalization
• Security - Path traversal prevention and plugin name validation
• Examples - Complete example application
• Changelog - Version history
• Roadmap - Planned features and ideas

Architecture Overview

PluginManager
├── Config (YAML)             - app.yaml, plugins/*.yaml, i18n/*.yaml
├── Discovery                 - Entry points + dependency resolution
├── Diagnostics (v0.6.0)      - DiscoveryResult / PluginState / PluginError
├── Lifecycle                 - init -> activate -> deactivate (+ hot-reload)
├── Live Config Refresh (v0.6.0) - refresh_config() + on_config_changed hook
├── Config Overlay (v0.10.0)    - merge_app_config(overlay) recursive-merge entry point
├── Entry Point Rediscovery (v0.6.0) - rediscover() picks up newly-installed plugins
├── Version Gating (v0.6.0)   - api_version / min_app_version with configurable severity
├── Application Identity (v0.7.0/v0.9.0) - target_application / app_id; mismatch and missing-target both hard-filter
├── Lifecycle Visibility (v0.9.0) - PluginState timestamps + source, inspect_plugin aggregator, event hooks
├── Hooks (pluggy)            - @hookspec / @hookimpl
├── Extensions                - get_extensions(type) for interface-based queries
├── Health Checks             - Plugin health monitoring
├── Security                  - Plugin name validation, path traversal prevention
├── FastAPI (optional)        - Route mounting with configurable prefix (idempotent since v0.8.0)
├── Test Helpers (v0.8.0)     - pluginforge.testing.IsolatedPluginManager + MockPlugin
├── Alembic (optional)        - Migration directory collection
└── i18n (optional)           - Multilingual strings from YAML

Requirements

• Python 3.11+
• pluggy >= 1.5.0
• PyYAML >= 6.0
• packaging >= 21.0 (added as a direct dependency in v0.6.0 for Version comparison)