stinger-python-utils 0.1.8rc5__tar.gz → 0.2.0__tar.gz

stinger_python_utils-0.2.0/.agents/skills/release/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: release
+description: "Release stinger-python-utils. Use when: releasing a new version, cutting a release, bumping the version, publishing, shipping, preparing a release, running pre-release checks."
+argument-hint: "optional notes or release context"
+---
+
+# Release stinger-python-utils
+
+Runs pre-release checks, bumps the version in `pyproject.toml`, then offers to commit and push.
+
+## Procedure
+
+### 1. Run mypy
+
+```
+uv run mypy src/ tests/
+```
+
+If mypy reports errors, fix them before continuing. Do not proceed until mypy is clean.
+
+### 2. Run pytest
+
+```
+uv run pytest
+```
+
+If any tests fail, fix them before continuing. Do not proceed until all tests pass.
+
+### 3. Bump the version
+
+Read the current version from `pyproject.toml`. Then ask the user:
+
+> The current version is `X.Y.Z`. How would you like to bump it?
+> - **patch** → `X.Y.Z+1`
+> - **minor** → `X.Y+1.0`
+> - **major** → `X+1.0.0`
+> - **manual** → enter a custom version string
+
+Apply the chosen version to the `version` field in `pyproject.toml`.
+
+### 4. Confirm commit and push
+
+Ask the user:
+
+> Ready to commit and push `vX.Y.Z` to `origin/main`?
+> - **Yes** — stage `pyproject.toml`, commit with message `chore: bump version to X.Y.Z`, then push to `origin main`
+> - **No** — stop here; leave the version bump in place for the user to handle manually
+
+Only run `git add`, `git commit`, and `git push` if the user explicitly confirms.
+
+### 5. Build
+
+```
+uv build
+```
+
+If the build fails, report the error and stop. Do not proceed to publish.
+
+### 6. Confirm publish
+
+Ask the user:
+
+> Build succeeded. Publish `vX.Y.Z` to PyPI with `uv publish`?
+> - **Yes** — run `uv publish`
+> - **No** — stop here; the built artifacts are in `dist/`
+
+Only run `uv publish` if the user explicitly confirms.

{stinger_python_utils-0.1.8rc5 → stinger_python_utils-0.2.0}/.github/workflows/python-tests.yml

@@ -11,7 +11,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        # Python 3.7 requires a completely different setup because it is very EOL.
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v4
       - name: Install UV
@@ -20,7 +21,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install project
         run: |
-          uv sync --locked --all-extras --dev
+          uv sync --locked --dev
       - name: Run unit tests
         run: |
           uv run pytest

{stinger_python_utils-0.1.8rc5 → stinger_python_utils-0.2.0}/.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.2.0/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:system",
+    "python-envs.pythonProjects": [],
+    "chat.tools.terminal.autoApprove": {
+        "/^uv run mypy src/ tests/$/": {
+            "approve": true,
+            "matchCommandLine": true
+        }
+    }
+}

stinger_python_utils-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,73 @@
+# 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.1.8rc5 → stinger_python_utils-0.2.0}/pyproject.toml

@@ -4,26 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stinger-python-utils"
-version = "0.1.8rc5"
+version = "0.2.0"
 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",
 ]
 
-[project.optional-dependencies]
-mcp = [
-    "mcp>=1.0.0",
-    "stevedore>=5.0",
-    "uvicorn>=0.20.0",
-]
-
-[project.scripts]
-stinger-mcp-server = "stinger_python_utils.mcp.__main__:main"
-
 [tool.uv]
 managed = true
 
@@ -31,5 +22,5 @@ managed = true
 dev = [
     "black>=23.3.0",
     "mypy>=1.4.1",
-    "pytest>=7.0.0",
+    "pytest>=7.0.0; python_version >= '3.10'",
 ]

{stinger_python_utils-0.1.8rc5 → stinger_python_utils-0.2.0}/src/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