stinger-python-utils 0.1.9__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.2.0/.github/workflows/python-tests.yml

@@ -0,0 +1,30 @@
+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.
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    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 --dev
+      - name: Run unit tests
+        run: |
+          uv run pytest
+      - name: Mypy Type Check
+        run: |
+          uv run mypy --check-untyped-defs ./src/

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.9 → stinger_python_utils-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stinger-python-utils"
-version = "0.1.9"
+version = "0.2.0"
 description = "Common utilities for Stinger Python services."
 readme = "README.md"
 license = "MIT"
@@ -15,16 +15,6 @@ dependencies = [
     "pyqttier>=0.2.0",
 ]
 
-[project.optional-dependencies]
-mcp = [
-    "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-mcp-server = "stinger_python_utils.mcp.__main__:main"
-
 [tool.uv]
 managed = true
 
@@ -32,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.9 → stinger_python_utils-0.2.0}/src/stinger_python_utils/message_creator.py

@@ -16,27 +16,73 @@ class MessageCreator:
 
     @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
@@ -46,9 +92,14 @@ 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 = (
@@ -58,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=(
@@ -67,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
@@ -86,19 +137,32 @@ 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):
             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,
@@ -109,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(
@@ -120,13 +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)}
@@ -144,14 +218,33 @@ class MessageCreator:
         """
         Creates a message representing a request to update a property.
         """
+        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")
-        msg_obj = Message(
+        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")
@@ -160,7 +253,6 @@ class MessageCreator:
             ),
             user_properties={"PropertyVersion": str(version)},
         )
-        return msg_obj
 
     @classmethod
     def property_response_message(
@@ -175,6 +267,27 @@ 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
@@ -183,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)
@@ -210,22 +323,38 @@ class MessageCreator:
         request_obj: BaseModel,
         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