pkl

Attribute resources to plugins, and release them whenever you decide a lifetime ends.

📚 Documentation · The idea · Quick start · Extensions · Examples

The idea

A plugin system has to answer two questions:

1. Who is running right now? So that whatever gets created can be attributed to someone.
2. Who owns what? So that it can all be cleaned up when the plugin goes away.

That is the whole core of pkl, in four small concepts:

pkl never decides what "enable", "disable" or "uninstall" mean. A registry is a lifetime: you create as many as you like and call release(plugin) whenever you want. Call it on disable and it is a disable lifetime; call it on uninstall and it is an uninstall lifetime. There is no global state: a process can have any number of trackers and registries.

Everything else is an extension: it depends on the core, and the core never imports it.

Installation

Python 3.11+, no dependencies.

uv add plugins-kernel      # or: pip install plugins-kernel

Quick start

from dataclasses import dataclass
from pkl import Plugin, PluginTracker, ResourceRegistry


@dataclass(eq=False)                 # eq=False keeps "same iff `is`"
class AppPlugin(Plugin):             # pkl only sees the identity; the rest is yours
    name: str


plugins = PluginTracker[AppPlugin]()
disable = ResourceRegistry[AppPlugin]()   # a lifetime


class Connection:                    # any object with release() is a resource
    def release(self) -> None:
        print("closed")


alpha = AppPlugin("alpha")
with plugins.executing(alpha):       # alpha is running...
    owner = plugins.require_current()
    disable.register(owner, Connection())

disable.release(alpha)               # ...and now its lifetime ends: prints "closed"

Registering by hand gets tedious, which is what pkl.tracking is for.

Extensions

Extensions are plain modules in the package. They depend on the core (and on tracking), never on each other.

Bring your own: subclass Tracked, implement on_release, and your resource gets the same automatic tracking.

Automatic tracking

Bind a base class to a lifetime once; every subclass is then recorded under the plugin that creates it:

from pkl.tracking import ResourceTracker, Tracked
from pkl.timing import Timer

runtime = ResourceRegistry[AppPlugin]()


class RuntimeResource(Tracked[AppPlugin], tracker=ResourceTracker(plugins, runtime)): ...


class AppTimer(Timer, RuntimeResource): ...


with plugins.executing(alpha):
    AppTimer.interval(lambda: print("tick"), 1.0)   # attributed to alpha, recorded in `runtime`

runtime.release(alpha)                               # the timer is cancelled

Creating a tracked resource while no plugin is executing raises NoCurrentPluginError, because it could never be released. Pass ResourceTracker(..., allow_orphans=True) for resources that legitimately belong to the host.

One class can also serve several trackers (e.g. one per game zone) without subclassing: Timer.with_tracker(zone.tracker).interval(...). An SDK that must stay single-host forbids that with allow_tracker_override=False.

An SDK for your plugins

If plugin authors only ever import your SDK, tracking is 100% automatic and they never see pkl. See examples/sdk.py: it defines a derived AppPlugin (id, name, metadata), a runtime and a persistent lifetime, the resource classes plugins use, and disable() / uninstall().

Async and threads

The current plugin lives in a ContextVar, so concurrent asyncio tasks that run as different plugins never see each other's plugin, and tasks inherit the plugin they were created under. New threads start with an empty context: bind their entry point with plugins.bind(fn) (it captures the plugin executing now), or self.bind(fn) inside a resource. Timer does this for you.

Examples

python examples/main.py    # two plugins, one host, disable vs uninstall lifetimes
python examples/zones.py   # several independent hosts in one process
python examples/dependencies.py   # releasing a plugin releases its dependants
python examples/nested.py  # a plugin that owns a plugin host

Development

uv sync
uv run pytest
uv run mypy --strict pkl tests

License

MIT