msw-plugin-api 0.2.1__py3-none-any.whl

msw_plugin_api/__init__.py

@@ -0,0 +1,61 @@
+"""Minimal structural interfaces for MSW plugin packages.
+
+Defines runtime-checkable Protocols and a concrete HostSessionInfo dataclass
+so plugins can implement the MSW host-session contract without depending on
+the full murineshiftwork package.
+
+Usage in a plugin::
+
+    from msw_plugin_api import HostSessionInfo, HostSessionProtocol
+
+    class MyHostSession:
+        def attach(self, **kwargs) -> HostSessionInfo: ...
+        def start(self) -> None: ...
+        def stop(self) -> None: ...
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class HostSessionInfo:
+    """Data returned by a host session plugin after attaching.
+
+    Plugins may return this class directly or return any object whose
+    attributes satisfy HostSessionInfoProtocol.
+    """
+
+    backend: str
+    acquisition_name: str
+    subject: str
+    parent_directory: str
+    extra: dict[str, object] = field(default_factory=dict)
+
+
+@runtime_checkable
+class HostSessionInfoProtocol(Protocol):
+    """Structural protocol for host session info objects."""
+
+    backend: str
+    acquisition_name: str
+    subject: str
+    parent_directory: str
+    extra: dict[str, object]
+
+
+@runtime_checkable
+class HostSessionProtocol(Protocol):
+    """Structural protocol for MSW host session plugins.
+
+    Implement this interface (structurally — no import required) and declare::
+
+        [project.entry-points."msw.host"]
+        myplugin = "my_package.session:MyHostSession"
+    """
+
+    def attach(self, **kwargs: object) -> HostSessionInfoProtocol | None: ...
+    def start(self) -> None: ...
+    def stop(self) -> None: ...

msw_plugin_api/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)
+
+__commit_id__ = commit_id = None

msw_plugin_api-0.2.1.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: msw-plugin-api
+Version: 0.2.1
+Summary: Minimal structural interfaces for MSW plugin packages
+Project-URL: Homepage, https://github.com/MurineShiftWork/msw-plugin-api
+Project-URL: Issue Tracker, https://github.com/MurineShiftWork/msw-plugin-api/issues
+Author-email: "Lars B. Rollik" <lars@rollik.me>
+License: Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+        
+        Permission is granted, free of charge, to use, copy, modify, and distribute
+        this software and associated documentation files (the "Software") for
+        non-commercial research or academic purposes only, subject to the following
+        conditions:
+        
+        1. This copyright notice and permission notice must be included in all copies
+           or substantial portions of the Software.
+        
+        2. Any publication, presentation, or product that uses or builds upon the
+           Software must give clear attribution to the original work and its authors.
+        
+        3. Commercial use is prohibited without a separate written commercial licence
+           agreement with the copyright holder. Commercial use means incorporation of
+           the Software into anything for which fees or other compensation are charged
+           or received, including commercial products and commercial services.
+        
+        4. No patent licence, express or implied, is granted under these terms. Any
+           use that would require a patent licence from the copyright holder requires
+           a separate written agreement.
+        
+        5. Redistribution, in source or binary form, is permitted only for
+           non-commercial purposes and must retain this notice unmodified.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+        DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+        SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
+        
+        For commercial or patent licensing enquiries contact: lars@rollik.me
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Free for non-commercial use
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: commitizen; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# msw-plugin-api
+
+Minimal structural interfaces for [MurineShiftWork](https://github.com/MurineShiftWork/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
+
+```python
+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`:
+
+```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.

msw_plugin_api-0.2.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+msw_plugin_api/__init__.py,sha256=5T8Udbwmw6p5wauCFwrgmT_SbXdbwetMgzvL1-BZTn4,1680
+msw_plugin_api/_version.py,sha256=CttnnA3dbvHvGG5cEuWfP0DQ5e_0aiOMkUZSe_ertts,520
+msw_plugin_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msw_plugin_api-0.2.1.dist-info/METADATA,sha256=pWWcSRYSyB9qQPzwGGjzXU3iCPswk5jTDzHO5Tzr3l0,4046
+msw_plugin_api-0.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+msw_plugin_api-0.2.1.dist-info/licenses/LICENSE,sha256=y94meQ0GJdHwzoJDFhr3dwn8YsSVy9TkdM5H-3_DdpQ,1549
+msw_plugin_api-0.2.1.dist-info/RECORD,,

msw_plugin_api-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

msw_plugin_api-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+
+Permission is granted, free of charge, to use, copy, modify, and distribute
+this software and associated documentation files (the "Software") for
+non-commercial research or academic purposes only, subject to the following
+conditions:
+
+1. This copyright notice and permission notice must be included in all copies
+   or substantial portions of the Software.
+
+2. Any publication, presentation, or product that uses or builds upon the
+   Software must give clear attribution to the original work and its authors.
+
+3. Commercial use is prohibited without a separate written commercial licence
+   agreement with the copyright holder. Commercial use means incorporation of
+   the Software into anything for which fees or other compensation are charged
+   or received, including commercial products and commercial services.
+
+4. No patent licence, express or implied, is granted under these terms. Any
+   use that would require a patent licence from the copyright holder requires
+   a separate written agreement.
+
+5. Redistribution, in source or binary form, is permitted only for
+   non-commercial purposes and must retain this notice unmodified.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR DEALINGS IN THE SOFTWARE.
+
+For commercial or patent licensing enquiries contact: lars@rollik.me