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

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-body p-3 pb-0",
+        )
+
+    div(parent=horiz_container)
+
+    div(parent=container)

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

@@ -8,8 +8,10 @@ from svgen.element.html import div
 
 # internal
 from runtimepy import PKG_NAME
+from runtimepy.net.server.app.bootstrap import icon_str
 from runtimepy.net.server.app.bootstrap.elements import (
     BOOTSTRAP_BUTTON,
+    bootstrap_button,
     collapse_button,
     flex,
     toggle_button,
@@ -85,16 +87,23 @@ class TabbedContent:
 
         # Create application container.
         self.container = div(parent=parent, id=name)
-        self.container.add_class("d-flex", "align-items-start")
+        self.container.add_class("d-flex", "align-items-start", "bg-body")
 
         # Dark theme.
         self.container["data-bs-theme"] = "dark"
-        parent.add_class("bg-dark")
 
         # Buttons.
         self.button_column = div(parent=self.container)
         self.button_column.add_class(
-            "d-flex", "flex-column", "h-100", "bg-secondary-subtle"
+            "d-flex", "flex-column", "h-100", "bg-dark-subtle"
+        )
+
+        # Dark/light theme switch button.
+        bootstrap_button(
+            icon_str("lightbulb"),
+            tooltip=" Toggle light/dark.",
+            id="theme-button",
+            parent=self.button_column,
         )
 
         # Toggle tabs button.

runtimepy/net/server/app/env/__init__.py

@@ -8,53 +8,75 @@ from svgen.element.html import div
 # internal
 from runtimepy import PKG_NAME
 from runtimepy.net.arbiter.info import AppInfo
-from runtimepy.net.server.app.bootstrap.elements import input_box
+from runtimepy.net.server.app.bootstrap.elements import (
+    centered_markdown,
+    input_box,
+)
 from runtimepy.net.server.app.bootstrap.tabs import TabbedContent
 from runtimepy.net.server.app.env.modal import Modal
 from runtimepy.net.server.app.env.settings import plot_settings
 from runtimepy.net.server.app.env.tab import ChannelEnvironmentTab
-from runtimepy.net.server.app.placeholder import dummy_tabs, under_construction
+from runtimepy.net.server.app.placeholder import dummy_tabs
 from runtimepy.net.server.app.sound import SoundTab
 
 
-def channel_environments(app: AppInfo, tabs: TabbedContent) -> None:
-    """Populate application elements."""
-
-    # Remove tab-content scrolling.
-    tabs.set_scroll(False)
-
-    # Tab name filter.
-    input_box(tabs.tabs, label="tab", description="Tab name filter.")
+def populate_tabs(app: AppInfo, tabs: TabbedContent) -> None:
+    """Populate tab contents."""
 
     # Connection tabs.
     for name, conn in app.connections.items():
         ChannelEnvironmentTab(
-            name, conn.command, app, tabs, icon="ethernet"
+            name,
+            conn.command,
+            app,
+            tabs,
+            icon="ethernet",
+            markdown=conn.markdown,
         ).entry()
 
     # Task tabs.
     for name, task in app.tasks.items():
         ChannelEnvironmentTab(
-            name, task.command, app, tabs, icon="arrow-repeat"
+            name,
+            task.command,
+            app,
+            tabs,
+            icon="arrow-repeat",
+            markdown=task.markdown,
         ).entry()
 
     # Struct tabs.
     for struct in app.structs.values():
         ChannelEnvironmentTab(
-            struct.name, struct.command, app, tabs, icon="bucket"
+            struct.name,
+            struct.command,
+            app,
+            tabs,
+            icon="bucket",
+            markdown=struct.markdown,
         ).entry()
 
     # Subprocess tabs.
     for peer in app.peers.values():
         # Host side.
         ChannelEnvironmentTab(
-            peer.struct.name, peer.struct.command, app, tabs, icon="cpu-fill"
+            peer.struct.name,
+            peer.struct.command,
+            app,
+            tabs,
+            icon="cpu-fill",
+            markdown=peer.markdown,
         ).entry()
 
         # Remote side.
         assert peer.peer is not None
         ChannelEnvironmentTab(
-            peer.peer_name, peer.peer, app, tabs, icon="cpu"
+            peer.peer_name,
+            peer.peer,
+            app,
+            tabs,
+            icon="cpu",
+            markdown=peer.struct.markdown,
         ).entry()
 
     # If we are a peer program, load environments.
@@ -69,14 +91,40 @@ def channel_environments(app: AppInfo, tabs: TabbedContent) -> None:
             app,
             tabs,
             icon="cpu-fill",
+            markdown=PROGRAM.struct.markdown,
         ).entry()
 
         # Remote side.
         assert PROGRAM.peer is not None
         ChannelEnvironmentTab(
-            PROGRAM.peer_name, PROGRAM.peer, app, tabs, icon="cpu"
+            PROGRAM.peer_name,
+            PROGRAM.peer,
+            app,
+            tabs,
+            icon="cpu",
+            markdown=PROGRAM.markdown,
         ).entry()
 
