runtimepy 5.13.3__tar.gz → 5.14.0__tar.gz

{runtimepy-5.13.3/runtimepy.egg-info → runtimepy-5.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtimepy
-Version: 5.13.3
+Version: 5.14.0
 Summary: A framework for implementing Python services.
 Home-page: https://github.com/libre-embedded/runtimepy
 Author: Libre Embedded
@@ -17,11 +17,11 @@ Classifier: Development Status :: 5 - Production/Stable
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiofiles
 Requires-Dist: psutil
-Requires-Dist: websockets
 Requires-Dist: svgen>=0.7.12
 Requires-Dist: vcorelib>=3.5.8
+Requires-Dist: websockets
+Requires-Dist: aiofiles
 Provides-Extra: test
 Requires-Dist: pylint; extra == "test"
 Requires-Dist: flake8; extra == "test"
@@ -51,11 +51,11 @@ Dynamic: requires-python
     =====================================
     generator=datazen
     version=3.2.3
-    hash=7dce65a7ea83c118cf5fa28ddbfd533f
+    hash=f46a9eb2c8979cc9ff0a3444077956ec
     =====================================
 -->
 
-# runtimepy ([5.13.3](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.14.0](https://pypi.org/project/runtimepy/))
 
 [![python](https://img.shields.io/pypi/pyversions/runtimepy.svg)](https://pypi.org/project/runtimepy/)
 ![Build Status](https://github.com/libre-embedded/runtimepy/workflows/Python%20Package/badge.svg)

{runtimepy-5.13.3 → runtimepy-5.14.0}/README.md

@@ -2,11 +2,11 @@
     =====================================
     generator=datazen
     version=3.2.3
-    hash=7dce65a7ea83c118cf5fa28ddbfd533f
+    hash=f46a9eb2c8979cc9ff0a3444077956ec
     =====================================
 -->
 
-# runtimepy ([5.13.3](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.14.0](https://pypi.org/project/runtimepy/))
 
 [![python](https://img.shields.io/pypi/pyversions/runtimepy.svg)](https://pypi.org/project/runtimepy/)
 ![Build Status](https://github.com/libre-embedded/runtimepy/workflows/Python%20Package/badge.svg)

{runtimepy-5.13.3 → runtimepy-5.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta:__legacy__"
 
 [project]
 name = "runtimepy"
-version = "5.13.3"
+version = "5.14.0"
 description = "A framework for implementing Python services."
 readme = "README.md"
 requires-python = ">=3.12"

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/__init__.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.2.3
-# hash=940af0fb662bf9b9e98e5ce5df85b4b2
+# hash=c6b2bd8ab0196f119c02bcdf6807ecab
 # =====================================
 
 """
@@ -10,7 +10,7 @@ Useful defaults and other package metadata.
 
 DESCRIPTION = "A framework for implementing Python services."
 PKG_NAME = "runtimepy"
-VERSION = "5.13.3"
+VERSION = "5.14.0"
 
 # runtimepy-specific content.
 METRICS_NAME = "metrics"

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/codec/protocol/__init__.py

@@ -53,3 +53,8 @@ class ProtocolFactory(ABC):
         if cls._singleton is None:
             cls._singleton = cls.instance()
         return cls._singleton
+
+    @classmethod
+    def id(cls) -> int:
+        """Get an integer identifier for this protocol factory."""
+        return cls.singleton().id

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/codec/protocol/base.py

@@ -6,6 +6,7 @@ A module implementing an interface to build communication protocols.
 from contextlib import contextmanager, suppress
 from copy import copy as _copy
 from io import StringIO
+from typing import BinaryIO as _BinaryIO
 from typing import Iterator as _Iterator
 from typing import NamedTuple
 from typing import Optional as _Optional
@@ -18,8 +19,9 @@ from vcorelib.logging import LoggerType
 
 # internal
 from runtimepy.enum import RuntimeEnum as _RuntimeEnum
-from runtimepy.enum.registry import EnumRegistry as _EnumRegistry
+from runtimepy.enum.registry import DEFAULT_ENUM_PRIMITIVE, EnumRegistry
 from runtimepy.primitives import AnyPrimitive as _AnyPrimitive
+from runtimepy.primitives import PrimitiveInstancelike
 from runtimepy.primitives import Primitivelike as _Primitivelike
 from runtimepy.primitives import normalize_instance as _normalize_instance
 from runtimepy.primitives.array import PrimitiveArray
@@ -29,6 +31,7 @@ from runtimepy.primitives.byte_order import (
 from runtimepy.primitives.byte_order import ByteOrder as _ByteOrder
 from runtimepy.primitives.field.fields import BitFields as _BitFields
 from runtimepy.primitives.field.manager import BitFieldsManager
+from runtimepy.primitives.int import UnsignedInt
 from runtimepy.primitives.serializable import Serializable, SerializableMap
 from runtimepy.registry.name import NameRegistry as _NameRegistry
 from runtimepy.registry.name import RegistryKey as _RegistryKey
@@ -66,11 +69,12 @@ class ProtocolBase(PrimitiveArray):
 
     def __init__(
         self,
-        enum_registry: _EnumRegistry,
+        enum_registry: EnumRegistry,
         names: _NameRegistry = None,
         fields: BitFieldsManager = None,
         build: ProtocolBuild = None,
         identifier: int = 1,
+        identifier_primitive: PrimitiveInstancelike = DEFAULT_ENUM_PRIMITIVE,
         byte_order: _Union[_ByteOrder, _RegistryKey] = _DEFAULT_BYTE_ORDER,
         serializables: SerializableMap = None,
         alias: str = None,
@@ -78,6 +82,12 @@ class ProtocolBase(PrimitiveArray):
         """Initialize this protocol."""
 
         self.id = identifier
+        self.id_primitive: UnsignedInt = _normalize_instance(  # type: ignore
+            identifier_primitive
+        )
+        assert self.id_primitive.kind.is_integer
+        self.id_primitive.value = self.id
+
         self.alias = alias
 
         # Register the byte-order enumeration if it's not present.
@@ -150,6 +160,7 @@ class ProtocolBase(PrimitiveArray):
             build=self._build,
             byte_order=self.byte_order,
             identifier=self.id,
+            identifier_primitive=self.id_primitive.kind.name,
             serializables={
                 key: [val[0].copy_without_chain()]
                 for key, val in self.serializables.items()
@@ -331,3 +342,8 @@ class ProtocolBase(PrimitiveArray):
     def __setitem__(self, name: str, val: ProtocolPrimitive) -> None:
         """Set a value of a field belonging to the protocol."""
         self.set(name, val)
+
+    def write_with_id(self, stream: _BinaryIO) -> None:
+        """Write this instance to a stream with its identifier as a prefix."""
+        self.id_primitive.to_stream(stream, byte_order=self.byte_order)
+        self.to_stream(stream)

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/codec/protocol/json.py

@@ -54,6 +54,7 @@ class JsonProtocol(ProtocolBase):
 
         data[META_KEY] = {
             "id": self.id,
+            "id_primitive": self.id_primitive.kind.name,
             "byte_order": self.byte_order.name.lower(),
             "alias": self.alias,
         }
@@ -131,6 +132,7 @@ class JsonProtocol(ProtocolBase):
             fields=fields,
             build=build,
             identifier=_cast(int, data[META_KEY]["id"]),
+            identifier_primitive=_cast(str, data[META_KEY]["id_primitive"]),
             byte_order=_cast(str, data[META_KEY]["byte_order"]),
             alias=data[META_KEY]["alias"],  # type: ignore
             serializables=serializables,

runtimepy-5.14.0/runtimepy/codec/protocol/receiver.py

@@ -0,0 +1,91 @@
+"""
+A module implementing an interface for receiving struct messages.
+"""
+
+# built-in
+from io import BytesIO
+import os
+from typing import Callable
+
+# third-party
+from vcorelib.logging import LoggerMixin
+
+# internal
+from runtimepy.codec.protocol import Protocol, ProtocolFactory
+from runtimepy.primitives.byte_order import ByteOrder
+from runtimepy.primitives.int import UnsignedInt
+
+StructHandler = Callable[[Protocol], None]
+
+
+class StructReceiver(LoggerMixin):
+    """A class for sending and receiving struct messages."""
+
+    id_primitive: UnsignedInt
+    byte_order: ByteOrder
+
+    def __init__(self, *factories: type[ProtocolFactory]) -> None:
+        """Initialize this instance."""
+
+        super().__init__()
+
+        self.handlers: dict[int, StructHandler] = {}
+        self.instances: dict[int, Protocol] = {}
+        for factory in factories:
+            self.register(factory)
+
+    def add_handler(self, identifier: int, handler: StructHandler) -> None:
+        """Add a struct message handler."""
+
+        assert identifier not in self.handlers
+        self.handlers[identifier] = handler
+
+    def register(self, factory: type[ProtocolFactory]) -> None:
+        """Track a protocol factory's structure by identifier."""
+
+        inst = factory.singleton()
+
+        if not hasattr(self, "id_primitive"):
+            self.id_primitive = inst.id_primitive.copy()  # type: ignore
+            self.byte_order = inst.byte_order
+        else:
+            assert self.id_primitive.kind == inst.id_primitive.kind
+            assert self.byte_order == inst.byte_order
+
+        assert inst.id not in self.instances
+        self.instances[inst.id] = inst
+
+    def process(self, data: bytes) -> None:
+        """Attempt to process a struct message."""
+
+        with BytesIO(data) as stream:
+            stream.seek(0, os.SEEK_END)
+            end_pos = stream.tell()
+            stream.seek(0, os.SEEK_SET)
+
+            while stream.tell() < end_pos:
+                ident = self.id_primitive.from_stream(
+                    stream, byte_order=self.byte_order
+                )
+                if ident in self.instances:
+                    inst = self.instances[ident]
+                    inst.from_stream(stream)
+                    if ident in self.handlers:
+                        self.handlers[ident](inst)
+                    else:
+                        self.logger.warning(
+                            "No message handler for struct '%d' (%s).",
+                            ident,
+                            inst,
+                        )
+
+                # Can't continue reading if we don't know this identifier.
+                else:
+                    self.logger.error(
+                        "Unknown struct identifier '%d' "
+                        "@%d/%d of stream (aborting).",
+                        ident,
+                        stream.tell(),
+                        end_pos,
+                    )
+                    stream.seek(0, os.SEEK_END)

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/commands/all.py

@@ -1,17 +1,13 @@
 # =====================================
 # generator=datazen
 # version=3.2.3
-# hash=1814b7f7fae3556a0dbeec37141e4182
+# hash=f4667fb34b5066e16f0621961f11efd8
 # =====================================
 
 """
 A module aggregating package commands.
 """
 
-# built-in
-from typing import List as _List
-from typing import Tuple as _Tuple
-
 # third-party
 from vcorelib.args import CommandRegister as _CommandRegister
 
@@ -24,7 +20,7 @@ from runtimepy.commands.tftp import add_tftp_cmd
 from runtimepy.commands.tui import add_tui_cmd
 
 
-def commands() -> _List[_Tuple[str, str, _CommandRegister]]:
+def commands() -> list[tuple[str, str, _CommandRegister]]:
     """Get this package's commands."""
 
     return [

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/entry.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.2.3
-# hash=79c31d1280a6e97b5d326aecb758c597
+# hash=17cbf063ff27b9146abd2014891778a2
 # =====================================
 
 """
@@ -14,7 +14,6 @@ from logging import getLogger
 import os
 from pathlib import Path
 import sys
-from typing import List
 
 # third-party
 from vcorelib.logging import init_logging, log_time, logging_args
@@ -24,7 +23,7 @@ from runtimepy import DESCRIPTION, VERSION
 from runtimepy.app import add_app_args, entry
 
 
-def main(argv: List[str] = None) -> int:
+def main(argv: list[str] = None) -> int:
     """Program entry-point."""
 
     result = 0

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy/primitives/__init__.py

@@ -121,9 +121,10 @@ def create(value: Primitivelike, **kwargs) -> AnyPrimitive:
     return normalize(value)(**kwargs)
 
 
-def normalize_instance(
-    value: Primitivelike | AnyPrimitive, **kwargs
-) -> AnyPrimitive:
+PrimitiveInstancelike = _Union[Primitivelike, AnyPrimitive]
+
+
+def normalize_instance(value: PrimitiveInstancelike, **kwargs) -> AnyPrimitive:
     """Creates a new instance only if necessary."""
 
     if not isinstance(value, Primitive):

{runtimepy-5.13.3 → runtimepy-5.14.0/runtimepy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtimepy
-Version: 5.13.3
+Version: 5.14.0
 Summary: A framework for implementing Python services.
 Home-page: https://github.com/libre-embedded/runtimepy
 Author: Libre Embedded
@@ -17,11 +17,11 @@ Classifier: Development Status :: 5 - Production/Stable
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiofiles
 Requires-Dist: psutil
-Requires-Dist: websockets
 Requires-Dist: svgen>=0.7.12
 Requires-Dist: vcorelib>=3.5.8
+Requires-Dist: websockets
+Requires-Dist: aiofiles
 Provides-Extra: test
 Requires-Dist: pylint; extra == "test"
 Requires-Dist: flake8; extra == "test"
@@ -51,11 +51,11 @@ Dynamic: requires-python
     =====================================
     generator=datazen
     version=3.2.3
-    hash=7dce65a7ea83c118cf5fa28ddbfd533f
+    hash=f46a9eb2c8979cc9ff0a3444077956ec
     =====================================
 -->
 
-# runtimepy ([5.13.3](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.14.0](https://pypi.org/project/runtimepy/))
 
 [![python](https://img.shields.io/pypi/pyversions/runtimepy.svg)](https://pypi.org/project/runtimepy/)
 ![Build Status](https://github.com/libre-embedded/runtimepy/workflows/Python%20Package/badge.svg)

{runtimepy-5.13.3 → runtimepy-5.14.0}/runtimepy.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ runtimepy/codec/__init__.py
 runtimepy/codec/protocol/__init__.py
 runtimepy/codec/protocol/base.py
 runtimepy/codec/protocol/json.py
+runtimepy/codec/protocol/receiver.py
 runtimepy/codec/system/__init__.py
 runtimepy/commands/__init__.py
 runtimepy/commands/all.py