runtimepy 5.6.3__tar.gz → 5.7.0__tar.gz

{runtimepy-5.6.3/runtimepy.egg-info → runtimepy-5.7.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: runtimepy
-Version: 5.6.3
+Version: 5.7.0
 Summary: A framework for implementing Python services.
 Home-page: https://github.com/vkottler/runtimepy
 Author: Vaughn Kottler
-Author-email: Vaughn Kottler <vaughnkottler@gmail.com>
-Maintainer-email: Vaughn Kottler <vaughnkottler@gmail.com>
+Author-email: Vaughn Kottler <vaughn@libre-embedded.com>
+Maintainer-email: Vaughn Kottler <vaughn@libre-embedded.com>
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: Microsoft :: Windows
@@ -17,10 +17,11 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: vcorelib>=3.3.1
+Requires-Dist: vcorelib>=3.4.2
 Requires-Dist: svgen>=0.6.8
-Requires-Dist: psutil
 Requires-Dist: websockets
+Requires-Dist: aiofiles
+Requires-Dist: psutil
 Provides-Extra: test
 Requires-Dist: pylint; extra == "test"
 Requires-Dist: flake8; extra == "test"
@@ -44,11 +45,11 @@ Requires-Dist: uvloop; (sys_platform != "win32" and sys_platform != "cygwin") an
     =====================================
     generator=datazen
     version=3.1.4
-    hash=ac4d0a4097094aeb4e3f43c5f1128115
+    hash=aa59dcef7f11c767458b14ad97f9de59
     =====================================
 -->
 
-# runtimepy ([5.6.3](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.7.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.6.3 → runtimepy-5.7.0}/README.md

@@ -2,11 +2,11 @@
     =====================================
     generator=datazen
     version=3.1.4
-    hash=ac4d0a4097094aeb4e3f43c5f1128115
+    hash=aa59dcef7f11c767458b14ad97f9de59
     =====================================
 -->
 
-# runtimepy ([5.6.3](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.7.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.6.3 → runtimepy-5.7.0}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta:__legacy__"
 
 [project]
 name = "runtimepy"
-version = "5.6.3"
+version = "5.7.0"
 description = "A framework for implementing Python services."
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [
-  {name = "Vaughn Kottler", email = "vaughnkottler@gmail.com"}
+  {name = "Vaughn Kottler", email = "vaughn@libre-embedded.com"}
 ]
 maintainers = [
-  {name = "Vaughn Kottler", email = "vaughnkottler@gmail.com"}
+  {name = "Vaughn Kottler", email = "vaughn@libre-embedded.com"}
 ]
 classifiers = [
   "Programming Language :: Python :: 3.11",

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/__init__.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.1.4
-# hash=9547492b6c819241db9f6c010450b6ce
+# hash=c51f4ac6cf134b3c3fa872a096e83489
 # =====================================
 
 """
@@ -10,7 +10,7 @@ Useful defaults and other package metadata.
 
 DESCRIPTION = "A framework for implementing Python services."
 PKG_NAME = "runtimepy"
-VERSION = "5.6.3"
+VERSION = "5.7.0"
 
 # runtimepy-specific content.
 METRICS_NAME = "metrics"

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/channel/environment/command/__init__.py

@@ -15,6 +15,7 @@ from vcorelib import DEFAULT_ENCODING
 from vcorelib.io import ARBITER, JsonObject
 from vcorelib.logging import DEFAULT_TIME_FORMAT, LoggerMixin
 from vcorelib.math import default_time_ns, nano_str
+from vcorelib.names import name_search
 
 # internal
 from runtimepy.channel.environment import ChannelEnvironment
@@ -26,7 +27,6 @@ from runtimepy.channel.environment.command.processor import (
 )
 from runtimepy.channel.registry import ParsedEvent
 from runtimepy.mapping import DEFAULT_PATTERN
-from runtimepy.util import name_search
 
 # Declared so we re-export FieldOrChannel after moving where it's declared.
 __all__ = [

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/channel/environment/telemetry.py

@@ -6,6 +6,9 @@ A module implementing channel-environment telemetry registration.
 from contextlib import ExitStack, contextmanager
 from typing import BinaryIO, Iterator, Optional, cast
 
+# third-party
+from vcorelib.names import name_search
+
 # internal
 from runtimepy.channel.environment.base import (
     BaseChannelEnvironment as _BaseChannelEnvironment,
@@ -14,7 +17,6 @@ from runtimepy.channel.event import PrimitiveEvent
 from runtimepy.channel.registry import ParsedEvent
 from runtimepy.mapping import DEFAULT_PATTERN
 from runtimepy.metrics.channel import ChannelMetrics
-from runtimepy.util import name_search
 
 
 class TelemetryChannelEnvironment(_BaseChannelEnvironment):

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/css/bootstrap_extra.css

@@ -42,6 +42,7 @@
 
 .table-container {
   overflow-x: scroll;
+  min-height: fit-content;
 }
 
 .channel-column {
@@ -76,19 +77,17 @@ textarea.text-logs {
   padding-bottom: 0 !important;
 
   border-top: 0;
-  background-color: var(--bs-secondary-bg-subtle);
 }
 
 .vertical-divider {
   flex-basis: 0.75em;
   flex-grow: 0;
   flex-shrink: 0;
-  background-color: var(--bs-secondary-bg-subtle);
 }
 
 .vertical-divider:hover {
   cursor: col-resize;
-  background-color: var(--bs-secondary-bg);
+  background-color: var(--bs-highlight-bg) !important;
 }
 
 button:hover {
@@ -98,3 +97,14 @@ button:hover {
 .channel-value-input {
   width: 6em;
 }
+
+/*
+ * Should probably build the bootstrap stuff from source and set custom Sass:
+ * https://getbootstrap.com/docs/5.3/customize/sass/
+ */
+
+:root {
+  /* Prefer 'Arial' and 'Consolas' at the highest priority. */
+  --bs-font-sans-serif: Arial, "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+  --bs-font-monospace: Consolas, "Liberation Mono", "Courier New", monospace;
+}

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/css/main.css

@@ -17,6 +17,10 @@ body > :first-child {
   height: 100%;
 }
 
+#runtimepy-tabs {
+  width: min-content;
+}
+
 #runtimepy-splash {
   position: fixed;
   top: 0;
@@ -24,7 +28,6 @@ body > :first-child {
   width: 100vw;
   height: 100vh;
   opacity: 1.0;
-  background-color: var(--bs-secondary-bg-subtle);
 }
 
 .click-plot {

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/dummy_load.yaml

@@ -9,7 +9,19 @@ tasks:
   # Sinusoids.
   - {name: wave1, factory: sinusoid, period_s: 0.01}
   - {name: wave2, factory: sinusoid, period_s: 0.02}
-  - {name: wave3, factory: sinusoid, period_s: 0.03}
+  - name: wave3
+    factory: sinusoid
+    period_s: 0.03
+    markdown: |
+      # Markdown for wave3
+
+      * list element 1
+      * list element 2
+      * list element 3
+
+      To be continued.
+
+      `peace`
 
   # Drive interactions with runtime entities that won't otherwise be polled.
   - {name: app, factory: SampleApp, period_s: 0.25}
@@ -21,6 +33,11 @@ clients:
     defer: true
     kwargs:
       remote_addr: [localhost, "$udp_json"]
+    markdown: |
+      # `udp_json_client`
+
+      Connects to `udp_json_server`.
+
   - factory: udp_json
     name: udp_json_server
     kwargs:
@@ -36,8 +53,19 @@ structs:
       b: 2
       c: 3
 
+      markdown: |
+        # Docs for `example.struct1`
+
+        Should be shown for peer process as well?
+
   - name: struct2
     factory: sample_struct
+    config:
+      markdown: |
+        # `struct2`
+
+        One of the structs of all time.
+
   - name: struct3
     factory: sample_struct
 
@@ -46,6 +74,11 @@ processes:
   - name: proc1
     factory: sample_peer
 
+    markdown: |
+      # Markdown for `proc1`
+
+      A process that
+
     # The peer itself runs an arbiter process.
     config:
       includes:

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/js/classes/WindowHashManager.js

@@ -7,6 +7,7 @@ class WindowHashManager {
     this.tabFilter = "";
     this.tabsShown = true;
     this.channelsShown = true;
+    this.lightMode = false;
     this.plotChannels = {};
     this.filters = {};
     this.minTxPeriod = 0.0;
@@ -17,6 +18,15 @@ class WindowHashManager {
     this.update();
   }
 
+  lightDarkClick(event) {
+    this.lightMode = !this.lightMode;
+
+    document.getElementById("runtimepy")
+        .setAttribute("data-bs-theme", this.lightMode ? "light" : "dark");
+
+    this.update();
+  }
+
   channelClick(event) {
     this.channelsShown = !this.channelsShown;
 
@@ -106,6 +116,12 @@ class WindowHashManager {
       channelsButton.addEventListener("click", this.channelClick.bind(this));
     }
 
+    /* Click handler for light/dark toggle. */
+    let lightDarkButton = document.getElementById("theme-button");
+    if (lightDarkButton) {
+      lightDarkButton.addEventListener("click", this.lightDarkClick.bind(this));
+    }
+
     /* Click handlers for new window buttons. */
     for (const button of document.querySelectorAll(".window-button")) {
       button.onclick = () => {
@@ -150,13 +166,6 @@ class WindowHashManager {
         }
       }
 
-      if (split.includes("hide-tabs")) {
-        tabButton.click();
-      }
-      if (split.includes("hide-channels")) {
-        channelsButton.click();
-      }
-
       /* Check for tab filter. */
       for (let item of split) {
         if (item.includes("=")) {
@@ -171,6 +180,16 @@ class WindowHashManager {
           }
         }
       }
+
+      if (split.includes("hide-tabs")) {
+        tabButton.click();
+      }
+      if (split.includes("hide-channels")) {
+        channelsButton.click();
+      }
+      if (split.includes("light-mode")) {
+        lightDarkButton.click();
+      }
     }
   }
 
@@ -199,6 +218,9 @@ class WindowHashManager {
     if (!this.channelsShown) {
       hash += ",hide-channels"
     }
+    if (this.lightMode) {
+      hash += ",light-mode";
+    }
 
     if (this.minTxPeriod != 0.0) {
       hash += `,min-tx-period-ms=${this.minTxPeriod}`;

runtimepy-5.7.0/runtimepy/data/md/Connection.md

@@ -0,0 +1,3 @@
+# Connections
+
+To be continued.

runtimepy-5.7.0/runtimepy/data/md/PeriodicTask.md

@@ -0,0 +1,3 @@
+# Periodic Tasks
+
+To be continued.

runtimepy-5.7.0/runtimepy/data/md/RuntimeStruct.md

@@ -0,0 +1,3 @@
+# Runtime Structures
+
+To be continued.

runtimepy-5.7.0/runtimepy/data/md/RuntimepyPeer.md

@@ -0,0 +1,3 @@
+# Peer Programs
+
+To be continued.

runtimepy-5.7.0/runtimepy/data/md/SinusoidTask.md

@@ -0,0 +1,20 @@
+# Sinusoid Tasks
+
+## Intent
+
+These tasks compute
+[`math.sin`](https://docs.python.org/3/library/math.html#math.sin) and
+[`math.cos`](https://docs.python.org/3/library/math.html#math.cos) on every
+iteration, which advances one "step" per dispatch where the "step angle"
+advanced depends on the `steps` control.
+
+Once the current "step angle" is computed, controls `amplitude` and phase
+angles are considered for final `sin` and `cos` channel values.
+
+## Discussion
+
+* Is it worth adding a `tan` channel that computes
+[`math.tan`](https://docs.python.org/3/library/math.html#math.tan) and/or other
+trigonometric functions?
+* Is it worth adding a "number of steps" control, such that one task iteration
+could advance multiple waveform steps?

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/schemas/ClientConnectionConfig.yaml

@@ -2,6 +2,7 @@
 includes:
   - has_factory.yaml
   - has_name.yaml
+  - has_markdown.yaml
 
 properties:
   defer:

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/schemas/PeerProcessConfig.yaml

@@ -3,6 +3,7 @@ includes:
   - has_factory.yaml
   - has_name.yaml
   - has_config.yaml
+  - has_markdown.yaml
 
 required: [program]
 

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/data/schemas/TaskConfig.yaml

@@ -2,6 +2,7 @@
 includes:
   - has_factory.yaml
   - has_name.yaml
+  - has_markdown.yaml
 
 properties:
   period_s:

runtimepy-5.7.0/runtimepy/data/schemas/has_markdown.yaml

@@ -0,0 +1,4 @@
+---
+properties:
+  markdown:
+    type: string

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/mapping.py

@@ -13,10 +13,10 @@ from typing import cast as _cast
 
 # third-party
 from vcorelib.logging import LoggerMixin
+from vcorelib.names import name_search
 
 # internal
 from runtimepy.mixins.regex import RegexMixin as _RegexMixin
-from runtimepy.util import name_search
 
 # This determines types that are valid as keys.
 T = _TypeVar("T", int, bool)

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/message/interface.py

@@ -11,7 +11,7 @@ from typing import Any, Optional, Union
 
 # third-party
 from vcorelib.dict.codec import JsonCodec
-from vcorelib.logging import LoggerType
+from vcorelib.logging import ListLogger, LoggerType
 from vcorelib.target.resolver import TargetResolver
 
 # internal
@@ -39,7 +39,7 @@ from runtimepy.message.types import (
     T,
     TypedHandler,
 )
-from runtimepy.util import Identifier, ListLogger
+from runtimepy.util import Identifier
 
 
 class JsonMessageInterface:

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/mixins/environment.py

@@ -30,11 +30,14 @@ class ChannelEnvironmentMixin:
         return id(self.env)
 
     def register_task_metrics(
-        self, metrics: PeriodicTaskMetrics, namespace: str = METRICS_NAME
+        self,
+        metrics: PeriodicTaskMetrics,
+        *names: str,
+        namespace: str = METRICS_NAME,
     ) -> None:
         """Register periodic task metrics."""
 
-        with self.env.names_pushed(namespace):
+        with self.env.names_pushed(namespace, *names):
             self.env.channel(
                 "dispatches",
                 metrics.dispatches,
@@ -104,11 +107,14 @@ class ChannelEnvironmentMixin:
             )
 
     def register_connection_metrics(
-        self, metrics: ConnectionMetrics, namespace: str = METRICS_NAME
+        self,
+        metrics: ConnectionMetrics,
+        *names: str,
+        namespace: str = METRICS_NAME,
     ) -> None:
         """Register connection metrics."""
 
-        with self.env.names_pushed(namespace):
+        with self.env.names_pushed(namespace, *names):
             for name, direction, verb in [
                 ("tx", metrics.tx, "transmitted"),
                 ("rx", metrics.rx, "received"),

runtimepy-5.7.0/runtimepy/mixins/logging.py

@@ -0,0 +1,110 @@
+"""
+A module implementing a logger-mixin extension.
+"""
+
+# built-in
+from contextlib import AsyncExitStack
+import io
+import logging
+from typing import Any, Iterable
+
+# third-party
+import aiofiles
+from vcorelib.logging import LoggerMixin, LoggerType
+from vcorelib.paths import Pathlike, normalize
+
+# internal
+from runtimepy.channel.environment import ChannelEnvironment
+from runtimepy.enum.registry import RuntimeIntEnum
+
+
+class LogLevel(RuntimeIntEnum):
+    """A runtime enumeration for log level."""
+
+    DEBUG = logging.DEBUG
+    INFO = logging.INFO
+    WARNING = logging.WARNING
+    ERROR = logging.ERROR
+    CRITICAL = logging.CRITICAL
+
+
+LogLevellike = LogLevel | int | str
+
+
+class LoggerMixinLevelControl(LoggerMixin):
+    """A logger mixin that exposes a runtime-controllable level."""
+
+    def _log_level_changed(self, _: int, new_value: int) -> None:
+        """Handle a change in log level."""
+
+        self.logger.setLevel(new_value)
+        self.logger.log(new_value, "Log level updated to %d.", new_value)
+
+    def setup_level_channel(
+        self,
+        env: ChannelEnvironment,
+        name: str = "log_level",
+        initial: str = "info",
+        description: str = "Text-log level filter for this environment.",
+    ) -> None:
+        """Add a commandable log-level channel to the environment."""
+
+        chan = env.int_channel(
+            name,
+            enum=LogLevel.register_enum(env.enums),
+            commandable=True,
+            description=description,
+        )
+
+        # Set up change handler.
+        chan[0].raw.register_callback(self._log_level_changed)
+
+        # Set the initial log level.
+        env.set(name, initial)
+
+        del chan
+
+
+LogPaths = Iterable[tuple[LogLevellike, Pathlike]]
+
+
+class LogCaptureMixin:
+    """A simple async file-reading interface."""
+
+    logger: LoggerType
+
+    # Open aiofiles handles.
+    streams: list[tuple[int, Any]]
+
+    ext_log_extra = {"external": True}
+
+    async def init_log_capture(
+        self, stack: AsyncExitStack, log_paths: LogPaths
+    ) -> None:
+        """Initialize this task with application information."""
+
+        self.streams = [
+            (
+                LogLevel.normalize(level),
+                await stack.enter_async_context(aiofiles.open(path, mode="r")),
+            )
+            for level, path in log_paths
+            if normalize(path).is_file()
+        ]
+
+        # Don't handle any kind of backhaul.
+        for stream in self.streams:
+            await stream[1].seek(0, io.SEEK_END)
+
+    def log_line(self, level: int, data: str) -> None:
+        """Log a line for output."""
+        self.logger.log(level, data, extra=self.ext_log_extra)
+
+    async def dispatch_log_capture(self) -> None:
+        """Get the next line from this log stream."""
+
+        for level, stream in self.streams:
+            line = (await stream.readline()).rstrip()
+            while line:
+                self.log_line(level, line)
+                line = (await stream.readline()).rstrip()

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/net/arbiter/base.py

@@ -48,7 +48,9 @@ from runtimepy.subprocess.peer import RuntimepyPeer as _RuntimepyPeer
 from runtimepy.tui.mixin import CursesWindow, TuiMixin
 
 ServerTask = _Awaitable[None]
-RuntimeProcessTask = tuple[type[_RuntimepyPeer], str, _JsonObject, str]
+RuntimeProcessTask = tuple[
+    type[_RuntimepyPeer], str, _JsonObject, str, Optional[str]
+]
 
 
 async def init_only(app: AppInfo) -> int:
@@ -226,9 +228,17 @@ class BaseConnectionArbiter(_NamespaceMixin, _LoggerMixin, TuiMixin):
     async def _start_processes(self, stack: _AsyncExitStack) -> None:
         """Start processes."""
 
-        for name, (peer, name, config, import_str) in self._peers.items():
+        for name, (
+            peer,
+            name,
+            config,
+            import_str,
+            markdown,
+        ) in self._peers.items():
             self._runtime_peers[name] = await stack.enter_async_context(
-                peer.running_program(name, config, import_str)
+                peer.running_program(
+                    name, config, import_str, markdown=markdown
+                )
             )
             self.logger.info("Started process '%s'.", name)
 

{runtimepy-5.6.3 → runtimepy-5.7.0}/runtimepy/net/arbiter/config/__init__.py

@@ -17,6 +17,7 @@ from vcorelib.dict.env import dict_resolve_env_vars, list_resolve_env_vars
 from vcorelib.io import ARBITER as _ARBITER
 from vcorelib.io.types import JsonObject as _JsonObject
 from vcorelib.logging import LoggerMixin as _LoggerMixin
+from vcorelib.names import import_str_and_item
 from vcorelib.paths import Pathlike as _Pathlike
 from vcorelib.paths import find_file
 from vcorelib.paths import normalize as _normalize
@@ -29,7 +30,6 @@ from runtimepy.net.arbiter.imports import (
     ImportConnectionArbiter as _ImportConnectionArbiter,
 )
 from runtimepy.net.arbiter.imports.util import get_apps
-from runtimepy.util import import_str_and_item
 
 ConfigObject = dict[str, _Any]
 ConfigBuilder = _Callable[[ConfigObject], None]
@@ -168,6 +168,7 @@ class ConfigConnectionArbiter(_ImportConnectionArbiter):
             kwargs = dict_resolve_env_vars(
                 client.get("kwargs", {}), env=config.ports  # type: ignore
             )
+            kwargs.setdefault("markdown", client.get("markdown"))
 
             assert await self.factory_client(
                 factory,
@@ -201,6 +202,7 @@ class ConfigConnectionArbiter(_ImportConnectionArbiter):
                 name,
                 period_s=task["period_s"],
                 average_depth=task["average_depth"],
+                markdown=task.get("markdown"),
             ), f"Couldn't register task '{name}' ({factory})!"
 
         # Register structs.
@@ -216,7 +218,9 @@ class ConfigConnectionArbiter(_ImportConnectionArbiter):
             name = process["name"]
             factory = process["factory"]
             assert self.factory_process(
-                factory, name, process.get("config", {}), process["program"]
+                factory,
+                name,
+                process,
             ), f"Couldn't register process '{name}' ({factory})!"
 
         # Load initialization methods.