runtimepy 5.6.3__py3-none-any.whl → 5.6.4__py3-none-any.whl

runtimepy/__init__.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.1.4
-# hash=9547492b6c819241db9f6c010450b6ce
+# hash=beefe82269955725f177c01474f7cea1
 # =====================================
 
 """
@@ -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.6.4"
 
 # runtimepy-specific content.
 METRICS_NAME = "metrics"

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/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/data/css/bootstrap_extra.css

@@ -42,6 +42,7 @@
 
 .table-container {
   overflow-x: scroll;
+  min-height: fit-content;
 }
 
 .channel-column {

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;

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/data/md/Connection.md

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

runtimepy/data/md/PeriodicTask.md

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

runtimepy/data/md/RuntimeStruct.md

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

runtimepy/data/md/RuntimepyPeer.md

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

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/data/schemas/ClientConnectionConfig.yaml

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

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/data/schemas/TaskConfig.yaml

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

runtimepy/data/schemas/has_markdown.yaml

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

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/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/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/mixins/logging.py

@@ -3,10 +3,15 @@ A module implementing a logger-mixin extension.
 """
 
 # built-in
+from contextlib import AsyncExitStack
+import io
 import logging
+from typing import Any, Iterable
 
 # third-party
-from vcorelib.logging import LoggerMixin
+import aiofiles
+from vcorelib.logging import LoggerMixin, LoggerType
+from vcorelib.paths import Pathlike, normalize
 
 # internal
 from runtimepy.channel.environment import ChannelEnvironment
@@ -23,6 +28,9 @@ class LogLevel(RuntimeIntEnum):
     CRITICAL = logging.CRITICAL
 
 
+LogLevellike = LogLevel | int | str
+
+
 class LoggerMixinLevelControl(LoggerMixin):
     """A logger mixin that exposes a runtime-controllable level."""
 
@@ -55,3 +63,48 @@ class LoggerMixinLevelControl(LoggerMixin):
         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/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/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.

runtimepy/net/arbiter/imports/__init__.py

@@ -8,7 +8,7 @@ from importlib import import_module as _import_module
 
 # third-party
 from vcorelib.io.types import JsonObject as _JsonObject
