runtimepy 5.10.2__tar.gz → 5.11.0__tar.gz

{runtimepy-5.10.2/runtimepy.egg-info → runtimepy-5.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtimepy
-Version: 5.10.2
+Version: 5.11.0
 Summary: A framework for implementing Python services.
 Home-page: https://github.com/vkottler/runtimepy
 Author: Vaughn Kottler
@@ -17,11 +17,11 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: psutil
-Requires-Dist: aiofiles
-Requires-Dist: vcorelib>=3.5.1
 Requires-Dist: websockets
+Requires-Dist: aiofiles
 Requires-Dist: svgen>=0.7.4
+Requires-Dist: vcorelib>=3.5.1
+Requires-Dist: psutil
 Provides-Extra: test
 Requires-Dist: pylint; extra == "test"
 Requires-Dist: flake8; extra == "test"
@@ -50,11 +50,11 @@ Dynamic: requires-python
     =====================================
     generator=datazen
     version=3.1.4
-    hash=887650b5b88ff596b3ab067e01de6fbd
+    hash=12eb2a9d91dea3ae83e38a864f6cab4b
     =====================================
 -->
 
-# runtimepy ([5.10.2](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.11.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/vkottler/runtimepy/workflows/Python%20Package/badge.svg)

{runtimepy-5.10.2 → runtimepy-5.11.0}/README.md

@@ -2,11 +2,11 @@
     =====================================
     generator=datazen
     version=3.1.4
-    hash=887650b5b88ff596b3ab067e01de6fbd
+    hash=12eb2a9d91dea3ae83e38a864f6cab4b
     =====================================
 -->
 
-# runtimepy ([5.10.2](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.11.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/vkottler/runtimepy/workflows/Python%20Package/badge.svg)

{runtimepy-5.10.2 → runtimepy-5.11.0}/pyproject.toml

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

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/__init__.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.1.4
-# hash=9114f245a523f60ffbbfdd040548fc7c
+# hash=c4e165f8c6309dd6819689f0262cf92d
 # =====================================
 
 """
@@ -10,7 +10,7 @@ Useful defaults and other package metadata.
 
 DESCRIPTION = "A framework for implementing Python services."
 PKG_NAME = "runtimepy"
-VERSION = "5.10.2"
+VERSION = "5.11.0"
 
 # runtimepy-specific content.
 METRICS_NAME = "metrics"

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/channel/environment/array.py

@@ -95,10 +95,10 @@ class ArrayChannelEnvironment(_BaseChannelEnvironment):
 
             # Begin handling a new bit-fields primitive.
             if curr_fields is None:
-                fields = self.fields.get_fields(name)
-                assert fields is not None, f"Unknown bit-field '{name}'!"
-                result.array.add(fields.raw)
-                available_field_names = set(fields.names)
+                curr_fields = self.fields.get_fields(name)
+                assert curr_fields is not None, f"Unknown bit-field '{name}'!"
+                result.array.add(curr_fields.raw)
+                available_field_names = set(curr_fields.names)
 
             # Keep track of field names processed in the current bit-fields
             # primitive.

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/channel/environment/telemetry.py

@@ -99,7 +99,7 @@ class TelemetryChannelEnvironment(_BaseChannelEnvironment):
                 cast(int, channels.event_header["timestamp"]),
                 kind.decode(
                     data,
-                    byte_order=channels.event_header.array.byte_order,
+                    byte_order=channels.event_header.byte_order,
                 ),
             )
 
@@ -120,7 +120,7 @@ class TelemetryChannelEnvironment(_BaseChannelEnvironment):
                 cast(int, self.channels.event_header["timestamp"]),
                 kind.decode(
                     data,
-                    byte_order=self.channels.event_header.array.byte_order,
+                    byte_order=self.channels.event_header.byte_order,
                 ),
             )
 
@@ -146,7 +146,7 @@ class TelemetryChannelEnvironment(_BaseChannelEnvironment):
                 read_size = channels.event_header.size
                 data = channels.event_fifo.pop(read_size)
                 if data is not None:
-                    channels.event_header.array.update(data)
+                    channels.event_header.update(data)
 
                     # Update local variables.
                     ident = cast(int, channels.event_header["identifier"])

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/channel/event/__init__.py

@@ -90,7 +90,7 @@ class PrimitiveEvent:
             self.header["timestamp"] = curr_ns
 
             # Write header then value.
-            array = self.header.array
+            array = self.header
             written += array.to_stream(stream)
             written += raw.to_stream(stream, byte_order=array.byte_order)
             if flush:

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/codec/protocol/__init__.py

@@ -4,7 +4,6 @@ A module implementing an interface to build communication protocols.
 
 # built-in
 from abc import ABC, abstractmethod
-from copy import copy
 from typing import Optional
 
 # internal
@@ -40,10 +39,12 @@ class ProtocolFactory(ABC):
 
         # We only need to run the routine that populates the protocol once.
         if not cls.initialized:
+            if not cls.protocol.alias:
+                cls.protocol.alias = cls.__name__
             cls.initialize(cls.protocol)
             cls.initialized = True
 
-        return copy(cls.protocol)
+        return cls.protocol.copy()
 
     @classmethod
     def singleton(cls) -> Protocol:

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/codec/protocol/base.py

@@ -3,8 +3,9 @@ A module implementing an interface to build communication protocols.
 """
 
 # built-in
-from contextlib import contextmanager
+from contextlib import contextmanager, suppress
 from copy import copy as _copy
+from io import StringIO
 from typing import Iterator as _Iterator
 from typing import NamedTuple
 from typing import Optional as _Optional
@@ -57,9 +58,10 @@ class FieldSpec(NamedTuple):
 
 
 T = _TypeVar("T", bound="ProtocolBase")
+ProtocolBuild = list[_Union[int, FieldSpec, tuple[str, int]]]
 
 
-class ProtocolBase:
+class ProtocolBase(PrimitiveArray):
     """A class for defining runtime communication protocols."""
 
     def __init__(
@@ -67,14 +69,16 @@ class ProtocolBase:
         enum_registry: _EnumRegistry,
         names: _NameRegistry = None,
         fields: BitFieldsManager = None,
-        build: list[_Union[int, FieldSpec, str]] = None,
+        build: ProtocolBuild = None,
         identifier: int = 1,
         byte_order: _Union[_ByteOrder, _RegistryKey] = _DEFAULT_BYTE_ORDER,
         serializables: SerializableMap = None,
+        alias: str = None,
     ) -> None:
         """Initialize this protocol."""
 
         self.id = identifier
+        self.alias = alias
 
         # Register the byte-order enumeration if it's not present.
         self._enum_registry = enum_registry
@@ -86,7 +90,8 @@ class ProtocolBase:
             byte_order = _ByteOrder(
                 self._enum_registry["ByteOrder"].get_int(byte_order)
             )
-        self.array = PrimitiveArray(byte_order=byte_order)
+
+        super().__init__(byte_order=byte_order)
 
         if names is None:
             names = _NameRegistry()
@@ -96,11 +101,11 @@ class ProtocolBase:
             fields = BitFieldsManager(self.names, self._enum_registry)
         self._fields = fields
 
-        self._regular_fields: dict[str, _AnyPrimitive] = {}
+        self._regular_fields: dict[str, list[_AnyPrimitive]] = {}
         self._enum_fields: dict[str, _RuntimeEnum] = {}
 
         # Keep track of the order that the protocol was created.
-        self._build: list[_Union[int, FieldSpec, str]] = []
+        self._build: ProtocolBuild = []
 
         # Keep track of named serializables.
         self.serializables: SerializableMap = {}
@@ -110,24 +115,28 @@ class ProtocolBase:
             build = []
         for item in build:
             if isinstance(item, int):
-                self._add_bit_fields(self._fields.fields[item], track=False)
-            elif isinstance(item, str):
-                assert serializables, (item, serializables)
-                self.add_field(item, serializable=serializables[item])
-                del serializables[item]
-            else:
+                self._add_bit_fields(self._fields.fields[item])
+            elif isinstance(item, FieldSpec):
                 self.add_field(
                     item.name,
                     item.kind,
                     enum=item.enum,
-                    track=False,
                     array_length=item.array_length,
                 )
+            else:
+                assert serializables, (item, serializables)
+                name = item[0]
+                self.add_serializable(
+                    name,
+                    serializables[name][0],
+                    array_length=None if item[1] == 1 else item[1],
+                )
+                del serializables[name]
 
         # Ensure all serializables were handled via build.
         assert not serializables, serializables
 
-    def __copy__(self: T) -> T:
+    def _copy_impl(self: T) -> T:
         """Create another protocol instance from this one."""
 
         return self.__class__(
@@ -135,11 +144,12 @@ class ProtocolBase:
             names=self.names,
             fields=_copy(self._fields),
             build=self._build,
-            byte_order=self.array.byte_order,
+            byte_order=self.byte_order,
             serializables={
-                key: val.copy_without_chain()
+                key: [val[0].copy_without_chain()]
                 for key, val in self.serializables.items()
             },
+            alias=self.alias,
         )
 
     def register_name(self, name: str) -> int:
@@ -151,13 +161,14 @@ class ProtocolBase:
 
     def add_serializable(
         self, name: str, serializable: Serializable, array_length: int = None
-    ) -> int:
+    ) -> None:
         """Add a serializable instance."""
 
         self.register_name(name)
