stinger-python-utils 0.1.8rc4__tar.gz → 0.1.9__tar.gz

stinger_python_utils-0.1.9/.github/workflows/python-tests.yml

@@ -0,0 +1,51 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Python 3.7 requires a completely different setup because it is very EOL.
+        include:
+          - python-version: "3.10"
+            uv-sync-flags: "--all-extras"
+            mypy-flags: "--exclude '/mcp/'"
+          - python-version: "3.11"
+            uv-sync-flags: "--all-extras"
+            mypy-flags: ""
+          - python-version: "3.12"
+            uv-sync-flags: "--all-extras"
+            mypy-flags: ""
+          - python-version: "3.13"
+            uv-sync-flags: "--all-extras"
+            mypy-flags: ""
+          - python-version: "3.14"
+            uv-sync-flags: "--all-extras"
+            mypy-flags: ""
+          - python-version: "3.8"
+            uv-sync-flags: ""
+            mypy-flags: "--exclude '/mcp/'"
+          - python-version: "3.9"
+            uv-sync-flags: ""
+            mypy-flags: "--exclude '/mcp/'"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install project
+        run: |
+          uv sync --locked ${{ matrix.uv-sync-flags }} --dev
+      - name: Run unit tests
+        run: |
+          uv run pytest
+      - name: Mypy Type Check
+        run: |
+          uv run mypy --check-untyped-defs ${{ matrix.mypy-flags }} ./src/

{stinger_python_utils-0.1.8rc4 → stinger_python_utils-0.1.9}/.github/workflows/python37.yml

@@ -7,7 +7,7 @@ on:
     branches: [ main ]
 
 jobs:
-  test:
+  test_py37:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4

