oaknut-filesystem 12.0.0__py3-none-any.whl

oaknut/filesystem/__init__.py

@@ -0,0 +1,119 @@
+"""The pluggable filesystem contract for the oaknut family.
+
+A *filesystem* (Acorn DFS, Watford DFS, ADFS, AFS, …) is the unit of
+extension, registered on the ``oaknut.filesystem`` entry-point axis. Each
+:class:`Filesystem` detects itself (:meth:`Filesystem.probe`), opens a
+region into a :class:`Mount` exposing a small core plus opt-in capability
+protocols, and declares its physical :class:`Geometry` grammar.
+
+Geometry (the physical byte→sector layout) and the filesystem (the
+logical structure) are kept strictly apart. :func:`identify` runs the
+registered filesystems over an image, ranks the candidates, and recurses
+into reserved regions to build a per-partition :class:`Identification`
+tree — depending on, and importing, no concrete filesystem package.
+"""
+
+from oaknut.filesystem.capabilities import (
+    AcornMetadata,
+    Bootable,
+    Compactable,
+    DirectoryTitled,
+    DiscGeometry,
+    Entry,
+    FreeMap,
+    FreeMapData,
+    FreeSpace,
+    HierarchicalDirectories,
+    Mount,
+    PhysicalGeometry,
+    RegionHost,
+    Sized,
+    Titled,
+    UserDatabase,
+    Validatable,
+)
+from oaknut.filesystem.coordinator import (
+    create_filesystem,
+    creating_filesystem,
+    describe_filesystem,
+    filesystem_names,
+    identify,
+)
+from oaknut.filesystem.exceptions import (
+    FilesystemError,
+    FilesystemExtensionError,
+    GeometryError,
+    ReadOnlyFilesystemError,
+)
+from oaknut.filesystem.filesystem import (
+    FILESYSTEM_KIND,
+    FILESYSTEM_NAMESPACE,
+    Filesystem,
+)
+from oaknut.filesystem.geometry import (
+    FLOPPY,
+    WINCHESTER,
+    Geometry,
+    GeometryGrammar,
+    floppy_geometry,
+    geometry_from_dsc,
+    region_reader,
+    winchester_geometry,
+)
+from oaknut.filesystem.identification import Confidence, Identification, Partition
+from oaknut.filesystem.reader import ImageReader, ImageSource, reader_for
+
+__version__ = "12.0.0"
+
+__all__ = [
+    # contract
+    "Filesystem",
+    "FILESYSTEM_KIND",
+    "FILESYSTEM_NAMESPACE",
+    # capabilities
+    "Mount",
+    "Entry",
+    "HierarchicalDirectories",
+    "AcornMetadata",
+    "Titled",
+    "DirectoryTitled",
+    "Bootable",
+    "FreeSpace",
+    "FreeMap",
+    "FreeMapData",
+    "Sized",
+    "PhysicalGeometry",
+    "DiscGeometry",
+    "Compactable",
+    "Validatable",
+    "UserDatabase",
+    "RegionHost",
+    # geometry
+    "Geometry",
+    "GeometryGrammar",
+    "floppy_geometry",
+    "winchester_geometry",
+    "geometry_from_dsc",
+    "region_reader",
+    "FLOPPY",
+    "WINCHESTER",
+    # identification
+    "Confidence",
+    "Identification",
+    "Partition",
+    # coordinator
+    "identify",
+    "filesystem_names",
+    "describe_filesystem",
+    "create_filesystem",
+    "creating_filesystem",
+    # reader
+    "ImageReader",
+    "ImageSource",
+    "reader_for",
+    # exceptions
+    "FilesystemError",
+    "GeometryError",
+    "ReadOnlyFilesystemError",
+    "FilesystemExtensionError",
+]

oaknut/filesystem/capabilities.py

