oaknut-econet-host 13.6.0__tar.gz

oaknut_econet_host-13.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oaknut_econet_host-13.6.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: oaknut-econet-host
+Version: 13.6.0
+Summary: The econet-host program: a CLI that configures Econet transports and service plug-ins and runs a station.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-econet-host
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-econet-station>=10.0
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: oaknut-extension>=10.0
+Requires-Dist: oaknut-cli>=10.0
+Requires-Dist: click>=8.1.7
+Dynamic: license-file
+
+# oaknut-econet-host
+
+The **`econet-host`** program — the CLI that turns installed Econet transport
+and service plug-ins into a running station.
+
+It depends on the `oaknut-econet-station` library and on Click (a hard
+dependency — this *is* a CLI), and discovers whatever transports
+(`oaknut.econet.transport`) and services (`oaknut.econet.service`) are installed.
+
+```
+econet-host run        [--config PATH]   # run the station until SIGINT/SIGTERM
+econet-host validate   [--config PATH]   # build the config, print the plan, exit
+econet-host list-transports              # installed transport plug-ins
+econet-host list-services                # installed service plug-ins
+econet-host describe   <name>            # a plug-in's description
+econet-host run --transport aun --station 0.254 --service kvstore   # flag-only quick path
+```
+
+Configuration is TOML, discovered (first match wins) from `--config`, then
+`[tool.econet-host]` in a `pyproject.toml`, then `econet-host.toml`, else the
+flags above. See `docs/dev/econet-host.md` for the design and the recommended
+uv-project deployment pattern.

oaknut_econet_host-13.6.0/README.md

@@ -0,0 +1,22 @@
+# oaknut-econet-host
+
+The **`econet-host`** program — the CLI that turns installed Econet transport
+and service plug-ins into a running station.
+
+It depends on the `oaknut-econet-station` library and on Click (a hard
+dependency — this *is* a CLI), and discovers whatever transports
+(`oaknut.econet.transport`) and services (`oaknut.econet.service`) are installed.
+
+```
+econet-host run        [--config PATH]   # run the station until SIGINT/SIGTERM
+econet-host validate   [--config PATH]   # build the config, print the plan, exit
+econet-host list-transports              # installed transport plug-ins
+econet-host list-services                # installed service plug-ins
+econet-host describe   <name>            # a plug-in's description
+econet-host run --transport aun --station 0.254 --service kvstore   # flag-only quick path
+```
+
+Configuration is TOML, discovered (first match wins) from `--config`, then
+`[tool.econet-host]` in a `pyproject.toml`, then `econet-host.toml`, else the
+flags above. See `docs/dev/econet-host.md` for the design and the recommended
+uv-project deployment pattern.

oaknut_econet_host-13.6.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-econet-host"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "The econet-host program: a CLI that configures Econet transports and service plug-ins and runs a station."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    "oaknut-econet-station>=10.0",
+    "oaknut-exception>=10.0",
+    "oaknut-extension>=10.0",
+    "oaknut-cli>=10.0",
+    "click>=8.1.7",
+]
+
+[project.scripts]
+econet-host = "oaknut.econet.host.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-econet-host"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.econet.host.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_econet_host-13.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oaknut_econet_host-13.6.0/src/oaknut/econet/host/__init__.py

@@ -0,0 +1,12 @@
+"""The econet-host host program.
+
+A CLI (the ``econet-host`` console script) that configures Econet transports
+and service plug-ins from TOML and runs a :class:`~oaknut.econet.station.Station`.
+The CLI itself lives in :mod:`oaknut.econet.host.cli`.
+"""
+
+from __future__ import annotations
+
+__version__ = "13.6.0"
+
+__all__: list[str] = []

oaknut_econet_host-13.6.0/src/oaknut/econet/host/cli.py

