Quickstart

Prerequisites

1. Python 3.11+

2. Python package manager

   1. We recommend UV

Getting Started

1

Installation

uv add gl-plugin

2

A working example

A fully working example you can just immediately execute is as follows:

main.py

from gl_plugin.plugin.plugin import Plugin
from gl_plugin.plugin.handler import PluginHandler
from gl_plugin.plugin.manager import PluginManager
from typing import Any, Dict

# The handler
class HelloPluginHandler(PluginHandler):
    def __init__(self) -> None:
        super().__init__()

    @classmethod
    def create_injections(cls, instance: Any) -> Dict[str, Any]:
        return dict()

    @classmethod
    def initialize_plugin(cls, instance: Any, plugin: Any) -> None:
        pass

# The plugin
@Plugin.for_handler(HelloPluginHandler)
class HelloPlugin(Plugin):
    name = "HelloPlugin"
    version = "0.1.0"
    description = "A simple greeting plugin"

    def greet(self, name: str) -> str:
        return f"Hello, {name}!"

# Execution
handler = HelloPluginHandler()
manager = PluginManager(handlers=[handler])
manager.register_plugin(HelloPlugin)

hello_plugin = manager.get_plugin("HelloPlugin")

print(hello_plugin.greet("samuel"))

3

Executing the Code

You can execute the code by simply running:

uv run main.py

You should get the following as the output:

$ uv run main.py
Hello, samuel!

4

Explaining the Components

Plugin Handler

plugin_handler.py

from gl_plugin.plugin.handler import PluginHandler
from typing import Any, Dict

class HelloPluginHandler(PluginHandler):
    def __init__(self) -> None:
        super().__init__()

    @classmethod
    def create_injections(cls, instance: Any) -> Dict[str, Any]:
        return dict()  # No injections for this example

    @classmethod
    def initialize_plugin(cls, instance: Any, plugin: Any) -> None:
        pass  # No custom initialization needed

Every handler requires two class methods:

• create_injections() — Returns services to inject into plugins (empty dict if none)

• initialize_plugin() — Runs when a plugin is registered (leave empty if no setup needed)

We will go in-depth of what kind of injections are possible, and how to instantiate them in your plugin once you create it!

Creating the Plugin

plugin.py

from gl_plugin.plugin.plugin import Plugin

@Plugin.for_handler(HelloPluginHandler)
class HelloPlugin(Plugin):
    name = "HelloPlugin"
    version = "0.1.0"
    description = "A simple greeting plugin"

    def greet(self, name: str) -> str:
        return f"Hello, {name}!"

Use the @Plugin.for_handler() decorator to bind your plugin to its handler. Define the required metadata (name, version, description), then add your own methods.

Wiring up into the Manager

from gl_plugin.plugin.manager import PluginManager

manager = PluginManager(handlers=[HelloPluginHandler()])
manager.register_plugin(HelloPlugin)

hello_plugin = manager.get_plugin("HelloPlugin")
print(hello_plugin.greet("samuel"))  # Output: Hello, samuel!

Create your handler instance, pass it to the manager, register your plugin, and retrieve it by name.

Congratulations! You've just built your first plugin-based service. To dive deeper into the concepts behind GL Plugin and learn best practices, explore the sections below.

• Understanding Plugin Handlers

• Understanding how Service Injection works in GL Plugin