oaknut-cli 12.8.2__tar.gz → 12.10.0__tar.gz

{oaknut_cli-12.8.2/src/oaknut_cli.egg-info → oaknut_cli-12.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oaknut-cli
-Version: 12.8.2
+Version: 12.10.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
@@ -23,7 +23,7 @@ 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.3.0
+Requires-Dist: asyoulikeit>=1.4.0
 Dynamic: license-file
 
 # oaknut-cli

{oaknut_cli-12.8.2 → oaknut_cli-12.10.0}/pyproject.toml

@@ -27,7 +27,7 @@ dependencies = [
     "oaknut-extension>=10.0",
     "oaknut-file>=10.0",
     "click>=8.1.7",
-    "asyoulikeit>=1.3.0",
+    "asyoulikeit>=1.4.0",
 ]
 
 [project.urls]

{oaknut_cli-12.8.2 → oaknut_cli-12.10.0}/src/oaknut/cli/__init__.py

@@ -33,12 +33,14 @@ from oaknut.cli.reports import (
     address_cell,
     bytes_cell,
     control_pictures,
+    datestamp_cell,
+    filetype_cell,
     kv_table,
     size_cell,
     text_cell,
 )
 
-__version__ = "12.8.2"
+__version__ = "12.10.0"
 
 __all__ = [
     "COMMAND_KIND",
@@ -51,6 +53,8 @@ __all__ = [
     "address_cell",
     "bytes_cell",
     "control_pictures",
+    "datestamp_cell",
+    "filetype_cell",
     "kv_table",
     "size_cell",
     "text_cell",

{oaknut_cli-12.8.2 → oaknut_cli-12.10.0}/src/oaknut/cli/reports.py

@@ -9,8 +9,11 @@ command can render output without depending on ``oaknut-disc``.
 
 from __future__ import annotations
 
+from datetime import datetime, timedelta
+
 from asyoulikeit import ByAudience
 from oaknut.file.capacity import format_capacity
+from oaknut.file.filetypes import filetype_name
 
 #: Acorn discs are addressed in 256-byte sectors throughout.
 SECTOR_SIZE = 256
@@ -71,14 +74,49 @@ def bytes_cell(num_bytes: int) -> ByAudience:
     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.
+def address_cell(address: int, *, conceal: bool = False) -> ByAudience:
+    """An Acorn load/exec address as an audience-aware cell.
+
+    Humans read the ``0x``-prefixed hex form, trimmed of leading zeros
+    to a whole number of bytes (an even count of hex digits) with a
+    minimum of six — the width Acorn MOS uses for a DFS address, so a
+    table stays narrow without diverging from ``*EX`` / ``*INFO``. A
+    larger address (an ADFS 32-bit value) grows in whole bytes. Machine
+    formatters (JSON, TSV) get the raw integer, so a consumer never has
+    to parse a base back out of a string.
+
+    When *conceal* is set the human form is blank but the machine form
+    keeps the raw integer: a filetype-stamped file's load/exec hold an
+    encoded filetype and datestamp shown in their own columns, yet a
+    machine consumer still gets the faithful bytes.
+    """
+    if conceal:
+        return ByAudience(machine=address, human="")
+    digits = max(6, len(f"{address:X}"))
+    width = digits + (digits & 1)  # round up to a whole number of bytes
+    return ByAudience(machine=address, human=f"0x{address:0{width}X}")
+
+
+def filetype_cell(filetype: int) -> ByAudience:
+    """A RISC OS filetype as an audience-aware cell.
+
+    Humans read the registered name (or the ``&XXX`` hex form);
+    machine formatters get the raw 12-bit number.
+    """
+    return ByAudience(machine=filetype, human=filetype_name(filetype))
+
+
+def datestamp_cell(when: datetime, resolution: timedelta) -> str:
+    """A datestamp as an ISO 8601 string at the filesystem's resolution.
 
-    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.
+    A filesystem that records only a calendar day (AFS) yields a bare
+    date; one that records time of day (ADFS, centiseconds) yields a
+    full naive-local timestamp. The value is the same for humans and
+    machines, so a single string serves every formatter.
     """
-    return ByAudience(machine=address, human=f"0x{address:08X}")
+    if resolution >= timedelta(days=1):
+        return when.date().isoformat()
+    return when.isoformat(sep="T", timespec="milliseconds")
 
 
 def kv_table(title: str, pairs: list[tuple[str, str, object]]):

{oaknut_cli-12.8.2 → oaknut_cli-12.10.0/src/oaknut_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oaknut-cli
-Version: 12.8.2
+Version: 12.10.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
@@ -23,7 +23,7 @@ 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.3.0
+Requires-Dist: asyoulikeit>=1.4.0
 Dynamic: license-file
 
 # oaknut-cli

{oaknut_cli-12.8.2 → oaknut_cli-12.10.0}/src/oaknut_cli.egg-info/requires.txt

@@ -2,4 +2,4 @@ oaknut-exception>=10.0
 oaknut-extension>=10.0
 oaknut-file>=10.0
 click>=8.1.7
-asyoulikeit>=1.3.0
+asyoulikeit>=1.4.0

{oaknut_cli-12.8.2 → oaknut_cli-12.10.0}/tests/test_reports.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from asyoulikeit import ByAudience
-from oaknut.cli import control_pictures, text_cell
+from oaknut.cli import address_cell, control_pictures, text_cell
 
 
 class TestControlPictures:
@@ -36,3 +36,27 @@ class TestTextCell:
         # Machines keep the raw bytes; humans get control pictures.
         assert cell.machine == "\x0cPascal\n\r"
         assert cell.human == "␌Pascal␊␍"
+
+
+class TestAddressCell:
+    def test_machine_keeps_raw_int(self):
+        cell = address_cell(0x1900)
+        assert isinstance(cell, ByAudience)
+        assert cell.machine == 0x1900
+
+    def test_human_keeps_0x_prefix(self):
+        assert address_cell(0x1900).human.startswith("0x")
+
+    def test_human_trimmed_to_minimum_six_hexits(self):
+        # Acorn MOS shows DFS addresses in six hex digits; leading zeros
+        # beyond that serve no purpose, so the narrowest form is six.
+        assert address_cell(0x1900).human == "0x001900"
+        assert address_cell(0x838F).human == "0x00838F"
+        assert address_cell(0x0).human == "0x000000"
+
+    def test_human_grows_in_whole_bytes(self):
+        # Above six hexits the width rounds up to an even number of hexits
+        # (a whole number of bytes), never an odd count.
+        assert address_cell(0xFFFFFF).human == "0xFFFFFF"
+        assert address_cell(0x1FF0000).human == "0x01FF0000"
+        assert address_cell(0xFFFF0E00).human == "0xFFFF0E00"