msw-plugin-api

Minimal structural interfaces for MurineShiftWork plugin packages.

Zero dependencies (stdlib typing and dataclasses only). Provides:

• HostSessionInfo — concrete dataclass plugins return after attaching
• HostSessionInfoProtocol — runtime_checkable Protocol for structural typing
• HostSessionProtocol — runtime_checkable Protocol for host session plugins

Usage

from msw_plugin_api import HostSessionInfo, HostSessionProtocol

class MyHostSession:
    def attach(self, **kwargs) -> HostSessionInfo:
        return HostSessionInfo(
            backend="myplugin",
            acquisition_name="subject__20260609_143022__ext",
            subject="subject",
            parent_directory="/data/recordings",
        )

    def start(self) -> None: ...
    def stop(self) -> None: ...

Declare the plugin entry point in pyproject.toml:

[project.entry-points."msw.host"]
myplugin = "my_package.session:MyHostSession"

Plugin contract

MSW core checks isinstance(session, HostSessionProtocol) at dispatch time. Plugins may implement the interface structurally (without importing this package) or depend on msw-plugin-api explicitly for IDE support and test conformance checks.