+
+def channel_environments(app: AppInfo, tabs: TabbedContent) -> None:
+    """Populate application elements."""
+
+    # Remove tab-content scrolling.
+    tabs.set_scroll(False)
+
+    # Tab name filter.
+    input_box(tabs.tabs, label="tab", description="Tab name filter.")
+
+    centered_markdown(
+        tabs.tabs,
+        app.config_param("top_markdown", "configure `top_markdown`"),
+        "border-start",
+        "border-bottom",
+        "border-end",
+    )
+
+    populate_tabs(app, tabs)
+
     # Toggle channel-table button.
     tabs.add_button(
         "Toggle channel table",
@@ -99,10 +147,16 @@ def channel_environments(app: AppInfo, tabs: TabbedContent) -> None:
         Modal(tabs)
         Modal(tabs, name="diagnostics", icon="activity")
 
-    # Placeholder for using space at the bottom of the tab list.
-    under_construction(
-        tabs.tabs, note="unused space", class_str="border-start border-end"
+    centered_markdown(
+        tabs.tabs,
+        app.config_param("bottom_markdown", "configure `bottom_markdown`"),
+        "border-start",
+        "border-end",
     )
 
     # Add splash screen element.
-    div(id=f"{PKG_NAME}-splash", parent=tabs.container)
+    div(
+        id=f"{PKG_NAME}-splash",
+        parent=tabs.container,
+        class_str="bg-success-subtle bg-gradient",
+    )

runtimepy/net/server/app/env/modal.py

@@ -32,7 +32,7 @@ class Modal:
 
         content = div(
             parent=div(
-                parent=modal, class_str="modal-dialog text-light " + TEXT
+                parent=modal, class_str="modal-dialog text-body " + TEXT
             ),
             class_str="modal-content rounded-0",
         )

runtimepy/net/server/app/env/settings.py

@@ -43,7 +43,7 @@ def plot_settings(tabs: TabbedContent) -> None:
     div(
         text="0 ms ('high', run at native refresh rate)",
         parent=container,
-        class_str="text-nowrap text-primary",
+        class_str="text-nowrap text-body-emphasis",
     )
 
     slider(
@@ -53,7 +53,7 @@ def plot_settings(tabs: TabbedContent) -> None:
     div(
         text="100 ms ('low', 10 Hz)",
         parent=container,
-        class_str="text-nowrap text-primary",
+        class_str="text-nowrap text-body-emphasis",
     )
 
     div(tag="hr", parent=modal.body)

runtimepy/net/server/app/env/tab/base.py

@@ -3,10 +3,12 @@ A module implementing a channel-environment tab HTML interface.
 """
 
 # third-party
+from vcorelib.io import MarkdownMixin
 from vcorelib.logging import LoggerMixin
 from vcorelib.math import RateLimiter
 
 # internal
+from runtimepy import PKG_NAME
 from runtimepy.channel.environment.command.processor import (
     ChannelCommandProcessor,
 )
@@ -15,7 +17,7 @@ from runtimepy.net.server.app.bootstrap.tabs import TabbedContent
 from runtimepy.net.server.app.tab import Tab
 
 
-class ChannelEnvironmentTabBase(Tab, LoggerMixin):
+class ChannelEnvironmentTabBase(Tab, LoggerMixin, MarkdownMixin):
     """A channel-environment tab interface."""
 
     def __init__(
@@ -25,10 +27,12 @@ class ChannelEnvironmentTabBase(Tab, LoggerMixin):
         app: AppInfo,
         tabs: TabbedContent,
         icon: str = "alarm",
+        markdown: str = None,
     ) -> None:
         """Initialize this instance."""
 
         self.command = command
+        self.set_markdown(markdown=markdown, package=PKG_NAME)
         super().__init__(name, app, tabs, source="env", icon=icon)
 
         # Logging.

runtimepy/net/server/app/env/tab/html.py

@@ -14,6 +14,7 @@ from runtimepy.channel import AnyChannel
 from runtimepy.enum import RuntimeEnum
 from runtimepy.net.server.app.bootstrap.elements import (
     TEXT,
+    centered_markdown,
     flex,
     input_box,
     set_tooltip,
@@ -26,7 +27,6 @@ from runtimepy.net.server.app.env.widgets import (
     channel_table_header,
     plot_checkbox,
 )
-from runtimepy.net.server.app.placeholder import under_construction
 
 
 def channel_color_button(parent: Element, name: str) -> Element:
@@ -238,7 +238,7 @@ class ChannelEnvironmentTabHtml(ChannelEnvironmentTabControls):
         logs = div(
             tag="textarea",
             parent=div(parent=vert_container, class_str="form-floating"),
-            class_str=f"form-control rounded-0 {TEXT} text-logs",
+            class_str=(f"form-control rounded-0 {TEXT} text-logs"),
             id=self.get_id("logs"),
             title=f"Text logs for {self.name}.",
         )
@@ -246,19 +246,19 @@ class ChannelEnvironmentTabHtml(ChannelEnvironmentTabControls):
 
         self.channel_table(vert_container)
 
-        # Possible empty space that could eventually be used (scenario: channel
-        # table doesn't take up full vertical space, few channels).
-        under_construction(
+        centered_markdown(
             vert_container,
-            class_str="border-start border-top border-end",
-            note="unused space",
+            self.markdown,
+            "border-start",
+            "border-top",
+            "border-end",
         )
 
         # Divider.
         div(
             id=self.get_id("divider"),
             parent=container,
-            class_str="vertical-divider border-start",
+            class_str="vertical-divider border-start bg-dark-subtle",
         )
 
         self._compose_plot(container)

runtimepy/net/server/app/placeholder.py

@@ -19,7 +19,7 @@ class DummyTab(Tab):
     def compose(self, parent: Element) -> None:
         """Compose the tab's HTML elements."""
 
-        parent.add_class("text-light")
+        parent.add_class("text-body")
 
         for idx in range(10):
             div(parent=parent, text="Hello, world! " + str(idx))

runtimepy/net/server/app/sound.py

@@ -17,7 +17,7 @@ class SoundTab(Tab):
     def compose(self, parent: Element) -> None:
         """Compose the tab's HTML elements."""
 
-        container = div(parent=parent, class_str="text-light")
+        container = div(parent=parent, class_str="text-body")
 
         div(text="Hello, world! 1", parent=container)
         div(text="Hello, world! 2", parent=container)

runtimepy/net/server/struct/__init__.py

@@ -43,8 +43,7 @@ class UiState(RuntimeStruct, PsutilMixin):
 
         # JSON-messaging interface metrics.
         self.json_metrics = ConnectionMetrics()
-        with self.env.names_pushed("json"):
-            self.register_connection_metrics(self.json_metrics)
+        self.register_connection_metrics(self.json_metrics, "json")
 
         # System metrics.
         self.use_psutil = self.config.get("psutil", True)  # type: ignore

runtimepy/net/server/websocket/state.py

@@ -7,11 +7,13 @@ from collections import defaultdict
 from dataclasses import dataclass
 import logging
 
+# third-party
+from vcorelib.logging import ListLogger
+
 # internal
 from runtimepy.channel.environment.base import ValueMap
 from runtimepy.message import JsonMessage
 from runtimepy.primitives import AnyPrimitive
-from runtimepy.util import ListLogger
 
 # (value, nanosecond timestamp)
 Point = tuple[str | int | float | bool, int]

runtimepy/net/tcp/connection.py

@@ -51,7 +51,12 @@ class TcpConnection(_Connection, _TransportMixin):
     log_alias = "TCP"
     log_prefix = ""
 
-    def __init__(self, transport: _Transport, protocol: QueueProtocol) -> None:
+    def __init__(
+        self,
+        transport: _Transport,
+        protocol: QueueProtocol,
+        **kwargs,
+    ) -> None:
         """Initialize this TCP connection."""
 
         _TransportMixin.__init__(self, transport)
@@ -60,7 +65,9 @@ class TcpConnection(_Connection, _TransportMixin):
         self._transport: _Transport = transport
         self._set_protocol(protocol)
 
-        super().__init__(_getLogger(self.logger_name(f"{self.log_alias} ")))
+        super().__init__(
+            _getLogger(self.logger_name(f"{self.log_alias} ")), **kwargs
+        )
 
         # Store connection-instantiation arguments.
         self._conn_kwargs: dict[str, _Any] = {}
@@ -121,14 +128,17 @@ class TcpConnection(_Connection, _TransportMixin):
 
     @classmethod
     async def create_connection(
-        cls: type[T], backoff: ExponentialBackoff = None, **kwargs
+        cls: type[T],
+        backoff: ExponentialBackoff = None,
+        markdown: str = None,
+        **kwargs,
     ) -> T:
         """Create a TCP connection."""
 
         transport, protocol = await tcp_transport_protocol_backoff(
             backoff=backoff, **kwargs
         )
-        inst = cls(transport, protocol)
+        inst = cls(transport, protocol, markdown=markdown)
 
         # Is there a better way to do this? We can't restart a server's side
         # of a connection (seems okay).

runtimepy/net/tcp/http/__init__.py

@@ -7,7 +7,7 @@ import asyncio
 from copy import copy
 import http
 from json import loads
-from typing import Any, Awaitable, Callable, Optional, Tuple, Union
+from typing import Any, Awaitable, Callable, Optional, Tuple, Union, cast
 
 # third-party
 from vcorelib import DEFAULT_ENCODING
@@ -174,11 +174,9 @@ class HttpConnection(_TcpConnection):
     async def process_binary(self, data: bytes) -> bool:
         """Process a binary frame."""
 
-        kind = RequestHeader if not self.expecting_response else ResponseHeader
-
-        for header, payload in self.processor.ingest(  # type: ignore
+        for header, payload in self.processor.ingest(
             data,
-            kind,  # type: ignore
+            RequestHeader if not self.expecting_response else ResponseHeader,
         ):
             header.log(self.logger, False)
 
@@ -187,11 +185,15 @@ class HttpConnection(_TcpConnection):
                 response = ResponseHeader()
                 self._send(
                     response,
-                    await self._process_request(response, header, payload),
+                    await self._process_request(
+                        response, cast(RequestHeader, header), payload
+                    ),
                 )
 
             # Process the response to a pending request.
             else:
-                await self.responses.put((header, payload))
+                await self.responses.put(
+                    (cast(ResponseHeader, header), payload)
+                )
 
         return True

runtimepy/net/udp/connection.py

@@ -44,7 +44,10 @@ class UdpConnection(_Connection, _TransportMixin):
     log_alias = "UDP"
 
     def __init__(
-        self, transport: _DatagramTransport, protocol: UdpQueueProtocol
+        self,
+        transport: _DatagramTransport,
+        protocol: UdpQueueProtocol,
+        **kwargs,
     ) -> None:
         """Initialize this UDP connection."""
 
@@ -55,7 +58,9 @@ class UdpConnection(_Connection, _TransportMixin):
         # Re-assign with updated type information.
         self._transport: _DatagramTransport = transport
 
-        super().__init__(_getLogger(self.logger_name(f"{self.log_alias} ")))
+        super().__init__(
+            _getLogger(self.logger_name(f"{self.log_alias} ")), **kwargs
+        )
         self._set_protocol(protocol)
 
         # Store connection-instantiation arguments.
@@ -127,7 +132,9 @@ class UdpConnection(_Connection, _TransportMixin):
     should_connect: bool = True
 
     @classmethod
-    async def create_connection(cls: type[T], **kwargs) -> T:
+    async def create_connection(
+        cls: type[T], markdown: str = None, **kwargs
+    ) -> T:
         """Create a UDP connection."""
 
         LOG.debug("kwargs: %s", kwargs)
@@ -151,7 +158,7 @@ class UdpConnection(_Connection, _TransportMixin):
 
         # Create the underlying connection.
         transport, protocol = await udp_transport_protocol_backoff(**kwargs)
-        conn = cls(transport, protocol)
+        conn = cls(transport, protocol, markdown=markdown)
         conn._conn_kwargs = {**kwargs}
 
         # Set the remote address manually if necessary.

runtimepy/net/udp/tftp/__init__.py

@@ -11,7 +11,7 @@ from typing import Any, AsyncIterator
 
 # third-party
 from vcorelib.asyncio.poll import repeat_until
-from vcorelib.paths.context import tempfile
+from vcorelib.paths.context import PossiblePath, as_path, tempfile
 from vcorelib.paths.hashing import file_md5_hex
 from vcorelib.paths.info import FileInfo
 
@@ -25,7 +25,6 @@ from runtimepy.net.udp.tftp.base import (
 )
 from runtimepy.net.udp.tftp.enums import DEFAULT_MODE
 from runtimepy.net.util import IpHostTuplelike
-from runtimepy.util import PossiblePath, as_path
 
 
 class TftpConnection(BaseTftpConnection):

runtimepy/net/websocket/connection.py

@@ -51,11 +51,12 @@ class WebsocketConnection(Connection):
     def __init__(
         self,
         protocol: _Union[_WebSocketClientProtocol, _WebSocketServerProtocol],
+        **kwargs,
     ) -> None:
         """Initialize this connection."""
 
         self.protocol = protocol
-        super().__init__(self.protocol.logger)
+        super().__init__(self.protocol.logger, **kwargs)
 
     async def _handle_connection_closed(
         self, task: _Awaitable[V]
@@ -92,7 +93,9 @@ class WebsocketConnection(Connection):
         await self.protocol.close()
 
     @classmethod
-    async def create_connection(cls: type[T], uri: str, **kwargs) -> T:
+    async def create_connection(
+        cls: type[T], uri: str, markdown: str = None, **kwargs
+    ) -> T:
         """Connect a client to an endpoint."""
 
         kwargs.setdefault("use_ssl", uri.startswith("wss"))
@@ -100,11 +103,13 @@ class WebsocketConnection(Connection):
         protocol = await getattr(websockets, "connect")(
             uri, **handle_possible_ssl(**kwargs)
         )
-        return cls(protocol)
+        return cls(protocol, markdown=markdown)
 
     @classmethod
     @_asynccontextmanager
-    async def client(cls: type[T], uri: str, **kwargs) -> _AsyncIterator[T]:
+    async def client(
+        cls: type[T], uri: str, markdown: str = None, **kwargs
+    ) -> _AsyncIterator[T]:
         """A wrapper for connecting a client."""
 
         kwargs.setdefault("use_ssl", uri.startswith("wss"))
@@ -112,7 +117,7 @@ class WebsocketConnection(Connection):
         async with getattr(websockets, "connect")(
             uri, **handle_possible_ssl(**kwargs)
         ) as protocol:
-            yield cls(protocol)
+            yield cls(protocol, markdown=markdown)
 
     @classmethod
     def server_handler(

runtimepy/requirements.txt

@@ -1,4 +1,5 @@
-vcorelib>=3.3.1
+aiofiles
+vcorelib>=3.4.2
 svgen>=0.6.8
 websockets
 psutil

runtimepy/struct/__init__.py

@@ -6,9 +6,11 @@ A module implementing a runtime structure base.
 from logging import getLogger as _getLogger
 
 # third-party
+from vcorelib.io import MarkdownMixin
 from vcorelib.io.types import JsonObject as _JsonObject
 
 # internal
+from runtimepy import PKG_NAME
 from runtimepy.channel.environment.command.processor import (
     ChannelCommandProcessor,
 )
@@ -16,15 +18,23 @@ from runtimepy.mixins.environment import ChannelEnvironmentMixin
 from runtimepy.mixins.logging import LoggerMixinLevelControl
 
 
-class RuntimeStructBase(LoggerMixinLevelControl, ChannelEnvironmentMixin):
+class RuntimeStructBase(
+    LoggerMixinLevelControl, ChannelEnvironmentMixin, MarkdownMixin
+):
     """A base runtime structure."""
 
     log_level_channel: bool = True
 
-    def __init__(self, name: str, config: _JsonObject) -> None:
+    # Unclear why this is/was necessary (mypy bug?)
+    markdown: str
+
+    def __init__(
+        self, name: str, config: _JsonObject, markdown: str = None
+    ) -> None:
         """Initialize this instance."""
 
         self.name = name
+        self.set_markdown(config=config, markdown=markdown, package=PKG_NAME)
         LoggerMixinLevelControl.__init__(self, logger=_getLogger(self.name))
         ChannelEnvironmentMixin.__init__(self)
         if self.log_level_channel: