msw-plugin-api 0.2.3__tar.gz → 0.3.0__tar.gz

{msw_plugin_api-0.2.3 → msw_plugin_api-0.3.0}/.gitignore

@@ -10,5 +10,8 @@ build/
 .mypy_cache/
 .ruff_cache/
 
+# library: do not commit the lockfile
+uv.lock
+
 # hatch-vcs generated version file
 src/msw_plugin_api/_version.py

{msw_plugin_api-0.2.3 → msw_plugin_api-0.3.0}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024-present Lars B. Rollik. All rights reserved.
+Copyright (c) 2020-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

{msw_plugin_api-0.2.3 → msw_plugin_api-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: msw-plugin-api
-Version: 0.2.3
+Version: 0.3.0
 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.
+License: Copyright (c) 2020-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
@@ -44,7 +44,7 @@ Classifier: License :: Free for non-commercial use
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Provides-Extra: dev
 Requires-Dist: commitizen; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'

msw_plugin_api-0.3.0/VERSION

@@ -0,0 +1 @@
+0.3.0

{msw_plugin_api-0.2.3 → msw_plugin_api-0.3.0}/pyproject.toml

@@ -11,7 +11,7 @@ license = { file = "LICENSE" }
 authors = [
     { name = "Lars B. Rollik", email = "lars@rollik.me" },
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = []
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -52,7 +52,7 @@ dev = [
 [tool.commitizen]
 name = "cz_conventional_commits"
 version_provider = "commitizen"
-version = "0.2.3"
+version = "0.3.0"
 version_files = ["VERSION"]
 tag_format = "v$version"
 update_changelog_on_bump = false
@@ -69,5 +69,5 @@ select = ["E", "W", "F", "I", "UP", "TCH", "PYI"]
 fixable = ["ALL"]
 
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.11"
 strict = true

msw_plugin_api-0.3.0/src/msw_plugin_api/__init__.py

@@ -0,0 +1,136 @@
+"""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.
+
+    ``session_name`` is the name of the host session directory (e.g. the Open
+    Ephys recording folder). MSW behavioural acquisitions are nested inside
+    it at ``parent_directory/subject/session_name/``.
+
+    Plugins may return this class directly or return any object whose
+    attributes satisfy ``HostSessionInfoProtocol``.
+
+    Args:
+        backend: Identifier for the recording backend (e.g. ``"open_ephys"``).
+        session_name: Name of the host session directory on disk.
+        subject: Subject identifier (e.g. animal ID).
+        parent_directory: Absolute path to the root recordings directory.
+        extra: Optional dict for backend-specific metadata.
+    """
+
+    backend: str
+    session_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.
+
+    Any object that exposes ``backend``, ``session_name``, ``subject``,
+    ``parent_directory``, and ``extra`` satisfies this protocol at runtime
+    via ``isinstance`` checks. ``HostSessionInfo`` implements it directly.
+    """
+
+    backend: str
+    session_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 of this package required)
+    and declare the entry point in ``pyproject.toml``::
+
+        [project.entry-points."msw.host"]
+        myplugin = "my_package.session:MyHostSession"
+
+    MSW core checks ``isinstance(session, HostSessionProtocol)`` at dispatch
+    time, so any class with ``attach``, ``start``, and ``stop`` will pass.
+    """
+
+    def attach(self, **kwargs: object) -> HostSessionInfoProtocol | None:
+        """Attach to the recording backend and return session info.
+
+        Args:
+            **kwargs: Backend-specific keyword arguments (e.g. port, host).
+
+        Returns:
+            A ``HostSessionInfoProtocol``-compatible object on success,
+            or ``None`` if the backend is unavailable.
+        """
+        ...
+
+    def start(self) -> None:
+        """Start the recording session on the backend."""
+        ...
+
+    def stop(self) -> None:
+        """Stop the recording session on the backend."""
+        ...
+
+
+@runtime_checkable
+class MetadataProtocol(Protocol):
+    """Structural protocol for an MSW metadata section.
+
+    A metadata addon owns exactly one top-level subtree of the manifest
+    ``metadata`` key-tree (e.g. ``metadata.probes``, ``metadata.opto``). It
+    keeps its schema in its own package and advertises itself with an entry
+    point::
+
+        [project.entry-points."msw.metadata"]
+        probes = "my_package.metadata:ProbesMetadata"
+
+    MSW core discovers these via ``importlib.metadata`` and checks
+    ``isinstance(obj, MetadataProtocol)``, so any object exposing ``subtree``,
+    ``schema_version``, and ``validate`` satisfies it (no import of this
+    package required). ``validate`` must be non-fatal: it returns a list of
+    human-readable warnings and never raises, because ``metadata`` is optional
+    and legacy/partial trees must still load.
+
+    Attributes:
+        subtree: The reserved top-level metadata key this addon owns.
+        schema_version: The version of this subtree's schema.
+    """
+
+    subtree: str
+    schema_version: int
+
+    def validate(self, block: object) -> list[str]:
+        """Validate this addon's metadata subtree.
+
+        Args:
+            block: The value at ``metadata[self.subtree]``.
+
+        Returns:
+            A list of human-readable warnings (empty when valid). Never raises.
+        """
+        ...

{msw_plugin_api-0.2.3 → msw_plugin_api-0.3.0}/src/msw_plugin_api/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.3'
-__version_tuple__ = version_tuple = (0, 2, 3)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

msw_plugin_api-0.2.3/VERSION

@@ -1 +0,0 @@
-0.2.3

msw_plugin_api-0.2.3/src/msw_plugin_api/__init__.py

@@ -1,65 +0,0 @@
-"""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.
-
-    ``session_name`` is the name of the host session directory (e.g. the Open
-    Ephys recording folder).  MSW behavioural acquisitions are nested inside
-    it: ``basepath/subject/session_name/acquisition_basename/``.
-
-    Plugins may return this class directly or return any object whose
-    attributes satisfy HostSessionInfoProtocol.
-    """
-
-    backend: str
-    session_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
-    session_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: ...