oaknut-filesystem 12.0.0__tar.gz

oaknut_filesystem-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_filesystem-12.0.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: oaknut-filesystem
+Version: 12.0.0
+Summary: The pluggable filesystem contract for the oaknut family: detection, capabilities, geometry, partitions, and the identification coordinator.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-filesystem
+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-discimage>=10.0
+Requires-Dist: oaknut-file>=10.0
+Dynamic: license-file
+
+# oaknut-filesystem
+
+The pluggable **filesystem contract** for the oaknut family — the base every
+Acorn (and, in principle, foreign) filesystem plugs into.
+
+A *filesystem* is the unit of extension: Acorn DFS, Watford DFS, Opus DDOS,
+ADFS, AFS, … are peers, registered on the `oaknut.filesystem` entry-point axis
+(built on `oaknut-extension`). Each one:
+
+- **probes** an image region and proposes what it is — with a confidence,
+  evidence, and a candidate *geometry*;
+- **opens** a region into a mount exposing a small **core** (list / stat /
+  read / write / exists, and parsing its own path syntax) plus opt-in
+  **capability protocols** (`HierarchicalDirectories`, `AcornMetadata`,
+  `BootOption`, `UserDatabase`, `RegionHost`);
+- declares its **geometry grammar** — the physical layouts it supports.
+
+Two concerns are kept strictly apart:
+
+- **Geometry** — the *physical* mapping of image bytes to logical sectors
+  (track count, sides, interleave, density, CHS). This is the discimage
+  `DiscFormat` layer, *beneath* the filesystem.
+- **Filesystem** — the *logical* structure that turns sectors into files and
+  directories.
+
+This package also hosts the **identification coordinator** (`identify()`): it
+runs the registered filesystems over an image, ranks the candidates, and
+recurses into reserved regions (an ADFS host's tail, where an AFS or other
+filesystem may live) to produce a per-partition `Identification` tree.
+
+It depends on **no** concrete filesystem package and imports none: filesystems
+are discovered purely through entry points, so any subset can be installed and
+the rest simply aren't handled.
+
+See `docs/dev/filesystem-extensions.md` (architecture) and
+`docs/dev/filesystem-extensions-plan.md` (implementation plan).

oaknut_filesystem-12.0.0/README.md

@@ -0,0 +1,36 @@
+# oaknut-filesystem
+
+The pluggable **filesystem contract** for the oaknut family — the base every
+Acorn (and, in principle, foreign) filesystem plugs into.
+
+A *filesystem* is the unit of extension: Acorn DFS, Watford DFS, Opus DDOS,
+ADFS, AFS, … are peers, registered on the `oaknut.filesystem` entry-point axis
+(built on `oaknut-extension`). Each one:
+
+- **probes** an image region and proposes what it is — with a confidence,
+  evidence, and a candidate *geometry*;
+- **opens** a region into a mount exposing a small **core** (list / stat /
+  read / write / exists, and parsing its own path syntax) plus opt-in
+  **capability protocols** (`HierarchicalDirectories`, `AcornMetadata`,
+  `BootOption`, `UserDatabase`, `RegionHost`);
+- declares its **geometry grammar** — the physical layouts it supports.
+
+Two concerns are kept strictly apart:
+
+- **Geometry** — the *physical* mapping of image bytes to logical sectors
+  (track count, sides, interleave, density, CHS). This is the discimage
+  `DiscFormat` layer, *beneath* the filesystem.
+- **Filesystem** — the *logical* structure that turns sectors into files and
+  directories.
+
+This package also hosts the **identification coordinator** (`identify()`): it
+runs the registered filesystems over an image, ranks the candidates, and
+recurses into reserved regions (an ADFS host's tail, where an AFS or other
+filesystem may live) to produce a per-partition `Identification` tree.
+
+It depends on **no** concrete filesystem package and imports none: filesystems
+are discovered purely through entry points, so any subset can be installed and
+the rest simply aren't handled.
+
+See `docs/dev/filesystem-extensions.md` (architecture) and
+`docs/dev/filesystem-extensions-plan.md` (implementation plan).

oaknut_filesystem-12.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-filesystem"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "The pluggable filesystem contract for the oaknut family: detection, capabilities, geometry, partitions, and the identification coordinator."
+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-discimage>=10.0",
+    "oaknut-file>=10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-filesystem"
+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.filesystem.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_filesystem-12.0.0/setup.cfg

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

oaknut_filesystem-12.0.0/src/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-12.0.0/src/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."""
+        ...