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

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,9 +147,11 @@ 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.

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:
@@ -246,12 +246,12 @@ 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.

runtimepy/net/server/app/files.py

@@ -77,12 +77,16 @@ def set_text_to_kind(
 WORKER_TYPE = "text/js-worker"
 
 
-def handle_worker(writer: IndentedFileWriter) -> bool:
+def handle_worker(writer: IndentedFileWriter) -> int:
     """Boilerplate contents for worker thread block."""
 
-    return write_found_file(
-        writer, kind_url("js", "webgl-debug", subdir="third-party")
-    )
+    # Not currently used.
+    # return write_found_file(
+    #     writer, kind_url("js", "webgl-debug", subdir="third-party")
+    # )
+    del writer
+
+    return 0
 
 
 def append_kind(
@@ -107,8 +111,8 @@ def append_kind(
             ):
                 found_count += 1
 
-        if worker and handle_worker(writer):
-            found_count += 1
+        if worker:
+            found_count += handle_worker(writer)
 
         if found_count:
             elem.text = stream.getvalue()

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.1
 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:

runtimepy/subprocess/interface.py

@@ -12,11 +12,12 @@ from logging import INFO, getLogger
 from typing import Optional
 
 # third-party
+from vcorelib.io import MarkdownMixin
 from vcorelib.io.types import JsonObject
 from vcorelib.math import RateLimiter
 
 # internal
-from runtimepy import METRICS_NAME
+from runtimepy import METRICS_NAME, PKG_NAME
 from runtimepy.channel.environment import ChannelEnvironment
 from runtimepy.channel.environment.base import FieldOrChannel
 from runtimepy.channel.environment.command import register_env
@@ -34,7 +35,7 @@ PEER_SUFFIX = ".peer"
 
 
 class RuntimepyPeerInterface(
-    JsonMessageInterface, AsyncCommandProcessingMixin
+    JsonMessageInterface, AsyncCommandProcessingMixin, MarkdownMixin
 ):
     """A class implementing an interface for messaging peer subprocesses."""
 
@@ -42,13 +43,25 @@ class RuntimepyPeerInterface(
 
     struct_type: type[RuntimeStruct] = SampleStruct
 
-    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.set_markdown(markdown=markdown, package=PKG_NAME)
+
         self.processor = MessageProcessor()
 
         self.basename = name
-        self.struct = self.struct_type(self.basename + HOST_SUFFIX, config)
+
+        self.struct = self.struct_type(
+            self.basename + HOST_SUFFIX,
+            config,
+            markdown=config.get("config", {}).get("markdown"),  # type: ignore
+        )
 
         self.peer: Optional[RemoteCommandProcessor] = None
         self.peer_config: Optional[JsonMessage] = None

runtimepy/subprocess/peer.py

@@ -19,13 +19,13 @@ from typing import AsyncIterator, Iterator, Type, TypeVar
 from vcorelib.io import ARBITER, DEFAULT_INCLUDES_KEY
 from vcorelib.io.file_writer import IndentedFileWriter
 from vcorelib.io.types import JsonObject
+from vcorelib.names import import_str_and_item
 from vcorelib.paths.context import tempfile
 
 # internal
 from runtimepy.subprocess import spawn_exec, spawn_shell
 from runtimepy.subprocess.interface import RuntimepyPeerInterface
 from runtimepy.subprocess.protocol import RuntimepySubprocessProtocol
-from runtimepy.util import import_str_and_item
 
 T = TypeVar("T", bound="RuntimepyPeer")
 
@@ -38,10 +38,11 @@ class RuntimepyPeer(RuntimepyPeerInterface):
         protocol: RuntimepySubprocessProtocol,
         name: str,
         config: JsonObject,
+        markdown: str = None,
     ) -> None:
         """Initialize this instance."""
 
-        super().__init__(name, config)
+        super().__init__(name, config, markdown=markdown)
         self.protocol = protocol
 
         # Offset message identifiers.
@@ -89,14 +90,20 @@ class RuntimepyPeer(RuntimepyPeerInterface):
     @classmethod
     @asynccontextmanager
     async def shell(
-        cls: Type[T], name: str, config: JsonObject, cmd: str
+        cls: Type[T],
+        name: str,
+        config: JsonObject,
+        cmd: str,
+        markdown: str = None,
     ) -> AsyncIterator[T]:
         """Create an instance from a shell command."""
 
         async with spawn_shell(
             cmd, stdout=asyncio.Queue(), stderr=asyncio.Queue()
         ) as proto:
-            async with cls(proto, name, config)._context() as inst:
+            async with cls(
+                proto, name, config, markdown=markdown
+            )._context() as inst:
                 yield inst
 
     async def main(self) -> None:
@@ -105,14 +112,21 @@ class RuntimepyPeer(RuntimepyPeerInterface):
     @classmethod
     @asynccontextmanager
     async def exec(
-        cls: Type[T], name: str, config: JsonObject, *args, **kwargs
+        cls: Type[T],
+        name: str,
+        config: JsonObject,
+        *args,
+        markdown: str = None,
+        **kwargs,
     ) -> AsyncIterator[T]:
         """Create an instance from comand-line arguments."""
 
         async with spawn_exec(
             *args, stdout=asyncio.Queue(), stderr=asyncio.Queue(), **kwargs
         ) as proto:
-            async with cls(proto, name, config)._context() as inst:
+            async with cls(
+                proto, name, config, markdown=markdown
+            )._context() as inst:
                 yield inst
 
     @classmethod

runtimepy/task/basic/periodic.py

@@ -13,12 +13,14 @@ from logging import getLogger as _getLogger
 from typing import Optional as _Optional
 
 # third-party
+from vcorelib.io import MarkdownMixin
 from vcorelib.math import DEFAULT_DEPTH as _DEFAULT_DEPTH
 from vcorelib.math import MovingAverage as _MovingAverage
 from vcorelib.math import RateTracker as _RateTracker
 from vcorelib.math import rate_str as _rate_str
 
 # internal
+from runtimepy import PKG_NAME
 from runtimepy.channel.environment import ChannelEnvironment
 from runtimepy.channel.environment.command.processor import (
     ChannelCommandProcessor,
@@ -32,7 +34,9 @@ from runtimepy.primitives import Float as _Float
 from runtimepy.ui.controls import Controlslike
 
 
-class PeriodicTask(LoggerMixinLevelControl, ChannelEnvironmentMixin, _ABC):
+class PeriodicTask(
+    LoggerMixinLevelControl, ChannelEnvironmentMixin, MarkdownMixin, _ABC
+):
     """A class implementing a simple periodic-task interface."""
 
     auto_finalize = True
@@ -45,10 +49,12 @@ class PeriodicTask(LoggerMixinLevelControl, ChannelEnvironmentMixin, _ABC):
         period_s: float = 1.0,
         env: ChannelEnvironment = None,
         period_controls: Controlslike = "period",
+        markdown: str = None,
     ) -> None:
         """Initialize this task."""
 
         self.name = name
+        self.set_markdown(markdown=markdown, package=PKG_NAME)
         LoggerMixinLevelControl.__init__(self, logger=_getLogger(self.name))
         self._task: _Optional[_asyncio.Task[None]] = None