-        self.serializables[name] = serializable
-        self._build.append(name)
-        return self.array.add_to_end(serializable, array_length=array_length)
+
+        instances = self.add_to_end(serializable, array_length=array_length)
+        self._build.append((name, len(instances)))
+        self.serializables[name] = instances
 
     def add_field(
         self,
@@ -165,17 +176,17 @@ class ProtocolBase:
         kind: _Primitivelike = None,
         enum: _RegistryKey = None,
         serializable: Serializable = None,
-        track: bool = True,
         array_length: int = None,
-    ) -> int:
+    ) -> None:
         """Add a new field to the protocol."""
 
         # Add the serializable to the end of this protocol.
         if serializable is not None:
             assert kind is None and enum is None
-            return self.add_serializable(
+            self.add_serializable(
                 name, serializable, array_length=array_length
             )
+            return
 
         self.register_name(name)
 
@@ -189,25 +200,20 @@ class ProtocolBase:
                 kind = runtime_enum.primitive
 
         assert kind is not None
-        new = _create(kind)
-
-        result = self.array.add(new, array_length=array_length)
-        self._regular_fields[name] = new
 
-        if track:
-            self._build.append(
-                FieldSpec(name, kind, enum, array_length=array_length)
-            )
+        self._regular_fields[name] = self.add(
+            _create(kind), array_length=array_length
+        )
 
-        return result
+        self._build.append(
+            FieldSpec(name, kind, enum, array_length=array_length)
+        )
 
-    def _add_bit_fields(self, fields: _BitFields, track: bool = True) -> None:
+    def _add_bit_fields(self, fields: _BitFields) -> None:
         """Add a bit-fields instance."""
 
-        idx = self._fields.add(fields)
-        self.array.add(fields.raw)
-        if track:
-            self._build.append(idx)
+        self._build.append(self._fields.add(fields))
+        self.add(fields.raw)
 
     @contextmanager
     def add_bit_fields(
@@ -219,55 +225,92 @@ class ProtocolBase:
         yield new
         self._add_bit_fields(new)
 
-    def value(self, name: str, resolve_enum: bool = True) -> ProtocolPrimitive:
+    def value(
+        self, name: str, resolve_enum: bool = True, index: int = 0
+    ) -> ProtocolPrimitive:
         """Get the value of a field belonging to the protocol."""
 
         val: ProtocolPrimitive = 0
 
         if name in self._regular_fields:
-            val = self._regular_fields[name].value
+            val = self._regular_fields[name][index].value
 
             # Resolve the enum value.
             if resolve_enum and name in self._enum_fields:
-                val = self._enum_fields[name].get_str(val)  # type: ignore
+                with suppress(KeyError):
+                    val = self._enum_fields[name].get_str(val)  # type: ignore
 
             return val
 
         return self._fields.get(name, resolve_enum=resolve_enum)
 
-    @property
-    def size(self) -> int:
-        """Get this protocol's size in bytes."""
-        return self.array.length()
-
     def trace_size(self, logger: LoggerType) -> None:
         """Log a size trace."""
-        logger.info("%s: %s", self, self.array.length_trace())
+        logger.info("%s: %s", self, self.length_trace(alias=self.alias))
 
     def __str__(self) -> str:
         """Get this instance as a string."""
 
-        return f"({self.size}) " + " ".join(
-            f"{name}={self[name]}" for name in self.names.registered_order
-        )
+        with StringIO() as stream:
+            stream.write(
+                "{"
+                + f"{self.resolve_alias(alias=self.alias)}({self.length()}): "
+            )
+
+            parts = []
+            for name in self.names.registered_order:
+                part = name
+                count = 1
+
+                if name in self.serializables:
+                    count = len(self.serializables[name])
+                    part += f"<{self.serializables[name][0].resolve_alias()}>"
+                elif name in self._regular_fields:
+                    count = len(self._regular_fields[name])
+
+                    part += f"<{self._regular_fields[name][0].kind}>"
+
+                if count > 1:
+                    part += f"[{count}] = ["
+                    if name in self._regular_fields:
+                        part += ", ".join(
+                            str(x.value) for x in self._regular_fields[name]
+                        )
+                    else:
+                        part += ", ".join("..." for _ in range(count))
+                    part += "]"
+                else:
+                    part += f" = {self[name]}"
+
+                parts.append(part)
 
-    def __getitem__(self, name: str) -> ProtocolPrimitive:
+            stream.write(", ".join(parts))
+
+            stream.write("}")
+
+            return stream.getvalue()
+
+    def __getitem__(self, name: str) -> ProtocolPrimitive:  # type: ignore
         """Get the value of a protocol field."""
 
         if name in self.serializables:
-            return str(self.serializables[name])
+            return str(self.serializables[name][0])
 
         return self.value(name)
 
-    def __setitem__(self, name: str, val: ProtocolPrimitive) -> None:
+    def set(self, name: str, val: ProtocolPrimitive, index: int = 0) -> None:
         """Set a value of a field belonging to the protocol."""
 
         if name in self._regular_fields:
             # Resolve an enum value.
             if isinstance(val, str):
                 val = self._enum_fields[name].get_int(val)
-            self._regular_fields[name].value = val
+            self._regular_fields[name][index].value = val
         elif name in self.serializables and isinstance(val, str):
-            self.serializables[name].update_str(val)
+            self.serializables[name][index].update_str(val)
         else:
             self._fields.set(name, val)  # type: ignore
+
+    def __setitem__(self, name: str, val: ProtocolPrimitive) -> None:
+        """Set a value of a field belonging to the protocol."""
+        self.set(name, val)

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/codec/protocol/json.py

@@ -14,7 +14,11 @@ from vcorelib.io.types import JsonObject as _JsonObject
 from vcorelib.io.types import JsonValue as _JsonValue
 
 # internal
-from runtimepy.codec.protocol.base import FieldSpec, ProtocolBase
+from runtimepy.codec.protocol.base import (
+    FieldSpec,
+    ProtocolBase,
+    ProtocolBuild,
+)
 from runtimepy.primitives.field.manager import (
     ENUMS_KEY,
     NAMES_KEY,
@@ -46,9 +50,11 @@ class JsonProtocol(ProtocolBase):
         """Export this protocol's data to JSON."""
 
         data = self._fields.export_json(resolve_enum=resolve_enum)
+
         data[META_KEY] = {
             "id": self.id,
-            "byte_order": self.array.byte_order.name.lower(),
+            "byte_order": self.byte_order.name.lower(),
+            "alias": self.alias,
         }
 
         # Export regular-field names.
@@ -72,12 +78,12 @@ class JsonProtocol(ProtocolBase):
         )
 
         # Export the build specification.
-        build: list[_Union[int, _JsonObject, str]] = []
+        build: list[_Union[int, _JsonObject, str, tuple[str, int]]] = []
         for item in self._build:
-            if isinstance(item, (int, str)):
-                build.append(item)
-            else:
+            if isinstance(item, FieldSpec):
                 build.append(item.asdict())
+            else:
+                build.append(item)
         data[BUILD_KEY] = _cast(_JsonObject, build)
 
         # Export regular-field values.
@@ -101,18 +107,16 @@ class JsonProtocol(ProtocolBase):
         fields = BitFieldsManager.import_json(data)
 
         # Create the build specification.
-        build: list[_Union[int, FieldSpec, str]] = []
+        build: ProtocolBuild = []
         for item in data[BUILD_KEY]:
-            if isinstance(item, int):
-                build.append(item)
-            else:
+            if isinstance(item, dict):
                 build.append(
                     FieldSpec(
-                        item["name"],  # type: ignore
-                        item["kind"],  # type: ignore
-                        enum=item.get("enum"),  # type: ignore
+                        item["name"], item["kind"], enum=item.get("enum")
                     )
                 )
+            else:
+                build.append(item)  # type: ignore
 
         result = cls(
             fields.enums,
@@ -121,6 +125,7 @@ class JsonProtocol(ProtocolBase):
             build=build,
             identifier=_cast(int, data[META_KEY]["id"]),
             byte_order=_cast(str, data[META_KEY]["byte_order"]),
+            alias=data[META_KEY]["alias"],  # type: ignore
         )
 
         # Set values.

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/codec/system/__init__.py

@@ -146,7 +146,7 @@ class TypeSystem(LoggerMixin):
         if field_type_name in self.custom:
             custom.add_serializable(
                 field_name,
-                self.custom[field_type_name].array.copy(),
+                self.custom[field_type_name].copy(),
                 array_length=array_length,
             )
         else:
@@ -227,8 +227,7 @@ class TypeSystem(LoggerMixin):
         if found in self.primitives:
             return self.primitives[found].size
 
-        result = self.custom[found].size
         if trace:
             self.custom[found].trace_size(self.logger)
 
-        return result
+        return self.custom[found].length()

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/net/udp/tftp/__init__.py

@@ -50,7 +50,6 @@ class TftpConnection(BaseTftpConnection):
 
             def ack_sender() -> None:
                 """Send acks."""
-                nonlocal idx
                 endpoint.ack_sender(idx - 1, endpoint.addr)
 
             def send_rrq() -> None:

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/primitives/array/__init__.py

@@ -180,44 +180,50 @@ class PrimitiveArray(Serializable):
 
     def add_primitive(
         self, kind: _Primitivelike, array_length: int = None
-    ) -> int:
+    ) -> list[_AnyPrimitive]:
         """Add to the array by specifying the type of element to add."""
+
         return self.add(_create(kind), array_length=array_length)
 
-    def add(self, primitive: _AnyPrimitive, array_length: int = None) -> int:
+    def add(
+        self, primitive: _AnyPrimitive, array_length: int = None
+    ) -> list[_AnyPrimitive]:
         """Add another primitive to manage."""
 
+        result = []
+
         end = self.end
         if isinstance(end, PrimitiveArray):
             if end is self:
                 self._primitives.append(primitive)
                 self._format += primitive.kind.format
                 self.size += primitive.size
+                result.append(primitive)
 
                 # Handle array length.
                 if array_length is not None:
                     for _ in range(array_length - 1):
+                        inst = primitive.copy()
                         self._primitives.append(
-                            primitive.copy(),  # type: ignore
+                            inst,  # type: ignore
                         )
-                        self._format += primitive.kind.format
-                        self.size += primitive.size
+                        self._format += inst.kind.format
+                        self.size += inst.size
+                        result.append(inst)  # type: ignore
 
                 # Add tracking information for the current tail.
                 curr_idx = len(self._primitives)
                 self._bytes_to_index[self.size] = curr_idx
                 self._index_to_bytes[curr_idx] = self.size
-                result = self.size
             else:
-                result = end.add(primitive, array_length=array_length)
+                result.extend(end.add(primitive, array_length=array_length))
 
         # Add a new primitive array to the end of this chain for this
         # primitive.
         else:
             new_array = PrimitiveArray(byte_order=self.byte_order)
             end.assign(new_array)
-
-            result = new_array.add(primitive, array_length=array_length)
+            result.extend(new_array.add(primitive, array_length=array_length))
 
         return result
 
@@ -245,3 +251,16 @@ class PrimitiveArray(Serializable):
     ) -> None:
         """Update a fragment by index."""
         self._fragments[index].update(data, timestamp_ns=timestamp_ns)
