Getting Started

Getting Started

Installation

pip install pluginforge

For the optional integrations, install the relevant packages separately:

pip install pluginforge fastapi              # FastAPI route mounting
pip install pluginforge alembic sqlalchemy   # Alembic migration support

Note: the pluginforge[fastapi] and pluginforge[alembic] extras existed pre-v0.6.0 but were non-functional (they referenced dependencies that were never declared as optional). They were removed in v0.6.0.

Your First Plugin

1. Create a config file

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

plugins:
  entry_point_group: "myapp.plugins"
  enabled:
    - "hello"

2. Define a plugin

# plugins/hello_plugin.py
from pluginforge import BasePlugin

class HelloPlugin(BasePlugin):
    name = "hello"
    target_application = "quickstart-app"   # v0.7.0: which host this plugin targets
    version = "0.1.0"
    description = "A simple greeting plugin"
    author = "Your Name"

    def activate(self) -> None:
        greeting = self.config.get("greeting", "Hello")
        print(f"{greeting} from {self.name}!")

    def deactivate(self) -> None:
        print(f"Goodbye from {self.name}!")

target_application declares the host application this plugin is built for. v0.7.0 hosts that have adopted app_id validate it; mismatched plugins refuse to activate. See BasePlugin#application-identity-v070 for the full behavior matrix.

3. Optional plugin config

# config/plugins/hello.yaml
greeting: "Hallo"
max_greetings: 5

4. Use the PluginManager

from pluginforge import PluginManager

pm = PluginManager(
    "config/app.yaml",
    app_id="quickstart-app",   # v0.7.0: host identity; matches HelloPlugin.target_application
)

# Option A: Discover plugins via entry points
result = pm.discover_plugins()   # since v0.6.0, returns DiscoveryResult
print(f"Activated: {result.activated}")

# Option B: Register plugin classes directly
from plugins.hello_plugin import HelloPlugin
pm.register_plugins([HelloPlugin])   # also returns DiscoveryResult

# Use plugins
active = pm.get_active_plugins()
print(f"Active plugins: {[p.name for p in active]}")

# Shutdown
pm.deactivate_all()

app_id is the host application's identifier. When set, plugins declaring target_application are validated against it; mismatches refuse to activate. When None (the default), identity is not validated and behavior is identical to v0.6.x.

Note: app_id is passed explicitly by the host application at PluginManager construction time, not auto-read from the YAML config. This mirrors how app_version works in v0.6.0 - both are runtime parameters owned by the host, separate from the declarative app.* fields in the YAML. See Configuration for details on the YAML / constructor split.

Project Structure

A typical project using PluginForge:

myapp/
├── config/
│   ├── app.yaml                # Main app config
│   ├── plugins/
│   │   ├── hello.yaml          # Per-plugin config
│   │   └── export.yaml
│   └── i18n/
│       ├── en.yaml             # English strings
│       └── de.yaml             # German strings
├── plugins/
│   ├── hello_plugin.py
│   └── export_plugin.py
└── app.py                      # Application entry point

Next Steps

• BasePlugin - All plugin attributes and lifecycle methods
• BasePlugin#application-identity-v070 - Identity declaration and the identity contract
• PluginManager#related-types - Structured types (DiscoveryResult, PluginError, FilterReason, etc.) returned by discovery
• Lifecycle - Full activation pipeline (identity, version, dependency, init, activate)
• Configuration - Deep dive into the YAML config system
• Hooks - How to define and implement pluggy hooks