@@ -0,0 +1,302 @@
+"""The mounted-filesystem interface: a small core plus opt-in capabilities.
+
+Every mounted filesystem provides the :class:`Mount` core. Beyond that,
+features differ wildly — a flat DFS catalogue, a hierarchical ADFS tree,
+AFS user accounts, a foreign FAT with none of Acorn's metadata — so the
+extras are **opt-in capability protocols** the CLI feature-detects with
+``isinstance`` (each is ``runtime_checkable``). A command is "available
+when the mount provides capability X", never "when the filesystem is Y".
+
+These signatures establish the *shape* of the contract; they will be
+refined as the concrete filesystems are wrapped (Phase B).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from oaknut.file import AcornMeta, BootOption
+    from oaknut.filesystem.identification import Partition
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One directory entry, in filesystem-agnostic terms.
+
+    Acorn-specific metadata (load/exec/access) is reached through the
+    :class:`AcornMetadata` capability, not carried here, so a foreign
+    filesystem's entries need none of it.
+    """
+
+    name: str
+    is_dir: bool
+    length: int = 0
+    #: The entry's full in-partition path, so a caller can address it
+    #: (e.g. fetch its metadata) without re-joining in the filesystem's
+    #: own syntax. Empty only for a bare, unaddressed entry.
+    path: str = ""
+
+
+@runtime_checkable
+class Mount(Protocol):
+    """The core every mounted filesystem provides.
+
+    Paths are strings in the *filesystem's own* syntax (`$.DIR.FILE` for
+    Acorn, `\\DIR\\FILE` for FAT, `D.DIR.FILE` for a DDOS volume); the
+    filesystem parses them — the CLI never does.
+    """
+
+    def path_root(self) -> str:
+        """The root path string (e.g. ``"$"`` for Acorn filesystems)."""
+        ...
+
+    def stat(self, path: str) -> Entry:
+        """The :class:`Entry` for *path* (name, kind, length, full path)."""
+        ...
+
+    def join(self, parent: str, name: str) -> str:
+        """The path of child *name* under directory *parent*.
+
+        The filesystem owns its path syntax (``$.A`` for Acorn, the root
+        sometimes nameless), so the CLI builds new paths through this
+        rather than concatenating — needed when creating a path that does
+        not exist yet (e.g. a bulk import target).
+        """
+        ...
+
+    def iter_entries(self, path: str) -> Iterable[Entry]:
+        """Yield the entries of the directory at *path*."""
+        ...
+
+    def exists(self, path: str) -> bool:
+        """Whether anything exists at *path*."""
+        ...
+
+    def read_bytes(self, path: str) -> bytes:
+        """The contents of the file at *path*."""
+        ...
+
+    def write_bytes(self, path: str, data: bytes) -> None:
+        """Write *data* to *path*, creating or replacing the file."""
+        ...
+
+    def remove(self, path: str, *, force: bool = False) -> None:
+        """Delete the file or directory at *path*.
+
+        A directory is removed if the filesystem represents one (a flat
+        catalogue has none, so removing its notional directory is a
+        no-op). *force* overrides a lock — the filesystem unlocks the
+        entry first, owning its own locked-entry semantics so the access
+        byte's layout never leaks to the caller.
+        """
+        ...
+
+    def rename(self, old_path: str, new_path: str) -> None:
+        """Rename / move the entry at *old_path* to *new_path* in place."""
+        ...
+
+
+@runtime_checkable
+class HierarchicalDirectories(Protocol):
+    """The filesystem nests directories arbitrarily (ADFS, AFS, FAT, DDOS).
+
+    Its absence marks a flat catalogue (Acorn/Watford DFS: a single
+    top-level directory only).
+    """
+
+    def make_directory(
+        self,
+        path: str,
+        *,
+        parents: bool = False,
+        exist_ok: bool = False,
+        title: str | None = None,
+    ) -> None:
+        """Create a directory at *path*.
+
+        *parents* creates missing ancestors; *exist_ok* tolerates an
+        existing directory. *title* sets the new directory's title where
+        the filesystem supports per-directory titles (ADFS) and is
+        rejected (before anything is created) where it does not (AFS).
+        """
+        ...
+
+
+@runtime_checkable
+class AcornMetadata(Protocol):
+    """Files carry Acorn load/exec addresses and an access byte."""
+
+    def acorn_meta(self, path: str) -> "AcornMeta":
+        """The Acorn metadata of the file at *path*."""
+        ...
+
+    def set_acorn_meta(self, path: str, meta: "AcornMeta") -> None:
+        """Replace the Acorn metadata of the file at *path*."""
+        ...
+
+
+@runtime_checkable
+class Titled(Protocol):
+    """The disc carries a title / name (DFS, ADFS, AFS)."""
+
+    @property
+    def title(self) -> str:
+        """The disc title / name."""
+        ...
+
+    def set_title(self, title: str) -> None:
+        """Set the disc title / name."""
+        ...
+
+
+@runtime_checkable
+class DirectoryTitled(Protocol):
+    """Directories carry their own title, distinct from the disc's (ADFS).
+
+    Its absence marks a filesystem whose directories have no title field
+    (DFS, AFS) — setting one there is rejected.
+    """
+
+    def directory_title(self, path: str) -> str:
+        """The title of the directory at *path*."""
+        ...
+
+    def set_directory_title(self, path: str, title: str) -> None:
+        """Set the title of the directory at *path*."""
+        ...
+
+
+@runtime_checkable
+class Bootable(Protocol):
+    """The disc carries a ``*OPT 4`` boot option (DFS, ADFS)."""
+
+    @property
+    def boot_option(self) -> "BootOption":
+        """The disc's ``*OPT 4`` boot option."""
+        ...
+
+    def set_boot_option(self, option: "BootOption | int") -> None:
+        """Set the disc's ``*OPT 4`` boot option."""
+        ...
+
+
+@runtime_checkable
+class FreeSpace(Protocol):
+    """The filesystem reports its free space (ADFS, AFS)."""
+
+    def free_bytes(self) -> int:
+        """Free space remaining, in bytes."""
+        ...
+
+
+@runtime_checkable
+class Sized(Protocol):
+    """The filesystem reports its own occupied size (its partition's span)."""
+
+    def size_bytes(self) -> int:
+        """The size of this filesystem's partition, in bytes.
+
+        For a filesystem sharing a disc (ADFS with an AFS tail) this is
+        its slice, not the whole image — so partition sizes sum to the
+        disc.
+        """
+        ...
+
+
+@dataclass(frozen=True)
+class DiscGeometry:
+    """A disc's physical geometry, for the ``stat`` summary.
+
+    *label* is a human description in the filesystem's own vocabulary
+    (ADFS speaks cylinders/heads/track; AFS speaks cylinders/sectors-per-
+    cylinder). *sectors_per_cylinder* lets the caller place a partition's
+    logical-sector span into a cylinder range without parsing the label.
+    """
+
+    label: str
+    sectors_per_cylinder: int
+    total_sectors: int
+
+
+@runtime_checkable
+class PhysicalGeometry(Protocol):
+    """The filesystem knows the disc's physical geometry (ADFS, AFS).
+
+    A flat-catalogue floppy filesystem (DFS) records no geometry and does
+    not advertise this.
+    """
+
+    def disc_geometry(self) -> DiscGeometry:
+        """The disc's physical geometry."""
+        ...
+
+
+@dataclass(frozen=True)
+class FreeMapData:
+    """A filesystem's free space as partition-relative sector runs.
+
+    Carries no geometry: the renderer lays the *total_sectors* out as a
+    sector matrix sized to the terminal, marking those in *free_regions*
+    free and the rest used. Each region is ``(start_sector, length)``.
+    """
+
+    free_regions: tuple[tuple[int, int], ...]
+    total_sectors: int
+
+
+@runtime_checkable
+class FreeMap(Protocol):
+    """The filesystem can report which of its sectors are free."""
+
+    def free_map(self) -> FreeMapData:
+        """The free-space map as partition-relative sector runs."""
+        ...
+
+
+@runtime_checkable
+class Compactable(Protocol):
+    """The filesystem can defragment in place, consolidating free space."""
+
+    def compact(self) -> int:
+        """Defragment, returning a filesystem-defined measure of work done."""
+        ...
+
+
+@runtime_checkable
+class Validatable(Protocol):
+    """The filesystem can check its on-disc structure for defects."""
+
+    def validate(self) -> list:
+        """Return a list of structural defects (empty when clean).
+
+        The entries are the filesystem's own validation-error objects,
+        rendered by the CLI's error formatter; the caller treats them
+        opaquely.
+        """
+        ...
+
+
+@runtime_checkable
+class UserDatabase(Protocol):
+    """The filesystem has user accounts (AFS passwords / quota)."""
+
+    def user_names(self) -> tuple[str, ...]:
+        """The names of the registered users."""
+        ...
+
+
+@runtime_checkable
+class RegionHost(Protocol):
+    """The filesystem reserves regions another filesystem may occupy.
+
+    An ADFS host reserves tail cylinders that an AFS or (DRDOS) FAT
+    filesystem lives in; the coordinator recurses into these. The host
+    stays ignorant of *what* occupies them.
+    """
+
+    def reserved_regions(self) -> tuple["Partition", ...]:
+        """The regions reserved within this filesystem, for recursion."""
+        ...