+
+    def randomize(self, timestamp_ns: int = None, chain: bool = True) -> None:
+        """Randomize array contents."""
+
+        for prim in self._primitives:
+            prim.randomize(timestamp_ns=timestamp_ns)
+
+        if (
+            chain
+            and self.chain is not None
+            and isinstance(self.chain, PrimitiveArray)
+        ):
+            self.chain.randomize(timestamp_ns=timestamp_ns, chain=chain)

{runtimepy-5.10.2 → runtimepy-5.11.0}/runtimepy/primitives/bool.py

@@ -2,6 +2,9 @@
 A module implementing a boolean-primitive interface.
 """
 
+# built-in
+from random import getrandbits
+
 # internal
 from runtimepy.primitives.base import Primitive as _Primitive
 from runtimepy.primitives.evaluation import EvalResult, evaluate
@@ -18,17 +21,21 @@ class BooleanPrimitive(_Primitive[bool]):
         """Initialize this boolean primitive."""
         super().__init__(value=value, **kwargs)
 
-    def toggle(self) -> None:
+    def randomize(self, timestamp_ns: int = None) -> None:
+        """Set this primitive to a random integer."""
+        self.set_value(bool(getrandbits(1)), timestamp_ns=timestamp_ns)
+
+    def toggle(self, timestamp_ns: int = None) -> None:
         """Toggle the underlying value."""
-        self.value = not self.raw.value
+        self.set_value(not self.raw.value, timestamp_ns=timestamp_ns)
 
-    def set(self) -> None:
+    def set(self, timestamp_ns: int = None) -> None:
         """Coerce the underlying value to true."""
-        self.value = True
+        self.set_value(True, timestamp_ns=timestamp_ns)
 
-    def clear(self) -> None:
+    def clear(self, timestamp_ns: int = None) -> None:
         """Coerce the underlying value to false."""
-        self.value = False
+        self.set_value(False, timestamp_ns=timestamp_ns)
 
     async def wait_for_state(self, state: bool, timeout: float) -> EvalResult:
         """Wait for this primitive to reach a specified state."""