runtimepy 5.15.7__tar.gz → 5.16.0__tar.gz

{runtimepy-5.15.7/runtimepy.egg-info → runtimepy-5.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtimepy
-Version: 5.15.7
+Version: 5.16.0
 Summary: A framework for implementing Python services.
 Home-page: https://github.com/libre-embedded/runtimepy
 Author: Libre Embedded
@@ -17,11 +17,11 @@ Classifier: Development Status :: 5 - Production/Stable
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: websockets
 Requires-Dist: svgen>=0.8.0
-Requires-Dist: vcorelib>=3.6.4
 Requires-Dist: aiofiles
+Requires-Dist: vcorelib>=3.6.4
 Requires-Dist: psutil
+Requires-Dist: websockets
 Provides-Extra: test
 Requires-Dist: pylint; extra == "test"
 Requires-Dist: flake8; extra == "test"
@@ -51,11 +51,11 @@ Dynamic: requires-python
     =====================================
     generator=datazen
     version=3.2.3
-    hash=fd0b9f87927033d8ee2eb5448d8aec76
+    hash=ebb0bba9899d4baf7ce73b082f5e384e
     =====================================
 -->
 
-# runtimepy ([5.15.7](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.16.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/libre-embedded/runtimepy/workflows/Python%20Package/badge.svg)
@@ -89,7 +89,7 @@ This package is tested on the following platforms:
 # Command-line Options
 
 ```
-$ ./venv3.12/bin/runtimepy -h
+$ ./venv3.13/bin/runtimepy -h
 
 usage: runtimepy [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]
                  {arbiter,mtu,server,task,tftp,tui,noop} ...
@@ -103,7 +103,7 @@ options:
   -q, --quiet           set to reduce output
   --curses              whether or not to use curses.wrapper when starting
   --no-uvloop           whether or not to disable uvloop as event loop driver
-  -C DIR, --dir DIR     execute from a specific directory
+  -C, --dir DIR         execute from a specific directory
 
 commands:
   {arbiter,mtu,server,task,tftp,tui,noop}
@@ -123,7 +123,7 @@ commands:
 ### `arbiter`
 
 ```
-$ ./venv3.12/bin/runtimepy arbiter -h
+$ ./venv3.13/bin/runtimepy arbiter -h
 
 usage: runtimepy arbiter [-h] [-i] [-w] [--no-poller] configs [configs ...]
 
@@ -144,7 +144,7 @@ options:
 ### `mtu`
 
 ```
-$ ./venv3.12/bin/runtimepy mtu -h
+$ ./venv3.13/bin/runtimepy mtu -h
 
 usage: runtimepy mtu [-h] [--probe-size PROBE_SIZE] [--fallback FALLBACK] [-t]
                      destination [destination ...]
@@ -165,7 +165,7 @@ options:
 ### `server`
 
 ```
-$ ./venv3.12/bin/runtimepy server -h
+$ ./venv3.13/bin/runtimepy server -h
 
 usage: runtimepy server [-h] [-i] [-w] [--no-poller] [--cafile CAFILE]
                         [--capath CAPATH] [--cadata CADATA]
@@ -191,7 +191,7 @@ options:
   --certfile CERTFILE   passed directly to instantiation
   --keyfile KEYFILE     passed directly to instantiation
   --host HOST           host address to listen on (default: '0.0.0.0')
-  -p PORT, --port PORT  port to listen on (default: 0)
+  -p, --port PORT       port to listen on (default: 0)
   -u, --udp             whether or not this is a UDP-based server (otherwise
                         it must be a TCP-based server)
   -l, --loopback        if true a client of the same connection type is added
@@ -201,7 +201,7 @@ options:
 ### `task`
 
 ```
-$ ./venv3.12/bin/runtimepy task -h
+$ ./venv3.13/bin/runtimepy task -h
 
 usage: runtimepy task [-h] [-i] [-w] [--no-poller] [-r RATE]
                       factory [configs ...]
@@ -218,14 +218,14 @@ options:
                         ensure that a 'wait_for_stop' application method is
                         run last
   --no-poller           don't run a connection-metrics poller task
-  -r RATE, --rate RATE  rate (in Hz) that the task should run (default: 10)
+  -r, --rate RATE       rate (in Hz) that the task should run (default: 10)
 
 ```
 
 ### `tftp`
 
 ```
-$ ./venv3.12/bin/runtimepy tftp -h
+$ ./venv3.13/bin/runtimepy tftp -h
 
 usage: runtimepy tftp [-h] [-p PORT] [-m MODE] [-t TIMEOUT] [-r REEMIT]
                       {read,write} host our_file [their_file]
@@ -238,28 +238,27 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  -p PORT, --port PORT  port to message (default: 69)
-  -m MODE, --mode MODE  tftp mode to use (default: octet)
-  -t TIMEOUT, --timeout TIMEOUT
+  -p, --port PORT       port to message (default: 69)
+  -m, --mode MODE       tftp mode to use (default: octet)
+  -t, --timeout TIMEOUT
                         timeout for each step
-  -r REEMIT, --reemit REEMIT
-                        transmit period for each step
+  -r, --reemit REEMIT   transmit period for each step
 
 ```
 
 ### `tui`
 
 ```
-$ ./venv3.12/bin/runtimepy tui -h
+$ ./venv3.13/bin/runtimepy tui -h
 
 usage: runtimepy tui [-h] [-i ITERATIONS] [-r RATE]
 
 options:
   -h, --help            show this help message and exit
-  -i ITERATIONS, --iterations ITERATIONS
+  -i, --iterations ITERATIONS
                         maximum number of program iterations (if greater than
                         zero, default: 0)
-  -r RATE, --rate RATE  frequency (in Hz) to run the interface (default: 60.0
+  -r, --rate RATE       frequency (in Hz) to run the interface (default: 60.0
                         Hz)
 
 ```

{runtimepy-5.15.7 → runtimepy-5.16.0}/README.md

@@ -2,11 +2,11 @@
     =====================================
     generator=datazen
     version=3.2.3
-    hash=fd0b9f87927033d8ee2eb5448d8aec76
+    hash=ebb0bba9899d4baf7ce73b082f5e384e
     =====================================
 -->
 
-# runtimepy ([5.15.7](https://pypi.org/project/runtimepy/))
+# runtimepy ([5.16.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/libre-embedded/runtimepy/workflows/Python%20Package/badge.svg)
@@ -40,7 +40,7 @@ This package is tested on the following platforms:
 # Command-line Options
 
 ```
-$ ./venv3.12/bin/runtimepy -h
+$ ./venv3.13/bin/runtimepy -h
 
 usage: runtimepy [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]
                  {arbiter,mtu,server,task,tftp,tui,noop} ...
@@ -54,7 +54,7 @@ options:
   -q, --quiet           set to reduce output
   --curses              whether or not to use curses.wrapper when starting
   --no-uvloop           whether or not to disable uvloop as event loop driver
-  -C DIR, --dir DIR     execute from a specific directory
+  -C, --dir DIR         execute from a specific directory
 
 commands:
   {arbiter,mtu,server,task,tftp,tui,noop}
@@ -74,7 +74,7 @@ commands:
 ### `arbiter`
 
 ```
-$ ./venv3.12/bin/runtimepy arbiter -h
+$ ./venv3.13/bin/runtimepy arbiter -h
 
 usage: runtimepy arbiter [-h] [-i] [-w] [--no-poller] configs [configs ...]
 
@@ -95,7 +95,7 @@ options:
 ### `mtu`
 
 ```
-$ ./venv3.12/bin/runtimepy mtu -h
+$ ./venv3.13/bin/runtimepy mtu -h
 
 usage: runtimepy mtu [-h] [--probe-size PROBE_SIZE] [--fallback FALLBACK] [-t]
                      destination [destination ...]
@@ -116,7 +116,7 @@ options:
 ### `server`
 
 ```
-$ ./venv3.12/bin/runtimepy server -h
+$ ./venv3.13/bin/runtimepy server -h
 
 usage: runtimepy server [-h] [-i] [-w] [--no-poller] [--cafile CAFILE]
                         [--capath CAPATH] [--cadata CADATA]
@@ -142,7 +142,7 @@ options:
   --certfile CERTFILE   passed directly to instantiation
   --keyfile KEYFILE     passed directly to instantiation
   --host HOST           host address to listen on (default: '0.0.0.0')
-  -p PORT, --port PORT  port to listen on (default: 0)
+  -p, --port PORT       port to listen on (default: 0)
   -u, --udp             whether or not this is a UDP-based server (otherwise
                         it must be a TCP-based server)
   -l, --loopback        if true a client of the same connection type is added
@@ -152,7 +152,7 @@ options:
 ### `task`
 
 ```
-$ ./venv3.12/bin/runtimepy task -h
+$ ./venv3.13/bin/runtimepy task -h
 
 usage: runtimepy task [-h] [-i] [-w] [--no-poller] [-r RATE]
                       factory [configs ...]
@@ -169,14 +169,14 @@ options:
                         ensure that a 'wait_for_stop' application method is
                         run last
   --no-poller           don't run a connection-metrics poller task
-  -r RATE, --rate RATE  rate (in Hz) that the task should run (default: 10)
+  -r, --rate RATE       rate (in Hz) that the task should run (default: 10)
 
 ```
 
 ### `tftp`
 
 ```
-$ ./venv3.12/bin/runtimepy tftp -h
+$ ./venv3.13/bin/runtimepy tftp -h
 
 usage: runtimepy tftp [-h] [-p PORT] [-m MODE] [-t TIMEOUT] [-r REEMIT]
                       {read,write} host our_file [their_file]
@@ -189,28 +189,27 @@ positional arguments:
 
 options:
   -h, --help            show this help message and exit
-  -p PORT, --port PORT  port to message (default: 69)
-  -m MODE, --mode MODE  tftp mode to use (default: octet)
-  -t TIMEOUT, --timeout TIMEOUT
+  -p, --port PORT       port to message (default: 69)
+  -m, --mode MODE       tftp mode to use (default: octet)
+  -t, --timeout TIMEOUT
                         timeout for each step
-  -r REEMIT, --reemit REEMIT
-                        transmit period for each step
+  -r, --reemit REEMIT   transmit period for each step
 
 ```
 
 ### `tui`
 
 ```
-$ ./venv3.12/bin/runtimepy tui -h
+$ ./venv3.13/bin/runtimepy tui -h
 
 usage: runtimepy tui [-h] [-i ITERATIONS] [-r RATE]
 
 options:
   -h, --help            show this help message and exit
-  -i ITERATIONS, --iterations ITERATIONS
+  -i, --iterations ITERATIONS
                         maximum number of program iterations (if greater than
                         zero, default: 0)
-  -r RATE, --rate RATE  frequency (in Hz) to run the interface (default: 60.0
+  -r, --rate RATE       frequency (in Hz) to run the interface (default: 60.0
                         Hz)
 
 ```

{runtimepy-5.15.7 → runtimepy-5.16.0}/pyproject.toml

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

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/__init__.py

@@ -1,7 +1,7 @@
 # =====================================
 # generator=datazen
 # version=3.2.3
-# hash=7591d3ee09b156575678bdf806e1b5c7
+# hash=d903df789fdb4c76fdf462319413ca2c
 # =====================================
 
 """
@@ -10,7 +10,7 @@ Useful defaults and other package metadata.
 
 DESCRIPTION = "A framework for implementing Python services."
 PKG_NAME = "runtimepy"
-VERSION = "5.15.7"
+VERSION = "5.16.0"
 
 # runtimepy-specific content.
 METRICS_NAME = "metrics"

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/codec/protocol/receiver.py

@@ -21,6 +21,10 @@ NonStructHandler = Callable[[BytesIO], bool]
 NON_STRUCT_ID = 0
 
 
+def null_struct_handler(_: Protocol) -> None:
+    """Takes no action."""
+
+
 class StructReceiver(LoggerMixin):
     """A class for sending and receiving struct messages."""
 
@@ -44,7 +48,9 @@ class StructReceiver(LoggerMixin):
         assert self.non_struct_handler is None
         self.non_struct_handler = handler
 
-    def add_handler(self, identifier: int, handler: StructHandler) -> None:
+    def add_handler(
+        self, identifier: int, handler: StructHandler = null_struct_handler
+    ) -> None:
         """Add a struct message handler."""
 
         assert identifier not in self.handlers

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/commands/arbiter.py

@@ -30,7 +30,9 @@ async def entry(
 
     await arbiter.load_configs(args.configs, wait_for_stop=args.wait_for_stop)
 
-    return await arbiter.app()
+    if args.init_only:
+        stop_sig.set()
+    return await arbiter.app(clear_stop_sig=not args.init_only)
 
 
 def app(args: _Namespace) -> int:
@@ -38,9 +40,6 @@ def app(args: _Namespace) -> int:
 
     stop_sig = _asyncio.Event()
 
-    if args.init_only:
-        stop_sig.set()
-
     result = _run_handle_stop(
         stop_sig,
         entry(stop_sig, args, window=args.window),

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/data/css/main.css

@@ -19,6 +19,8 @@ body > :first-child {
 
 #runtimepy-tabs {
   width: min-content;
+  max-width: 30vw;
+  overflow: hidden;
 }
 
 #runtimepy-splash {

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/message/interface.py

@@ -342,7 +342,11 @@ class JsonMessageInterface:
             target = self.targets.evaluate(key)
             if target:
                 assert target.data is not None
-                key, handler, kind = target.data
+                (  # pylint: disable=unpacking-non-sequence
+                    key,
+                    handler,
+                    kind,
+                ) = target.data
 
                 # Use target resolution data (if any) as a base.
                 with_sub_data = copy(

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/arbiter/base.py

@@ -237,9 +237,10 @@ class BaseConnectionArbiter(_NamespaceMixin, _LoggerMixin, TuiMixin):
             self._register_connection(value, key)
 
         # Ensure connections are all initialized.
-        await _asyncio.gather(
-            *(x.initialized.wait() for x in self._connections.values())
-        )
+        with self.log_time("Connection initialization", reminder=True):
+            await _asyncio.gather(
+                *(x.initialized.wait() for x in self._connections.values())
+            )
 
     async def _build_structs(self, info: AppInfo) -> None:
         """Build structs."""
@@ -362,6 +363,7 @@ class BaseConnectionArbiter(_NamespaceMixin, _LoggerMixin, TuiMixin):
         app: NetworkApplicationlike = None,
         check_connections: bool = True,
         config: _JsonObject = None,
+        clear_stop_sig: bool = True,
     ) -> int:
         """
         Ensures connections are given a chance to initialize, run the
@@ -372,6 +374,9 @@ class BaseConnectionArbiter(_NamespaceMixin, _LoggerMixin, TuiMixin):
         info: Optional[AppInfo] = None
 
         try:
+            if clear_stop_sig:
+                self.stop_sig.clear()
+
             async with _AsyncExitStack() as stack:
                 result, info = await self._main(
                     stack,
@@ -462,6 +467,7 @@ class BaseConnectionArbiter(_NamespaceMixin, _LoggerMixin, TuiMixin):
         app: NetworkApplicationlike = None,
         check_connections: bool = True,
         config: _JsonObject = None,
+        clear_stop_sig: bool = False,
     ) -> int:
         """
         Run the application alongside the connection manager and server tasks.
@@ -472,7 +478,10 @@ class BaseConnectionArbiter(_NamespaceMixin, _LoggerMixin, TuiMixin):
 
         # Run application.
         result = await self._entry(
-            app=app, check_connections=check_connections, config=config
+            app=app,
+            check_connections=check_connections,
+            config=config,
+            clear_stop_sig=clear_stop_sig,
         )
 
         # Shutdown any pending tasks.

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/arbiter/info.py

@@ -69,7 +69,10 @@ class RuntimeStruct(RuntimeStructBase):
     final_poll = False
 
     def init_env(self) -> None:
-        """Initialize this sample environment."""
+        """Initialize this environment."""
+
+    async def async_init_env(self) -> None:
+        """Initialize this environment."""
 
     @contextmanager
     def _final_poll(self) -> _Iterator[None]:
@@ -101,14 +104,18 @@ class RuntimeStruct(RuntimeStructBase):
             if ProtocolFactory in factory.__bases__:
                 self.recv = factory.singleton()
                 byte_order = self.recv.byte_order
-                with self.env.names_pushed("rx"):
+                if self.config.get("control", True):
+                    with self.env.names_pushed("rx"):
+                        self.env.register_protocol(self.recv, False)
+
+                    self.send = factory.instance()
+                    with self.env.names_pushed("tx"):
+                        self.env.register_protocol(self.send, True)
+                else:
                     self.env.register_protocol(self.recv, False)
 
-                self.send = factory.instance()
-                with self.env.names_pushed("tx"):
-                    self.env.register_protocol(self.send, True)
-
         self.init_env()
+        await self.async_init_env()
         self.update_byte_order(byte_order, **kwargs)
 
     def update_byte_order(self, byte_order: ByteOrder, **kwargs) -> None:

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/connection.py

@@ -43,6 +43,7 @@ class Connection(
     byte_order: ByteOrder = DEFAULT_BYTE_ORDER
 
     default_auto_restart = False
+    ignore_stop_sig = False
 
     def __init__(
         self,
@@ -300,7 +301,7 @@ class Connection(
             )
 
         # Allow a stop signal to also disable the connection.
-        if stop_sig is not None:
+        if stop_sig is not None and not self.ignore_stop_sig:
             self._tasks.append(_asyncio.create_task(self._wait_sig(stop_sig)))
 
         self.exited.clear()

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/http/response.py

@@ -3,11 +3,12 @@ A module implementing HTTP-response interfaces.
 """
 
 # built-in
+from abc import ABC, abstractmethod
 import http
 from io import StringIO
 import logging
 from pathlib import Path
-from typing import AsyncIterator, cast
+from typing import AsyncIterator, Optional, cast
 
 # third-party
 import aiofiles
@@ -96,19 +97,32 @@ class ResponseHeader(HeadersMixin):
         self["Cache-Control"] = value
 
 
-class AsyncResponse:
+class AsyncResponse(ABC):
+    """Interface for asynchronous responses."""
+
+    @abstractmethod
+    async def size(self) -> Optional[int]:
+        """Get this response's size."""
+
+    @abstractmethod
+    async def process(self) -> AsyncIterator[bytes]:
+        """Yield chunks to write asynchronously."""
+        yield bytes()  # pragma: nocover
+
+
+class AsyncFile(AsyncResponse):
     """
     A class facilitating asynchronous server responses for e.g.
     file-system files.
     """
 
-    def __init__(self, path: Path, chunk_size: int = 1024) -> None:
+    def __init__(self, path: Path, chunk_size: int = 4096) -> None:
         """Initialize this instance."""
 
         self.path = path
         self.chunk_size = chunk_size
 
-    async def size(self) -> int:
+    async def size(self) -> Optional[int]:
         """Get this response's size."""
         return cast(int, await aiofiles.os.path.getsize(self.path))
 

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/server/__init__.py

@@ -8,7 +8,7 @@ from io import StringIO
 import logging
 import mimetypes
 from pathlib import Path
-from typing import Any, Optional, TextIO, Union
+from typing import Any, Awaitable, Callable, Optional, TextIO, Union
 from urllib.parse import urlencode
 
 # third-party
@@ -22,7 +22,7 @@ from runtimepy.channel.environment.command import GLOBAL, global_command
 from runtimepy.net.html import full_markdown_page
 from runtimepy.net.http.header import RequestHeader
 from runtimepy.net.http.request_target import PathMaybeQuery
-from runtimepy.net.http.response import AsyncResponse, ResponseHeader
+from runtimepy.net.http.response import AsyncFile, ResponseHeader
 from runtimepy.net.server.html import HtmlApp, HtmlApps, get_html, html_handler
 from runtimepy.net.server.json import encode_json, json_handler
 from runtimepy.net.server.markdown import DIR_FILE, markdown_for_dir
@@ -41,11 +41,17 @@ def package_data_dir() -> Path:
     return result.parent
 
 
+CustomAsync = Callable[
+    [ResponseHeader, RequestHeader, Optional[bytearray]], Awaitable[HttpResult]
+]
+
+
 class RuntimepyServerConnection(HttpConnection):
     """A class implementing a server-connection interface for this package."""
 
     # Can register application methods to URL paths.
     apps: HtmlApps = {"/mux.html": mux_app}
+    custom: dict[str, CustomAsync] = {}
     default_app: Optional[HtmlApp] = None
 
     # Can load additional data into this dictionary for easy HTTP access.
@@ -245,7 +251,7 @@ class RuntimepyServerConnection(HttpConnection):
                 response.static_resource()
 
                 # Return the file data.
-                result = AsyncResponse(candidate)
+                result = AsyncFile(candidate)
                 break
 
         # Handle a directory as a last resort.
@@ -335,6 +341,12 @@ class RuntimepyServerConnection(HttpConnection):
                     response.static_resource()
                     return self.favicon_data
 
+                # Check for a custom handler.
+                if path in self.custom:
+                    return await self.custom[path](
+                        response, request, request_data
+                    )
+
                 # Try serving a file and handling redirects.
                 for handler in [self.try_redirect, self.try_file]:
                     result = await handler(

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/tcp/http/__init__.py

@@ -173,13 +173,13 @@ class HttpConnection(_TcpConnection):
     ) -> None:
         """Send a request or response to a request."""
 
-        # Set content length.
-        header["content-length"] = "0"
-
+        size = None
         if isinstance(data, AsyncResponse):
-            header["content-length"] = str(await data.size())
+            size = await data.size()
         elif data is not None:
-            header["content-length"] = str(len(data))
+            size = len(data)
+        if size is not None:
+            header["content-length"] = str(size)
 
         self.send_binary(bytes(header))
 

{runtimepy-5.15.7 → runtimepy-5.16.0}/runtimepy/net/websocket/connection.py

@@ -104,9 +104,7 @@ class WebsocketConnection(Connection):
 
     async def _send_binay_message(self, data: BinaryMessage) -> None:
         """Send a binary message."""
-        await self._handle_connection_closed(
-            self.protocol.send(data),  # type: ignore
-        )
+        await self._handle_connection_closed(self.protocol.send(data))
         self.metrics.tx.increment(len(data))
 
     async def close(self) -> None: