Getting Started

Getting Started

Installation

pip install pluginforge

With optional dependencies:

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

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

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

# Option A: Discover plugins via entry points
pm.discover_plugins()

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

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

# Shutdown
pm.deactivate_all()

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
• Configuration - Deep dive into the YAML config system
• Hooks - How to define and implement pluggy hooks