oaknut-cli 12.0.0__tar.gz

oaknut_cli-12.0.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_cli-12.0.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: oaknut-cli
+Version: 12.0.0
+Summary: Shared CLI toolkit for the oaknut family: the contributed-command axis and report-rendering helpers a disc command needs, below the filesystem packages.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-cli
+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 :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: oaknut-extension>=10.0
+Requires-Dist: oaknut-file>=10.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: asyoulikeit>=1.2.0
+Dynamic: license-file
+
+# oaknut-cli
+
+Shared CLI toolkit for the [oaknut](https://github.com/rob-smallshire/oaknut)
+family. It sits *below* the filesystem packages so that both the `disc`
+CLI (`oaknut-disc`) and a filesystem's own contributed commands can
+depend on it without a dependency cycle.
+
+It provides the **contributed-command axis** — discovery of Click
+commands a filesystem package registers on the `oaknut.command`
+entry-point namespace — and report-rendering helpers shared between the
+generic `disc` commands and the contributed ones.
+
+See `docs/dev/contributed-commands.md` for the design.

oaknut_cli-12.0.0/README.md

@@ -0,0 +1,13 @@
+# oaknut-cli
+
+Shared CLI toolkit for the [oaknut](https://github.com/rob-smallshire/oaknut)
+family. It sits *below* the filesystem packages so that both the `disc`
+CLI (`oaknut-disc`) and a filesystem's own contributed commands can
+depend on it without a dependency cycle.
+
+It provides the **contributed-command axis** — discovery of Click
+commands a filesystem package registers on the `oaknut.command`
+entry-point namespace — and report-rendering helpers shared between the
+generic `disc` commands and the contributed ones.
+
+See `docs/dev/contributed-commands.md` for the design.

oaknut_cli-12.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-cli"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Shared CLI toolkit for the oaknut family: the contributed-command axis and report-rendering helpers a disc command needs, below the filesystem packages."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Filesystems",
+]
+dependencies = [
+    "oaknut-exception>=10.0",
+    "oaknut-extension>=10.0",
+    "oaknut-file>=10.0",
+    "click>=8.1.7",
+    "asyoulikeit>=1.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-cli"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.cli.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_cli-12.0.0/setup.cfg

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

oaknut_cli-12.0.0/src/oaknut/cli/__init__.py

@@ -0,0 +1,51 @@
+"""Shared CLI toolkit for the oaknut family.
+
+This package sits *below* the filesystem packages (oaknut-dfs/adfs/afs)
+so that both the ``disc`` CLI (``oaknut-disc``) and a filesystem's own
+contributed commands can depend on it without a cycle — ``oaknut-disc``
+depends on the filesystem packages, so they must never depend on it.
+
+It provides:
+
+- the **contributed-command axis** — discovery of Click commands
+  registered by filesystem packages on the ``oaknut.command`` entry-point
+  namespace (see :func:`contributed_commands`); and
+- report-rendering helpers shared between the generic ``disc`` commands
+  and the contributed ones.
+
+See ``docs/dev/contributed-commands.md`` for the design.
+"""
+
+from __future__ import annotations
+
+from oaknut.cli.commands import (
+    COMMAND_KIND,
+    COMMAND_NAMESPACE,
+    contributed_commands,
+)
+from oaknut.cli.help import (
+    PlainHelpFormatter,
+    strip_rst,
+    use_plain_help,
+)
+from oaknut.cli.reports import (
+    SECTOR_SIZE,
+    address_cell,
+    kv_table,
+    size_cell,
+)
+
+__version__ = "12.0.0"
+
+__all__ = [
+    "COMMAND_KIND",
+    "COMMAND_NAMESPACE",
+    "contributed_commands",
+    "PlainHelpFormatter",
+    "strip_rst",
+    "use_plain_help",
+    "SECTOR_SIZE",
+    "address_cell",
+    "kv_table",
+    "size_cell",
+]

oaknut_cli-12.0.0/src/oaknut/cli/commands.py

@@ -0,0 +1,55 @@
+"""The contributed-command axis.
+
+A filesystem package contributes admin subcommands to the ``disc`` CLI by
+registering a Click command (or group) on the ``oaknut.command``
+entry-point namespace::
+
+    [project.entry-points."oaknut.command"]
+    afs = "oaknut.afs.cli:afs"   # afs is a click.Group
+
+:func:`contributed_commands` discovers them; the ``disc`` root group
+attaches each with ``cli.add_command(...)``. An install sees exactly the
+commands its installed filesystems contribute.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import stevedore
+from oaknut.extension import namespace_for
+
+if TYPE_CHECKING:
+    import click
+
+#: The extension *kind* (axis) contributed CLI commands belong to.
+COMMAND_KIND = "command"
+
+#: The entry-point namespace commands register under: ``"oaknut.command"``.
+COMMAND_NAMESPACE = namespace_for(COMMAND_KIND)
+
+
+def _skip_unloadable(manager, entrypoint, exception) -> None:
+    """Ignore a command whose package cannot be imported.
+
+    A filesystem installed without its optional ``[cli]`` extra (so Click
+    is absent) leaves its command entry point unloadable. That command is
+    simply unavailable — not a fatal error — so the CLI degrades
+    gracefully rather than crashing.
+    """
+
+
+def contributed_commands() -> list["click.Command"]:
+    """Every Click command contributed on the ``oaknut.command`` axis.
+
+    Each entry point's target is a ready-made Click ``Command`` or
+    ``Group`` object. Returned sorted by name so the CLI's command
+    listing is deterministic regardless of discovery order.
+    """
+    manager = stevedore.ExtensionManager(
+        namespace=COMMAND_NAMESPACE,
+        invoke_on_load=False,
+        on_load_failure_callback=_skip_unloadable,
+    )
+    commands = [extension.plugin for extension in manager]
+    return sorted(commands, key=lambda command: getattr(command, "name", "") or "")

oaknut_cli-12.0.0/src/oaknut/cli/help.py

@@ -0,0 +1,71 @@
+"""Terminal-friendly help: strip RST inline markup as Click renders it.
+
+Command docstrings and option help are dual-purpose — Click prints them
+verbatim at the terminal, while the ``disc`` Sphinx command reference
+renders them as reStructuredText. RST inline markup (``literal`` spans)
+that reads as code in the manual shows as stray backticks in a terminal.
+
+:func:`use_plain_help` makes a command (and, for a group, its whole
+subtree) render help through a formatter that reduces that markup to
+plain text at display time, leaving the docstrings untouched for Sphinx.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+import click
+
+__all__ = ["strip_rst", "PlainHelpFormatter", "use_plain_help"]
+
+# ``literal`` and `interpreted` spans — one or two backticks either side.
+_BACKTICK_SPAN = re.compile(r"`{1,2}([^`]+)`{1,2}")
+
+
+def strip_rst(text: str) -> str:
+    """Reduce the RST inline markup used in help text to plain text.
+
+    ``code`` and `code` both collapse to ``code`` — readable at a
+    terminal. Only backtick spans are touched; everything else is left
+    as written.
+    """
+    return _BACKTICK_SPAN.sub(r"\1", text)
+
+
+class PlainHelpFormatter(click.HelpFormatter):
+    """A Click help formatter that strips RST markup as it writes.
+
+    Every piece of help text — the body paragraphs (:meth:`write_text`)
+    and the option / subcommand definition lists (:meth:`write_dl`) —
+    passes through :func:`strip_rst` on the way out.
+    """
+
+    def write_text(self, text: str) -> None:
+        super().write_text(strip_rst(text))
+
+    def write_dl(self, rows: Iterable[tuple[str, str]], *args: object, **kwargs: object) -> None:
+        super().write_dl(
+            [(strip_rst(term), strip_rst(definition)) for term, definition in rows],
+            *args,
+            **kwargs,
+        )
+
+
+class _PlainHelpContext(click.Context):
+    """A Click context whose help is formatted by :class:`PlainHelpFormatter`."""
+
+    formatter_class = PlainHelpFormatter
+
+
+def use_plain_help(command: click.Command) -> None:
+    """Render *command*'s help with RST markup stripped.
+
+    For a group, applies to the whole subtree, so a single call on a
+    fully-assembled CLI covers every subcommand — including ones
+    contributed by other packages, regardless of how they were built.
+    """
+    command.context_class = _PlainHelpContext
+    if isinstance(command, click.Group):
+        for sub in command.commands.values():
+            use_plain_help(sub)

oaknut_cli-12.0.0/src/oaknut/cli/reports.py

@@ -0,0 +1,58 @@
+"""Report-rendering helpers shared across ``disc`` commands.
+
+Audience-aware cells (a friendly string for humans, a raw value for
+machine formatters) and a transposed key-value table, used by both the
+generic ``disc`` commands and the filesystem-contributed ones. Built on
+asyoulikeit; kept here, below the filesystem packages, so a contributed
+command can render output without depending on ``oaknut-disc``.
+"""
+
+from __future__ import annotations
+
+from asyoulikeit import ByAudience
+from oaknut.file.capacity import format_capacity
+
+#: Acorn discs are addressed in 256-byte sectors throughout.
+SECTOR_SIZE = 256
+
+
+def size_cell(sectors: int) -> ByAudience:
+    """A capacity (given in sectors) as an audience-aware cell.
+
+    Humans read friendly IEC units (``800.0 KiB``); machine formatters
+    get the raw byte count as an integer, so the presentation base is
+    irrelevant to a consumer.
+    """
+    num_bytes = sectors * SECTOR_SIZE
+    return ByAudience(machine=num_bytes, human=format_capacity(num_bytes))
+
+
+def address_cell(address: int) -> ByAudience:
+    """A 32-bit Acorn address as an audience-aware cell.
+
+    Humans read the conventional ``0x``-prefixed 8-hex-digit form;
+    machine formatters (JSON, TSV) get the raw integer, so a consumer
+    never has to parse a base back out of a string.
+    """
+    return ByAudience(machine=address, human=f"0x{address:08X}")
+
+
+def kv_table(title: str, pairs: list[tuple[str, str, object]]):
+    """Build a transposed single-row table from (key, label, value) tuples.
+
+    Each tuple becomes a column whose sole row holds the value. A value
+    may be a plain string, an integer (for machine-readable counts), or
+    a :class:`~asyoulikeit.ByAudience` cell that renders one way for
+    humans and another for machine formatters. Transposed presentation
+    turns the one-row table into a key-value report in the display
+    formatter.
+    """
+    from asyoulikeit.tabular_data import TableContent
+
+    tc = TableContent(title=title, present_transposed=True)
+    row: dict = {}
+    for index, (key, label, value) in enumerate(pairs):
+        tc.add_column(key, label, header=(index == 0))
+        row[key] = value
+    tc.add_row(**row)
+    return tc

oaknut_cli-12.0.0/src/oaknut_cli.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: oaknut-cli
+Version: 12.0.0
+Summary: Shared CLI toolkit for the oaknut family: the contributed-command axis and report-rendering helpers a disc command needs, below the filesystem packages.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-cli
+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 :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: oaknut-extension>=10.0
+Requires-Dist: oaknut-file>=10.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: asyoulikeit>=1.2.0
+Dynamic: license-file
+
+# oaknut-cli
+
+Shared CLI toolkit for the [oaknut](https://github.com/rob-smallshire/oaknut)
+family. It sits *below* the filesystem packages so that both the `disc`
+CLI (`oaknut-disc`) and a filesystem's own contributed commands can
+depend on it without a dependency cycle.
+
+It provides the **contributed-command axis** — discovery of Click
+commands a filesystem package registers on the `oaknut.command`
+entry-point namespace — and report-rendering helpers shared between the
+generic `disc` commands and the contributed ones.
+
+See `docs/dev/contributed-commands.md` for the design.

oaknut_cli-12.0.0/src/oaknut_cli.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/oaknut/cli/__init__.py
+src/oaknut/cli/commands.py
+src/oaknut/cli/help.py
+src/oaknut/cli/reports.py
+src/oaknut_cli.egg-info/PKG-INFO
+src/oaknut_cli.egg-info/SOURCES.txt
+src/oaknut_cli.egg-info/dependency_links.txt
+src/oaknut_cli.egg-info/requires.txt
+src/oaknut_cli.egg-info/top_level.txt
+tests/test_commands.py
+tests/test_help.py

oaknut_cli-12.0.0/src/oaknut_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oaknut_cli-12.0.0/src/oaknut_cli.egg-info/requires.txt

@@ -0,0 +1,5 @@
+oaknut-exception>=10.0
+oaknut-extension>=10.0
+oaknut-file>=10.0
+click>=8.1.7
+asyoulikeit>=1.2.0

oaknut_cli-12.0.0/src/oaknut_cli.egg-info/top_level.txt

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

oaknut_cli-12.0.0/tests/test_commands.py

@@ -0,0 +1,47 @@
+"""Tests for the contributed-command axis."""
+
+from oaknut.cli import COMMAND_NAMESPACE, contributed_commands
+
+
+def test_command_namespace():
+    assert COMMAND_NAMESPACE == "oaknut.command"
+
+
+def test_contributed_commands_is_a_sorted_list():
+    # Whatever command-contributing packages are installed, discovery
+    # returns a list and does not raise. (Empty until a filesystem
+    # registers an oaknut.command entry point.)
+    commands = contributed_commands()
+    assert isinstance(commands, list)
+    names = [getattr(c, "name", "") for c in commands]
+    assert names == sorted(names)
+
+
+class TestSkipsUnloadable:
+    def test_a_failing_entry_point_does_not_crash_discovery(self, monkeypatch):
+        # Simulate one entry point importing nothing usable (e.g. a
+        # filesystem installed without its [cli] extra): discovery must
+        # skip it, not raise.
+        import stevedore
+        from oaknut.cli import commands as commands_module
+
+        class _FakeExtension:
+            name = "ok"
+            plugin = type("Cmd", (), {"name": "ok"})()
+
+        class _FakeManager:
+            def __init__(self, *args, on_load_failure_callback=None, **kwargs):
+                # Exercise the skip callback with a synthetic failure, then
+                # yield one good extension.
+                if on_load_failure_callback is not None:
+                    on_load_failure_callback(self, _FakeEntryPoint(), ImportError("no click"))
+
+            def __iter__(self):
+                return iter([_FakeExtension()])
+
+        class _FakeEntryPoint:
+            name = "broken"
+
+        monkeypatch.setattr(stevedore, "ExtensionManager", _FakeManager)
+        result = commands_module.contributed_commands()
+        assert [c.name for c in result] == ["ok"]

oaknut_cli-12.0.0/tests/test_help.py

@@ -0,0 +1,47 @@
+"""Tests for the terminal-friendly help machinery."""
+
+import click
+from click.testing import CliRunner
+from oaknut.cli import PlainHelpFormatter, strip_rst, use_plain_help
+
+
+class TestStripRst:
+    def test_double_backticks_become_plain(self):
+        assert strip_rst("pass ``--geometry`` to set it") == "pass --geometry to set it"
+
+    def test_single_backticks_become_plain(self):
+        assert strip_rst("run `disc list-filesystems`") == "run disc list-filesystems"
+
+    def test_text_without_markup_is_unchanged(self):
+        assert strip_rst("plain text, nothing to do") == "plain text, nothing to do"
+
+
+class TestUsePlainHelp:
+    def _cli(self):
+        @click.group()
+        def root():
+            """Root group with ``markup`` in its help."""
+
+        @root.command()
+        @click.option("--thing", help="A thing; see `other-command`.")
+        def sub(thing):
+            """Do a ``thing`` to the disc."""
+
+        return root
+
+    def test_help_text_is_stripped(self):
+        root = self._cli()
+        use_plain_help(root)
+        result = CliRunner().invoke(root, ["sub", "--help"])
+        assert result.exit_code == 0
+        assert "`" not in result.output
+        # Content survives, only the markup is gone.
+        assert "Do a thing to the disc." in result.output
+        assert "see other-command." in result.output
+
+    def test_applies_to_the_whole_subtree(self):
+        root = self._cli()
+        use_plain_help(root)
+        # Both the group's own help and the subcommand's use the formatter.
+        assert root.context_class.formatter_class is PlainHelpFormatter
+        assert root.commands["sub"].context_class.formatter_class is PlainHelpFormatter