oaknut/filesystem/coordinator.py

@@ -0,0 +1,197 @@
+"""The identification cascade: run every registered filesystem, recurse, rank.
+
+:func:`identify` probes an image with every filesystem on the
+``oaknut.filesystem`` axis, recurses into the regions a host filesystem
+reserves (an ADFS tail), and returns the candidates for the whole image
+ranked best-first — each carrying its recursively-identified
+``contained`` partitions. It depends on no concrete filesystem package;
+discovery is purely by entry point, so any subset can be installed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+import stevedore
+from oaknut.discimage import BYTES_PER_SECTOR
+from oaknut.extension import (
+    create_extension,
+    describe_extension,
+    list_extensions,
+    load_failure_callback,
+)
+from oaknut.filesystem.exceptions import FilesystemExtensionError
+from oaknut.filesystem.filesystem import (
+    FILESYSTEM_KIND,
+    FILESYSTEM_NAMESPACE,
+    Filesystem,
+)
+from oaknut.filesystem.geometry import Geometry, region_reader
+from oaknut.filesystem.identification import Confidence, Identification, Partition
+from oaknut.filesystem.reader import ImageReader, ImageSource, reader_for
+
+__all__ = [
+    "identify",
+    "filesystem_names",
+    "describe_filesystem",
+    "create_filesystem",
+    "creating_filesystem",
+]
+
+
+def filesystem_names() -> list[str]:
+    """The entry-point names of every registered filesystem."""
+    return list_extensions(FILESYSTEM_NAMESPACE)
+
+
+def describe_filesystem(name: str, *, single_line: bool = False) -> str:
+    """The description of one filesystem (its class docstring)."""
+    return describe_extension(
+        FILESYSTEM_KIND,
+        FILESYSTEM_NAMESPACE,
+        name,
+        FilesystemExtensionError,
+        single_line=single_line,
+    )
+
+
+def create_filesystem(name: str) -> Filesystem:
+    """Instantiate one filesystem by name."""
+    return create_extension(
+        kind=FILESYSTEM_KIND,
+        namespace=FILESYSTEM_NAMESPACE,
+        name=name,
+        exception_type=FilesystemExtensionError,
+    )
+
+
+def creating_filesystem(
+    suffix: str, *, filesystems: dict[str, Filesystem] | None = None
+) -> str | None:
+    """The filesystem that creates *suffix* images by default, or ``None``.
+
+    ``disc create`` infers the filesystem from the target's extension via
+    each filesystem's ``creates`` set. Returns ``None`` when no installed
+    filesystem is the default creator for the extension (so the user must
+    pass ``--filesystem``).
+    """
+    suffix = suffix.lower()
+    active = _registered_filesystems() if filesystems is None else filesystems
+    for name, filesystem in active.items():
+        if suffix in filesystem.creates:
+            return name
+    return None
+
+
+def _registered_filesystems() -> dict[str, Filesystem]:
+    """Instantiate every registered filesystem, keyed by entry-point name."""
+    manager = stevedore.ExtensionManager(
+        namespace=FILESYSTEM_NAMESPACE,
+        invoke_on_load=False,
+        on_load_failure_callback=load_failure_callback,
+    )
+    return {ext.name: ext.plugin(name=ext.name) for ext in manager}
+
+
+def identify(
+    source: ImageSource,
+    *,
+    suffix_hint: str | None = None,
+    filesystems: dict[str, Filesystem] | None = None,
+) -> list[Identification]:
+    """Identify the filesystem(s) on *source*, best candidate first.
+
+    Returns the whole-image candidates ranked by confidence (extension
+    only a tie-breaker), each with its reserved regions recursively
+    identified in :attr:`Identification.contained`. An empty list means
+    no installed filesystem recognised the image.
+
+    *filesystems* overrides the discovered set — used by tests and to
+    simulate a partial install (the extensibility invariant).
+    """
+    with reader_for(source, suffix_hint=suffix_hint) as reader:
+        active = _registered_filesystems() if filesystems is None else filesystems
+        candidates = _probe_region(reader, active, reader.suffix)
+        whole = Partition(name="", start_sector=0, num_sectors=reader.size // BYTES_PER_SECTOR)
+        return [replace(c, partition=replace(whole, name=c.filesystem)) for c in candidates]
+
+
+def _probe_region(
+    reader: ImageReader, filesystems: dict[str, Filesystem], suffix: str | None
+) -> list[Identification]:
+    """Ranked candidates for the region in *reader*, recursion attached."""
+    candidates: list[Identification] = []
+    for filesystem in filesystems.values():
+        identification = filesystem.probe(reader)
+        if identification is None:
+            continue
+        if identification.reserved_regions:
+            identification = identification.with_contained(
+                _recurse_regions(
+                    identification.reserved_regions,
+                    reader,
+                    identification.geometry,
+                    filesystems,
+                )
+            )
+        candidates.append(identification)
+    return _rank(candidates, filesystems, suffix)
+
+
+def _recurse_regions(
+    regions: tuple[Partition, ...],
+    reader: ImageReader,
+    geometry: Geometry | None,
+    filesystems: dict[str, Filesystem],
+) -> tuple[Identification, ...]:
+    """Identify each reserved region; name partitions by what's found there.
+
+    Each region is read through the host's geometry (de-interleaved when
+    the host is an interleaved floppy) so the tail filesystem sees a
+    contiguous logical view.
+    """
+    contained: list[Identification] = []
+    counts: dict[str, int] = {}
+    for region in regions:
+        sub_reader = region_reader(reader, geometry, region.start_sector, region.num_sectors)
+        sub = _probe_region(sub_reader, filesystems, None)
+        if sub:
+            name = sub[0].filesystem
+            index = counts.get(name, 0)
+            counts[name] = index + 1
+            contained.append(replace(sub[0], partition=replace(region, name=name, index=index)))
+        else:
+            index = counts.get("", 0)
+            counts[""] = index + 1
+            contained.append(
+                Identification(
+                    filesystem="",
+                    confidence=Confidence.POSSIBLE,
+                    evidence=("reserved region; no installed filesystem recognised it",),
+                    partition=replace(region, name="", index=index),
+                )
+            )
+    return tuple(contained)
+
+
+def _rank(
+    candidates: list[Identification],
+    filesystems: dict[str, Filesystem],
+    suffix: str | None,
+) -> list[Identification]:
+    """Order *candidates* best-first: confidence, then extension, then priority."""
+
+    def extension_agrees(identification: Identification) -> bool:
+        filesystem = filesystems.get(identification.filesystem)
+        return bool(suffix and filesystem and suffix in filesystem.extensions)
+
+    def priority(identification: Identification) -> int:
+        filesystem = filesystems.get(identification.filesystem)
+        return filesystem.priority if filesystem is not None else 0
+
+    ordered = sorted(candidates, key=lambda i: i.filesystem)
+    ordered.sort(
+        key=lambda i: (int(i.confidence), extension_agrees(i), priority(i)),
+        reverse=True,
+    )
+    return ordered

oaknut/filesystem/exceptions.py

@@ -0,0 +1,35 @@
+"""Exceptions for the filesystem contract."""
+
+from __future__ import annotations
+
+from oaknut.exception import DataError, ExitCode
+from oaknut.extension import ExtensionError
+
+
+class FilesystemError(DataError):
+    """Base for errors raised by the oaknut filesystem layer."""
+
+
+class GeometryError(FilesystemError):
+    """A geometry specification could not be parsed, or is invalid."""
+
+
+class ReadOnlyFilesystemError(FilesystemError):
+    """A mutating operation was attempted on a read-only mount.
+
+    Raised by a :class:`~oaknut.filesystem.Mount` whose backing
+    filesystem cannot be written (a ZIP archive, say). Carries the
+    "operation not permitted" exit code so the CLI reports a clear
+    refusal rather than a generic data error.
+    """
+
+    _exit_code = ExitCode.NO_PERM
+
+
+class FilesystemExtensionError(ExtensionError):
+    """A filesystem extension could not be discovered or loaded.
+
+    A missing or mis-registered filesystem plug-in is an environment
+    problem, so this inherits the configuration exit code via
+    :class:`~oaknut.extension.ExtensionError`.
+    """