@@ -0,0 +1,153 @@
+"""The ``econet-host`` host CLI: configure transports + services and run."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import signal
+from pathlib import Path
+
+import click
+from oaknut.cli import use_plain_help
+from oaknut.econet.host import __version__
+from oaknut.econet.station import Station, build_station, config_from_flags, load_config
+from oaknut.exception import ConfigurationError, handled_errors
+from oaknut.extension import describe_extension, list_extensions, namespace_for
+
+_TRANSPORT_NS = namespace_for("econet.transport")
+_SERVICE_NS = namespace_for("econet.service")
+
+
+def _print_error(line: str, is_continuation: bool = False) -> None:
+    click.secho(line, err=True, fg="yellow" if is_continuation else "red")
+
+
+class _BoundaryGroup(click.Group):
+    """Wraps every command in the oaknut handled_errors boundary, honouring --debug."""
+
+    def invoke(self, ctx: click.Context):
+        debug = bool(ctx.params.get("debug", False))
+        with handled_errors(_print_error, debug=debug):
+            return super().invoke(ctx)
+
+
+def _resolve_config(config_path, transport, station, services):
+    if config_path is not None:
+        return load_config(config_path)
+    if transport is not None or station is not None or services:
+        if transport is None or station is None:
+            raise ConfigurationError("the flag path needs both --transport and --station")
+        config = config_from_flags(transport=transport, station=station, services=tuple(services))
+        return config, "command-line flags"
+    return load_config(None)
+
+
+@click.group(cls=_BoundaryGroup)
+@click.option("--debug", is_flag=True, help="Show full tracebacks for internal errors.")
+@click.version_option(__version__, prog_name="econet-host")
+def cli(debug: bool) -> None:
+    """Host Econet services on a single station."""
+
+
+_CONFIG = click.option(
+    "--config",
+    "config_path",
+    default=None,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Path to a station config TOML file.",
+)
+_TRANSPORT = click.option("--transport", default=None, help="Transport plug-in (flag-only path).")
+_STATION = click.option("--station", default=None, help="Station address, e.g. 0.254 (flag path).")
+_SERVICE = click.option(
+    "--service", "services", multiple=True, help="A service plug-in to host (repeatable)."
+)
+
+
+@cli.command()
+@_CONFIG
+@_TRANSPORT
+@_STATION
+@_SERVICE
+def run(config_path, transport, station, services) -> None:
+    """Run the station host until interrupted (SIGINT/SIGTERM)."""
+    config, source = _resolve_config(config_path, transport, station, services)
+    host = build_station(config)
+    click.echo(f"econet-host {host.address} on '{config.transport}' (config: {source})")
+    _echo_port_map(host)
+    _run_blocking(host)
+
+
+@cli.command()
+@_CONFIG
+@_TRANSPORT
+@_STATION
+@_SERVICE
+def validate(config_path, transport, station, services) -> None:
+    """Parse and build the configuration, print the plan, then exit."""
+    config, source = _resolve_config(config_path, transport, station, services)
+    host = build_station(config)
+    click.echo(f"config source: {source}")
+    click.echo(f"station:       {host.address}")
+    click.echo(f"transport:     {config.transport}")
+    _echo_port_map(host)
+    click.echo("ok")
+
+
+@cli.command("list-transports")
+def list_transports() -> None:
+    """List the installed transport plug-ins."""
+    for name in sorted(list_extensions(_TRANSPORT_NS)):
+        click.echo(name)
+
+
+@cli.command("list-services")
+def list_services() -> None:
+    """List the installed service plug-ins."""
+    for name in sorted(list_extensions(_SERVICE_NS)):
+        click.echo(name)
+
+
+@cli.command()
+@click.argument("name")
+def describe(name: str) -> None:
+    """Describe a transport or service plug-in by name."""
+    for kind, namespace in (("econet.transport", _TRANSPORT_NS), ("econet.service", _SERVICE_NS)):
+        if name in list_extensions(namespace):
+            click.echo(describe_extension(kind, namespace, name))
+            return
+    raise ConfigurationError(f"no transport or service named {name!r}")
+
+
+def _echo_port_map(host: Station) -> None:
+    port_map = host.port_map
+    if not port_map:
+        click.echo("  (no services)")
+        return
+    for port in sorted(port_map):
+        click.echo(f"  &{port:02X}  {port_map[port]}")
+
+
+async def serve_until(host: Station, stop: asyncio.Event) -> None:
+    """Open the transport, serve, and shut down gracefully when *stop* is set."""
+    await host.transport.open()
+    serve_task = asyncio.create_task(host.serve())
+    try:
+        await stop.wait()
+    finally:
+        await host.transport.close()
+        await serve_task
+
+
+def _run_blocking(host: Station) -> None:
+    async def _main() -> None:
+        stop = asyncio.Event()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            with contextlib.suppress(NotImplementedError):
+                loop.add_signal_handler(sig, stop.set)
+        await serve_until(host, stop)
+
+    asyncio.run(_main())
+
+
+use_plain_help(cli)

oaknut_econet_host-13.6.0/src/oaknut_econet_host.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: oaknut-econet-host
+Version: 13.6.0
+Summary: The econet-host program: a CLI that configures Econet transports and service plug-ins and runs a station.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-econet-host
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-econet-station>=10.0
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: oaknut-extension>=10.0
+Requires-Dist: oaknut-cli>=10.0
+Requires-Dist: click>=8.1.7
+Dynamic: license-file
+
+# oaknut-econet-host
+
+The **`econet-host`** program — the CLI that turns installed Econet transport
+and service plug-ins into a running station.
+
+It depends on the `oaknut-econet-station` library and on Click (a hard
+dependency — this *is* a CLI), and discovers whatever transports
+(`oaknut.econet.transport`) and services (`oaknut.econet.service`) are installed.
+
+```
+econet-host run        [--config PATH]   # run the station until SIGINT/SIGTERM
+econet-host validate   [--config PATH]   # build the config, print the plan, exit
+econet-host list-transports              # installed transport plug-ins
+econet-host list-services                # installed service plug-ins
+econet-host describe   <name>            # a plug-in's description
+econet-host run --transport aun --station 0.254 --service kvstore   # flag-only quick path
+```
+
+Configuration is TOML, discovered (first match wins) from `--config`, then
+`[tool.econet-host]` in a `pyproject.toml`, then `econet-host.toml`, else the
+flags above. See `docs/dev/econet-host.md` for the design and the recommended
+uv-project deployment pattern.

oaknut_econet_host-13.6.0/src/oaknut_econet_host.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/oaknut/econet/host/__init__.py
+src/oaknut/econet/host/cli.py
+src/oaknut_econet_host.egg-info/PKG-INFO
+src/oaknut_econet_host.egg-info/SOURCES.txt
+src/oaknut_econet_host.egg-info/dependency_links.txt
+src/oaknut_econet_host.egg-info/entry_points.txt
+src/oaknut_econet_host.egg-info/requires.txt
+src/oaknut_econet_host.egg-info/top_level.txt
+tests/test_cli.py

oaknut_econet_host-13.6.0/src/oaknut_econet_host.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oaknut_econet_host-13.6.0/src/oaknut_econet_host.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+econet-host = oaknut.econet.host.cli:cli

oaknut_econet_host-13.6.0/src/oaknut_econet_host.egg-info/requires.txt

@@ -0,0 +1,5 @@
+oaknut-econet-station>=10.0
+oaknut-exception>=10.0
+oaknut-extension>=10.0
+oaknut-cli>=10.0
+click>=8.1.7

oaknut_econet_host-13.6.0/src/oaknut_econet_host.egg-info/top_level.txt

@@ -0,0 +1 @@
+oaknut

oaknut_econet_host-13.6.0/tests/test_cli.py

@@ -0,0 +1,66 @@
+"""Tests for the econet-host host CLI and the serve lifecycle."""
+
+import asyncio
+
+from click.testing import CliRunner
+from oaknut.econet.core import Address, TestTransport
+from oaknut.econet.host.cli import cli, serve_until
+from oaknut.econet.station import Station
+
+
+def test_list_transports_lists_installed_plugins():
+    result = CliRunner().invoke(cli, ["list-transports"])
+    assert result.exit_code == 0, result.output
+    assert "aun" in result.output
+    assert "piconet" in result.output
+    assert "hat" in result.output
+
+
+def test_list_services_lists_kvstore():
+    result = CliRunner().invoke(cli, ["list-services"])
+    assert result.exit_code == 0, result.output
+    assert "kvstore" in result.output
+
+
+def test_describe_a_transport():
+    result = CliRunner().invoke(cli, ["describe", "aun"])
+    assert result.exit_code == 0, result.output
+    assert result.output.strip()
+
+
+def test_describe_unknown_name_errors():
+    result = CliRunner().invoke(cli, ["describe", "no-such-plugin"])
+    assert result.exit_code != 0
+
+
+def test_validate_flag_path():
+    result = CliRunner().invoke(
+        cli, ["validate", "--transport", "aun", "--station", "0.254", "--service", "kvstore"]
+    )
+    assert result.exit_code == 0, result.output
+    assert "0.254" in result.output
+    assert "aun" in result.output
+    assert "kvstore" in result.output
+    assert "command-line flags" in result.output
+
+
+def test_validate_unknown_transport_errors():
+    result = CliRunner().invoke(cli, ["validate", "--transport", "nope", "--station", "0.254"])
+    assert result.exit_code != 0
+
+
+def test_validate_flag_path_needs_both_transport_and_station():
+    result = CliRunner().invoke(cli, ["validate", "--transport", "aun"])
+    assert result.exit_code != 0
+
+
+async def test_serve_until_opens_then_closes_on_stop():
+    transport = TestTransport(local_station=Address(0, 254))
+    station = Station(transport)
+    stop = asyncio.Event()
+    task = asyncio.create_task(serve_until(station, stop))
+    await asyncio.sleep(0)
+    assert transport.is_open
+    stop.set()
+    await asyncio.wait_for(task, timeout=1.0)
+    assert transport.is_closed