stinger-python-utils 0.1.8rc5__py3-none-any.whl → 0.2.0__py3-none-any.whl

stinger_python_utils/message_creator.py

@@ -7,27 +7,82 @@ 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:
+        return cls.binary_signal_message(
+            topic,
+            payload.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+        )
+
+    @classmethod
+    def binary_signal_message(cls, topic: str, payload: bytes, content_type: str) -> Message:
+        cls._validate_topic(topic)
         return Message(
             topic=topic,
-            payload=payload.model_dump_json(by_alias=True).encode("utf-8"),
+            payload=payload,
             qos=1,
             retain=False,
-            content_type="application/json",
+            content_type=content_type,
+        )
+
+    @classmethod
+    def command_message(cls, topic: str, payload: BaseModel, qos: int = 2) -> Message:
+        return cls.binary_command_message(
+            topic,
+            payload.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+            qos=qos,
+        )
+
+    @classmethod
+    def binary_command_message(
+        cls, topic: str, payload: bytes, content_type: str, qos: int = 2
+    ) -> Message:
+        """
+        A command is a signal in reverse: the client publishes it to the server and never
+        learns whether it was acted on.  There is therefore no response topic and no
+        correlation data on the message.
+        """
+        cls._validate_topic(topic)
+        return Message(
+            topic=topic,
+            payload=payload,
+            qos=qos,
+            retain=False,
+            content_type=content_type,
         )
 
     @classmethod
     def status_message(
-        cls, topic, status_message: BaseModel, expiry_seconds: int
+        cls, topic: str, status_message: BaseModel, expiry_seconds: int
+    ) -> Message:
+        return cls.binary_status_message(
+            topic,
+            status_message.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+            expiry_seconds=expiry_seconds,
+        )
+
+    @classmethod
+    def binary_status_message(
+        cls, topic: str, payload: bytes, content_type: str, expiry_seconds: int
     ) -> Message:
+        cls._validate_topic(topic)
         return Message(
             topic=topic,
-            payload=status_message.model_dump_json(by_alias=True).encode("utf-8"),
+            payload=payload,
             qos=1,
             retain=True,
             message_expiry_interval=expiry_seconds,
-            content_type="application/json",
+            content_type=content_type,
         )
 
     @classmethod
@@ -37,10 +92,16 @@ class MessageCreator:
         return_code: Union[int, MethodReturnCode],
         correlation_id: Union[str, bytes, None] = None,
         debug_info: Optional[str] = None,
+        content_type: str = "application/json",
     ) -> Message:
         """
         This could be used for a response to a request, but where there was an error fulfilling the request.
+
+        An error carries no data -- the return code and any debug info travel in MQTT user
+        properties -- so the body is an empty JSON object for a JSON response and empty
+        bytes for any other content type, since a protobuf consumer would reject "{}".
         """