{stinger_python_utils-0.1.8rc4 → stinger_python_utils-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stinger-python-utils
-Version: 0.1.8rc4
+Version: 0.1.9
 Summary: Common utilities for Stinger Python services.
 License-Expression: MIT
 License-File: LICENSE
@@ -8,9 +8,9 @@ Requires-Python: >=3.7
 Requires-Dist: pydantic>=2.5.3
 Requires-Dist: pyqttier>=0.2.0
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Requires-Dist: stevedore>=5.0; extra == 'mcp'
-Requires-Dist: uvicorn>=0.20.0; extra == 'mcp'
+Requires-Dist: mcp>=1.27.0; (python_version >= '3.10') and extra == 'mcp'
+Requires-Dist: stevedore>=5.7; (python_version >= '3.10') and extra == 'mcp'
+Requires-Dist: uvicorn>=0.44.0; (python_version >= '3.10') and extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # stinger-python-utils

{stinger_python_utils-0.1.8rc4 → stinger_python_utils-0.1.9}/pyproject.toml

@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stinger-python-utils"
-version = "0.1.8rc4"
+version = "0.1.9"
 description = "Common utilities for Stinger Python services."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.7"
+
 dependencies = [
     "pydantic>=2.5.3",
     "pyqttier>=0.2.0",
@@ -16,9 +17,9 @@ dependencies = [
 
 [project.optional-dependencies]
 mcp = [
-    "mcp>=1.0.0",
-    "stevedore>=5.0",
-    "uvicorn>=0.20.0",
+    "mcp>=1.27.0; python_version >= '3.10'",
+    "stevedore>=5.7; python_version >= '3.10'",
+    "uvicorn>=0.44.0; python_version >= '3.10'",
 ]
 
 [project.scripts]

{stinger_python_utils-0.1.8rc4 → stinger_python_utils-0.1.9}/src/stinger_python_utils/mcp/plugin.py

@@ -17,6 +17,8 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any
 
+from pydantic import BaseModel
+
 
 # ------------------------------------------------------------------
 # Data models
@@ -66,19 +68,18 @@ class MethodDefinition:
     """Describes a callable method on a stinger-ipc client.
 
     Each method is exposed as an MCP **tool** whose ``inputSchema`` is
-    *arguments_schema*.
+    derived from *arguments_model* via ``model_json_schema()``.
 
-    *arguments_schema* must be a valid `JSON Schema`_ of type
-    ``"object"``.  The property names **must** match the keyword
-    argument names accepted by the client method.
+    *arguments_model* must be a :class:`pydantic.BaseModel` subclass.
+    When the tool is invoked, the raw JSON arguments are loaded into
+    an instance of this model and the model is passed to
+    ``call_{method_name}`` on the client.
 
-    .. _JSON Schema: https://json-schema.org/
+    If *arguments_model* is ``None`` the tool accepts no arguments.
     """
 
     name: str
-    arguments_schema: dict[str, Any] = field(
-        default_factory=lambda: {"type": "object"}
-    )
+    arguments_model: type[BaseModel] | None = None
     description: str = ""
 
 
@@ -189,19 +190,24 @@ class StingerMCPPlugin(ABC):
         setattr(client, prop_name, list(arguments.values())[0])
 
     def call_method(
-        self, client: Any, method_name: str, arguments: dict[str, Any]
+        self, client: Any, method_name: str, arguments: BaseModel | None
     ) -> Any:
         """Invoke *method_name* on *client* with *arguments*.
 
+        *arguments* is a validated :class:`pydantic.BaseModel` instance
+        (or ``None`` when the method takes no parameters).
+
         The default implementation calls::
 
-            getattr(client, method_name)(**arguments)
+            getattr(client, f"call_{method_name}")(arguments)
 
         and returns whatever the method returns (typically a
         ``concurrent.futures.Future``).
         """
         method = getattr(client, f"call_{method_name}")
-        return method(**arguments)
+        if arguments is None:
+            return method()
+        return method(arguments)
 
     def serialize_property(self, prop_name: str, value: Any) -> str:
         """Serialize a property *value* to a JSON string for the MCP resource.

{stinger_python_utils-0.1.8rc4 → stinger_python_utils-0.1.9}/src/stinger_python_utils/mcp/server.py

@@ -193,7 +193,11 @@ class StingerMCPServer:
                                 or f"Call {mdef.name} on {state.plugin_name} "
                                 f"instance {state.instance_id}"
                             ),
-                            inputSchema=mdef.arguments_schema,
+                            inputSchema=(
+                                mdef.arguments_model.model_json_schema()
+                                if mdef.arguments_model is not None
+                                else {"type": "object"}
+                            ),
                         )
                     )
 
@@ -214,8 +218,8 @@ class StingerMCPServer:
 
     def _resolve_tool(
         self, name: str
-    ) -> tuple[InstanceState, str, str] | None:
-        """Map a tool *name* → ``(state, kind, item_name)``.
+    ) -> tuple[InstanceState, str, MethodDefinition | PropertyDefinition] | None:
+        """Map a tool *name* → ``(state, kind, definition)``.
 
         *kind* is ``"method"`` or ``"property"``.  Methods are checked
         first so that a method named ``set_foo`` takes precedence over
@@ -235,7 +239,7 @@ class StingerMCPServer:
                 # Methods take priority
                 for mdef in state.plugin.get_methods():
                     if _sanitize(mdef.name) == remainder:
-                        return state, "method", mdef.name
+                        return state, "method", mdef
 
                 # Property setters: set_<prop_name>
                 if remainder.startswith("set_"):
@@ -245,7 +249,7 @@ class StingerMCPServer:
                             _sanitize(pdef.name) == prop_token
                             and not pdef.readonly
                         ):
-                            return state, "property", pdef.name
+                            return state, "property", pdef
 
         return None
 
@@ -256,23 +260,32 @@ class StingerMCPServer:
         if target is None:
             raise ValueError(f"Unknown tool: {name}")
 
-        state, kind, item_name = target
+        state, kind, defn = target
 
         if kind == "property":
             try:
-                state.plugin.write_property(state.client, item_name, arguments)
-                text = json.dumps({"status": "ok", "property": item_name})
+                state.plugin.write_property(
+                    state.client, defn.name, arguments
+                )
+                text = json.dumps({"status": "ok", "property": defn.name})
             except Exception as exc:
-                logger.exception("Error setting property %s", item_name)
+                logger.exception("Error setting property %s", defn.name)
                 text = json.dumps(
                     {"status": "error", "error": str(exc)}, default=str
                 )
             return [types.TextContent(type="text", text=text)]
 
         # kind == "method"
+        assert isinstance(defn, MethodDefinition)
         try:
+            # Load the pydantic model from the raw arguments
+            model = (
+                defn.arguments_model(**arguments)
+                if defn.arguments_model is not None
+                else None
+            )
             result = state.plugin.call_method(
-                state.client, item_name, arguments
+                state.client, defn.name, model
             )
             if isinstance(result, Future):
                 result = await _resolve_future(result)
@@ -284,7 +297,7 @@ class StingerMCPServer:
             else:
                 text = json.dumps(result, default=str)
         except Exception as exc:
-            logger.exception("Error calling method %s", item_name)
+            logger.exception("Error calling method %s", defn.name)
             text = json.dumps(
                 {"status": "error", "error": str(exc)}, default=str
             )
@@ -364,11 +377,11 @@ class StingerMCPServer:
 
     def _load_plugins(self) -> None:
         def _on_failure(
-            _mgr: ExtensionManager, entrypoint: Any, err: Exception
+            _mgr: Any, entrypoint: Any, err: BaseException
         ) -> None:
             logger.error("Failed to load plugin %s: %s", entrypoint, err)
 
-        mgr = ExtensionManager(
+        mgr: ExtensionManager[Any] = ExtensionManager(
             namespace=self.STEVEDORE_NAMESPACE,
             invoke_on_load=True,
             on_load_failure_callback=_on_failure,

{stinger_python_utils-0.1.8rc4 → stinger_python_utils-0.1.9}/src/stinger_python_utils/message_creator.py

@@ -7,8 +7,16 @@ from .return_codes import MethodReturnCode
 
 class MessageCreator:
 
+    @staticmethod
+    def _validate_topic(topic: str, param_name: str = "topic") -> None:
+        if "+" in topic:
+            raise ValueError(
+                f"{param_name} must not contain '+', got: {topic!r}"
+            )
+
     @classmethod
     def signal_message(cls, topic: str, payload: BaseModel) -> Message:
+        cls._validate_topic(topic)
         return Message(
             topic=topic,
             payload=payload.model_dump_json(by_alias=True).encode("utf-8"),
@@ -21,6 +29,7 @@ class MessageCreator:
     def status_message(
         cls, topic, status_message: BaseModel, expiry_seconds: int
     ) -> Message:
+        cls._validate_topic(topic)
         return Message(
             topic=topic,
             payload=status_message.model_dump_json(by_alias=True).encode("utf-8"),
@@ -41,6 +50,7 @@ class MessageCreator:
         """
         This could be used for a response to a request, but where there was an error fulfilling the request.
         """
+        cls._validate_topic(topic)
         rc = (
             return_code.value
             if isinstance(return_code, MethodReturnCode)
@@ -76,6 +86,7 @@ class MessageCreator:
         """
         This could be used for a successful response to a request.
         """
+        cls._validate_topic(response_topic, "response_topic")
         if isinstance(response_obj, BaseModel):
             payload = response_obj.model_dump_json(by_alias=True).encode("utf-8")
         elif isinstance(response_obj, str):
@@ -109,6 +120,7 @@ class MessageCreator:
         """
         Creates a retained message representing the state/value of a property.
         """
+        cls._validate_topic(topic)
         msg_obj = Message(
             topic=topic,
             payload=state_obj.model_dump_json(by_alias=True).encode("utf-8"),
@@ -132,6 +144,8 @@ class MessageCreator:
         """
         Creates a message representing a request to update a property.
         """
+        cls._validate_topic(topic)
+        cls._validate_topic(response_topic, "response_topic")
         msg_obj = Message(
             topic=topic,
             payload=property_obj.model_dump_json(by_alias=True).encode("utf-8"),
@@ -161,6 +175,7 @@ class MessageCreator:
         """
         Creates a message representing a response to a property update request.
         """
+        cls._validate_topic(response_topic, "response_topic")
         rc = (
             return_code.value
             if isinstance(return_code, MethodReturnCode)
@@ -196,6 +211,8 @@ class MessageCreator:
         response_topic: str,
         correlation_id: Union[str, bytes, None] = None,
     ) -> Message:
+        cls._validate_topic(topic)
+        cls._validate_topic(response_topic, "response_topic")
         if correlation_id is None:
             correlation_id = str(uuid.uuid4())
         msg_obj = Message(