-from vcorelib.names import to_snake
+from vcorelib.names import import_str_and_item, to_snake
 
 # internal
 from runtimepy.net.arbiter.factory import (
@@ -23,7 +23,6 @@ from runtimepy.net.arbiter.factory.task import (
 from runtimepy.net.arbiter.info import RuntimeStruct as _RuntimeStruct
 from runtimepy.net.arbiter.task import TaskFactory as _TaskFactory
 from runtimepy.subprocess.peer import RuntimepyPeer as _RuntimepyPeer
-from runtimepy.util import import_str_and_item
 
 
 class ImportConnectionArbiter(
@@ -111,7 +110,7 @@ class ImportConnectionArbiter(
         return result
 
     def factory_process(
-        self, factory: str, name: str, config: _JsonObject, program: str
+        self, factory: str, name: str, top_level: _JsonObject
     ) -> bool:
         """Register a runtime process."""
 
@@ -121,8 +120,9 @@ class ImportConnectionArbiter(
             self._peers[name] = (
                 self._peer_factories[factory],
                 name,
-                config,
-                program,
+                top_level.get("config", {}),  # type: ignore
+                str(top_level["program"]),
+                top_level.get("markdown"),
             )
             result = True
 

runtimepy/net/arbiter/imports/util.py

@@ -5,10 +5,12 @@ Utility interfaces for arbiter runtime-import mechanisms.
 # built-in
 from importlib import import_module as _import_module
 
+# third-party
+from vcorelib.names import import_str_and_item
+
 # internal
 from runtimepy.net.arbiter.config.codec import ConfigApps
 from runtimepy.net.arbiter.info import ArbiterApps
-from runtimepy.util import import_str_and_item
 
 
 def get_apps(

runtimepy/net/connection.py

@@ -13,9 +13,11 @@ from typing import Union as _Union
 
 # third-party
 from vcorelib.asyncio import log_exceptions as _log_exceptions
+from vcorelib.io import MarkdownMixin
 from vcorelib.logging import LoggerType as _LoggerType
 
 # internal
+from runtimepy import PKG_NAME
 from runtimepy.channel.environment import ChannelEnvironment
 from runtimepy.channel.environment.command.processor import (
     ChannelCommandProcessor,
@@ -30,7 +32,9 @@ from runtimepy.primitives.byte_order import DEFAULT_BYTE_ORDER, ByteOrder
 BinaryMessage = _Union[bytes, bytearray, memoryview]
 
 
-class Connection(LoggerMixinLevelControl, ChannelEnvironmentMixin, _ABC):
+class Connection(
+    LoggerMixinLevelControl, ChannelEnvironmentMixin, MarkdownMixin, _ABC
+):
     """A connection interface."""
 
     uses_text_tx_queue = True
@@ -46,9 +50,11 @@ class Connection(LoggerMixinLevelControl, ChannelEnvironmentMixin, _ABC):
         logger: _LoggerType,
         env: ChannelEnvironment = None,
         add_metrics: bool = True,
+        markdown: str = None,
     ) -> None:
         """Initialize this connection."""
 
+        self.set_markdown(markdown=markdown, package=PKG_NAME)
         LoggerMixinLevelControl.__init__(self, logger=logger)
 
         # A queue for out-going text messages. Connections that don't use

runtimepy/net/http/common.py

@@ -9,6 +9,7 @@ from typing import Optional, TextIO, Union
 
 # third-party
 from vcorelib import DEFAULT_ENCODING
+from vcorelib.logging import LoggerType
 
 HTTPMethodlike = Union[str, http.HTTPMethod]
 HEADER_LINESEP = "\r\n"
@@ -62,6 +63,10 @@ class HeadersMixin(ABC):
     def from_lines(self, lines: list[str]) -> None:
         """Update this request from line data."""
 
+    @abstractmethod
+    def log(self, logger: LoggerType, out: bool, **kwargs) -> None:
+        """Log information about this response header."""
+
     @abstractmethod
     def __str__(self) -> str:
         """Get this response as a string."""

runtimepy/net/http/header.py

@@ -55,7 +55,11 @@ class RequestHeader(HeadersMixin):
         HeadersMixin.__init__(self, lines[1:])
 
     def log(
-        self, logger: LoggerType, out: bool, level: int = logging.DEBUG
+        self,
+        logger: LoggerType,
+        out: bool,
+        level: int = logging.DEBUG,
+        **_,
     ) -> None:
         """Log information about this request header."""
 

runtimepy/net/http/response.py

@@ -72,7 +72,7 @@ class ResponseHeader(HeadersMixin):
 
             return stream.getvalue()
 
-    def log(self, logger: LoggerType, out: bool) -> None:
+    def log(self, logger: LoggerType, out: bool, **_) -> None:
         """Log information about this response header."""
 
         level = logging.INFO if (200 <= self.status <= 299) else logging.ERROR

runtimepy/net/server/app/__init__.py

@@ -7,6 +7,9 @@ from contextlib import suppress
 from importlib import import_module as _import_module
 from typing import Any
 
+# third-party
+from vcorelib.names import import_str_and_item
+
 # internal
 from runtimepy.net.arbiter.info import AppInfo
 from runtimepy.net.server import RuntimepyServerConnection
@@ -17,7 +20,6 @@ from runtimepy.net.server.app.create import (
 )
 from runtimepy.net.server.app.landing_page import landing_page
 from runtimepy.subprocess import spawn_exec
-from runtimepy.util import import_str_and_item
 
 
 async def launch_browser(app: AppInfo) -> None:

runtimepy/net/server/app/bootstrap/elements.py

@@ -3,17 +3,19 @@ A module for creating various bootstrap-related elements.
 """
 
 # built-in
+from io import StringIO
 from typing import Optional
 
 # third-party
 from svgen.element import Element
 from svgen.element.html import div
+from vcorelib.io.file_writer import IndentedFileWriter
 
 # internal
 from runtimepy.net.server.app.bootstrap import icon_str
 
 TEXT = "font-monospace"
-BOOTSTRAP_BUTTON = f"rounded-0 {TEXT} button-bodge"
+BOOTSTRAP_BUTTON = f"rounded-0 {TEXT} button-bodge text-nowrap"
 
 
 def flex(kind: str = "row", **kwargs) -> Element:
@@ -161,3 +163,38 @@ def slider(
     #     div(tag="option", value=start + (idx * step), parent=markers)
 
     return elem
+
+
+def centered_markdown(
+    parent: Element, markdown: str, *container_classes: str
+) -> None:
+    """Add centered markdown."""
+
+    container = div(parent=parent)
+    container.add_class(
+        "flex-grow-1",
+        "d-flex",
+        "flex-column",
+        "justify-content-between",
+        *container_classes,
+    )
+
+    div(parent=container)
+
+    horiz_container = div(parent=container)
+    horiz_container.add_class("d-flex", "flex-row", "justify-content-between")
+
+    div(parent=horiz_container)
+
+    with StringIO() as stream:
+        writer = IndentedFileWriter(stream)
+        writer.write_markdown(markdown)
+        div(
+            text=stream.getvalue(),
+            parent=horiz_container,
+            class_str="text-light p-3 pb-0",
+        )
+
+    div(parent=horiz_container)
+
+    div(parent=container)