+        cls._validate_topic(topic)
         rc = (
             return_code.value
             if isinstance(return_code, MethodReturnCode)
@@ -48,7 +109,7 @@ class MessageCreator:
         )
         msg_obj = Message(
             topic=topic,
-            payload=b"{}",
+            payload=b"{}" if content_type == "application/json" else b"",
             qos=1,
             retain=False,
             correlation_data=(
@@ -57,7 +118,7 @@ class MessageCreator:
                 else correlation_id
             ),
             user_properties={"ReturnCode": str(rc)},
-            content_type="application/json",
+            content_type=content_type,
         )
         if (
             debug_info is not None and msg_obj.user_properties is not None
@@ -82,12 +143,26 @@ class MessageCreator:
             payload = response_obj.encode("utf-8")
         else:
             payload = response_obj
+        return cls.binary_response_message(
+            response_topic, payload, "application/json", return_code, correlation_id
+        )
+
+    @classmethod
+    def binary_response_message(
+        cls,
+        response_topic: str,
+        payload: bytes,
+        content_type: str,
+        return_code: Union[int, MethodReturnCode],
+        correlation_id: Union[str, bytes, None] = None,
+    ) -> Message:
+        cls._validate_topic(response_topic, "response_topic")
         rc = (
             return_code.value
             if isinstance(return_code, MethodReturnCode)
             else return_code
         )
-        msg_obj = Message(
+        return Message(
             topic=response_topic,
             payload=payload,
             qos=1,
@@ -98,9 +173,8 @@ class MessageCreator:
                 else correlation_id
             ),
             user_properties={"ReturnCode": str(rc)},
-            content_type="application/json",
+            content_type=content_type,
         )
-        return msg_obj
 
     @classmethod
     def property_state_message(
@@ -109,12 +183,24 @@ class MessageCreator:
         """
         Creates a retained message representing the state/value of a property.
         """
+        return cls.binary_property_state_message(
+            topic,
+            state_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+            state_version,
+        )
+
+    @classmethod
+    def binary_property_state_message(
+        cls, topic: str, payload: bytes, content_type: str, state_version: Optional[int] = None
+    ) -> Message:
+        cls._validate_topic(topic)
         msg_obj = Message(
             topic=topic,
-            payload=state_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            payload=payload,
             qos=1,
             retain=True,
-            content_type="application/json",
+            content_type=content_type,
         )
         if state_version is not None:
             msg_obj.user_properties = {"PropertyVersion": str(state_version)}
@@ -132,12 +218,33 @@ class MessageCreator:
         """
         Creates a message representing a request to update a property.
         """
-        msg_obj = Message(
+        return cls.binary_property_update_request_message(
+            topic,
+            property_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+            version,
+            response_topic,
+            correlation_id,
+        )
+
+    @classmethod
+    def binary_property_update_request_message(
+        cls,
+        topic: str,
+        payload: bytes,
+        content_type: str,
+        version: str,
+        response_topic: str,
+        correlation_id: Union[str, bytes, None] = None,
+    ) -> Message:
+        cls._validate_topic(topic)
+        cls._validate_topic(response_topic, "response_topic")
+        return Message(
             topic=topic,
-            payload=property_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            payload=payload,
             qos=1,
             retain=False,
-            content_type="application/json",
+            content_type=content_type,
             response_topic=response_topic,
             correlation_data=(
                 correlation_id.encode("utf-8")
@@ -146,7 +253,6 @@ class MessageCreator:
             ),
             user_properties={"PropertyVersion": str(version)},
         )
-        return msg_obj
 
     @classmethod
     def property_response_message(
@@ -161,6 +267,28 @@ class MessageCreator:
         """
         Creates a message representing a response to a property update request.
         """
+        return cls.binary_property_response_message(
+            response_topic,
+            property_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+            version,
+            return_code,
+            correlation_id,
+            debug_info,
+        )
+
+    @classmethod
+    def binary_property_response_message(
+        cls,
+        response_topic: str,
+        payload: bytes,
+        content_type: str,
+        version: str,
+        return_code: Union[int, MethodReturnCode],
+        correlation_id: Union[str, bytes, None] = None,
+        debug_info: Optional[str] = None,
+    ) -> Message:
+        cls._validate_topic(response_topic, "response_topic")
         rc = (
             return_code.value
             if isinstance(return_code, MethodReturnCode)
@@ -168,10 +296,10 @@ class MessageCreator:
         )
         msg_obj = Message(
             topic=response_topic,
-            payload=property_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            payload=payload,
             qos=1,
             retain=False,
-            content_type="application/json",
+            content_type=content_type,
             correlation_data=(
                 correlation_id.encode("utf-8")
                 if isinstance(correlation_id, str)
@@ -196,19 +324,37 @@ class MessageCreator:
         response_topic: str,
         correlation_id: Union[str, bytes, None] = None,
     ) -> Message:
+        return cls.binary_request_message(
+            topic,
+            request_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            "application/json",
+            response_topic,
+            correlation_id,
+        )
+
+    @classmethod
+    def binary_request_message(
+        cls,
+        topic: str,
+        payload: bytes,
+        content_type: str,
+        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(
+        return Message(
             topic=topic,
-            payload=request_obj.model_dump_json(by_alias=True).encode("utf-8"),
+            payload=payload,
             qos=1,
             retain=False,
             response_topic=response_topic,
-            content_type="application/json",
+            content_type=content_type,
             correlation_data=(
                 correlation_id.encode("utf-8")
                 if isinstance(correlation_id, str)
                 else correlation_id
             ),
         )
-        return msg_obj

stinger_python_utils-0.2.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: stinger-python-utils
+Version: 0.2.0
+Summary: Common utilities for Stinger Python services.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.7
+Requires-Dist: pydantic>=2.5.3
+Requires-Dist: pyqttier>=0.2.0
+Description-Content-Type: text/markdown
+
+# stinger-python-utils
+
+Shared utilities for Stinger Python services, providing convenient message creation for MQTT communication.
+
+
+
+## Installation
+
+```bash
+uv add stinger-python-utils
+```
+
+## MessageCreator
+
+`MessageCreator` is a utility class for creating MQTT messages with standardized properties and payloads.
+
+### Basic Usage
+
+```python
+from pydantic import BaseModel
+from stinger_python_utils.message_creator import MessageCreator
+
+class MyPayload(BaseModel):
+    name: str
+    value: int
+
+payload = MyPayload(name="test", value=42)
+message = MessageCreator.signal_message("my/topic", payload)
+```
+
+### Methods
+
+| Method | Purpose | Return Code |
+|--------|---------|-------------|
+| `signal_message(topic, payload)` | Send a signal with one-time delivery | QoS 1, no retain |
+| `status_message(topic, payload, expiry_seconds)` | Send status that expires | QoS 1, retained, with expiry |
+| `error_response_message(topic, return_code, correlation_id, debug_info)` | Error response to a request | QoS 1, user properties: `ReturnCode` |
+| `response_message(topic, payload, return_code, correlation_id)` | Successful response to a request | QoS 1, user properties: `ReturnCode` |
+| `property_state_message(topic, payload, state_version)` | Publish property state | QoS 1, retained, JSON content type |
+| `property_update_request_message(topic, payload, version, response_topic, correlation_id)` | Request property update | QoS 1, user property: `PropertyVersion` |
+| `property_response_message(topic, payload, version, return_code, correlation_id, debug_info)` | Respond to property update | QoS 1, user properties: `ReturnCode`, `PropertyVersion` |
+| `request_message(topic, payload, response_topic, correlation_id)` | Send a request (auto-generates UUID if no correlation_id) | QoS 1, auto correlation ID |
+
+### Example: Request/Response Pattern
+
+```python
+from pydantic import BaseModel
+from stinger_python_utils.message_creator import MessageCreator
+
+class Request(BaseModel):
+    action: str
+
+request = Request(action="start")
+msg = MessageCreator.request_message(
+    "devices/cmd",
+    request,
+    response_topic="devices/response"
+)
+# Returns a Message with auto-generated correlation ID
+```
+
+### Example: Error Response
+
+```python
+msg = MessageCreator.error_response_message(
+    "devices/response",
+    return_code=500,
+    correlation_id="req-123",
+    debug_info="Device not found"
+)
+# User properties include: ReturnCode=500, DebugInfo=Device not found
+```
+

stinger_python_utils-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+stinger_python_utils/__init__.py,sha256=IjHRV0k2DNwvFrEHebmsXiBvmITE8nQUnsR07h9tVkU,7
+stinger_python_utils/message_creator.py,sha256=SEdtwRJCDSBmVy_1ciJeHwPjK6pav4OIaF0W88RjOMY,11588
+stinger_python_utils/return_codes.py,sha256=AAwshvHu3SBoctwMX35k3j666J4a7DQ3V8AnR7QBjC8,5114
+stinger_python_utils-0.2.0.dist-info/METADATA,sha256=OjtR5mmKovSMZSbeMtaVhRZ-ZJ_GtUe99pKyKC0soUk,2769
+stinger_python_utils-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+stinger_python_utils-0.2.0.dist-info/licenses/LICENSE,sha256=_T-8ExmblJbhv-1AxC6XDVEHg1JdJA-126NvRiMqS-I,1070
+stinger_python_utils-0.2.0.dist-info/RECORD,,

{stinger_python_utils-0.1.8rc5.dist-info → stinger_python_utils-0.2.0.dist-info}/WHEEL

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

stinger_python_utils/mcp/__init__.py

@@ -1,20 +0,0 @@
-"""Stinger MCP server – plugin-based MCP interface to stinger-ipc services.
-
-Public API re-exported here for convenience::
-
-    from stinger_python_utils.mcp import StingerMCPPlugin, SignalDefinition, ...
-"""
-
-from .plugin import (
-    MethodDefinition,
-    PropertyDefinition,
-    SignalDefinition,
-    StingerMCPPlugin,
-)
-
-__all__ = [
-    "MethodDefinition",
-    "PropertyDefinition",
-    "SignalDefinition",
-    "StingerMCPPlugin",
-]

stinger_python_utils/mcp/__main__.py

@@ -1,58 +0,0 @@
-"""Entry-point for ``python -m stinger_python_utils.mcp``."""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import logging
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        prog="stinger-mcp-server",
-        description="Stinger MCP Server – expose stinger-ipc services over MCP",
-    )
-    parser.add_argument(
-        "--transport",
-        choices=["stdio", "sse", "streamable-http"],
-        default="stdio",
-        help="MCP transport to use (default: stdio)",
-    )
-    parser.add_argument(
-        "--host",
-        default="0.0.0.0",
-        help="Bind address for SSE/streamable-http transport (default: 0.0.0.0)",
-    )
-    parser.add_argument(
-        "--port",
-        type=int,
-        default=8000,
-        help="Port for SSE/streamable-http transport (default: 8000)",
-    )
-    parser.add_argument(
-        "--log-level",
-        default="INFO",
-        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
-        help="Logging level (default: INFO)",
-    )
-    args = parser.parse_args()
-
-    logging.basicConfig(
-        level=getattr(logging, args.log_level),
-        format="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
-    )
-
-    from .server import StingerMCPServer
-
-    server = StingerMCPServer()
-
-    if args.transport == "stdio":
-        asyncio.run(server.run_stdio())
-    elif args.transport == "sse":
-        asyncio.run(server.run_sse(host=args.host, port=args.port))
-    elif args.transport == "streamable-http":
-        asyncio.run(server.run_streamable_http(host=args.host, port=args.port))
-
-
-if __name__ == "__main__":
-    main()