oaknut-afs 10.0.1__tar.gz

oaknut_afs-10.0.1/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_afs-10.0.1/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: oaknut-afs
+Version: 10.0.1
+Summary: Acorn Level 3 File Server (AFS) filesystem support — the private on-disc format WFSINIT prepares in the tail of an old-map ADFS disc
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut
+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: Environment :: Console
+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-file>=10.0
+Requires-Dist: oaknut-discimage>=10.0
+Requires-Dist: oaknut-adfs>=10.0
+Dynamic: license-file
+
+# oaknut-afs
+
+Python library for reading and writing Acorn Level 3 File Server (AFS)
+disc partitions — the private on-disc filesystem that the Level 3 File
+Server serves to BBC Micro, Master, and Archimedes clients over Econet.
+
+AFS (identified by the `AFS0` magic in its info sectors) coexists with
+ADFS on the same disc: WFSINIT — or oaknut's `initialise()` — shrinks
+the ADFS partition and carves an AFS region out of the tail cylinders.
+
+Part of the [oaknut](https://github.com/rob-smallshire/oaknut) monorepo.

oaknut_afs-10.0.1/README.md

@@ -0,0 +1,11 @@
+# oaknut-afs
+
+Python library for reading and writing Acorn Level 3 File Server (AFS)
+disc partitions — the private on-disc filesystem that the Level 3 File
+Server serves to BBC Micro, Master, and Archimedes clients over Econet.
+
+AFS (identified by the `AFS0` magic in its info sectors) coexists with
+ADFS on the same disc: WFSINIT — or oaknut's `initialise()` — shrinks
+the ADFS partition and carves an AFS region out of the tail cylinders.
+
+Part of the [oaknut](https://github.com/rob-smallshire/oaknut) monorepo.

oaknut_afs-10.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-afs"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Acorn Level 3 File Server (AFS) filesystem support — the private on-disc format WFSINIT prepares in the tail of an old-map ADFS disc"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "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-file>=10.0",
+    "oaknut-discimage>=10.0",
+    "oaknut-adfs>=10.0",
+]
+
+[project.scripts]
+oaknut-afs-disc = "oaknut.afs.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut"
+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.afs.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_afs-10.0.1/setup.cfg

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

oaknut_afs-10.0.1/src/oaknut/afs/__init__.py

@@ -0,0 +1,95 @@
+"""Acorn Level 3 File Server (AFS) filesystem support.
+
+The Level 3 File Server's private on-disc filesystem, identified by
+the ``AFS0`` magic in its info sectors. An AFS region occupies the
+tail cylinders of an old-map ADFS hard-disc image; the ADFS partition
+at the front of the disc coexists with it.
+
+The ``A`` in ``AFS0`` most likely stands for *Acorn File Server*,
+though no primary source spells it out — the ``0`` is a format version.
+
+The full public API — read, write, merge, initialise, and CLI — is
+implemented. See ``docs/afs-implementation-plan.md`` for the design
+and ``docs/afs-onwire.md`` for the on-disc format specification.
+"""
+
+__version__ = "10.0.1"
+
+from oaknut.afs.access import AFSAccess
+from oaknut.afs.afs import AFS, AFSNotPresentError
+from oaknut.afs.allocator import Allocator
+from oaknut.afs.exceptions import (
+    AFSAccessDeniedError,
+    AFSAlreadyPartitionedError,
+    AFSBrokenDirectoryError,
+    AFSBrokenMapError,
+    AFSDirectoryEntryExistsError,
+    AFSDirectoryEntryNotFoundError,
+    AFSDirectoryFullError,
+    AFSDirectoryNotEmptyError,
+    AFSDiscNotCompactedError,
+    AFSError,
+    AFSFileLockedError,
+    AFSFormatError,
+    AFSHostImportError,
+    AFSInfoSectorError,
+    AFSInsufficientADFSSpaceError,
+    AFSInsufficientSpaceError,
+    AFSMergeConflictError,
+    AFSNewMapNotSupportedError,
+    AFSPathError,
+    AFSQuotaExceededError,
+    AFSRepartitionError,
+)
+from oaknut.afs.host_import import import_host_tree
+from oaknut.afs.libraries import SHIPPED_LIBRARIES, emplace_library
+from oaknut.afs.merge import merge
+from oaknut.afs.passwords import PasswordsFile, UserRecord
+from oaknut.afs.path import AFSPath
+from oaknut.afs.types import (
+    AfsDate,
+    Cylinder,
+    Geometry,
+    Sector,
+    SystemInternalName,
+)
+
+__all__ = [
+    "AFS",
+    "AFSAccess",
+    "AFSNotPresentError",
+    "AFSPath",
+    "Allocator",
+    "SHIPPED_LIBRARIES",
+    "emplace_library",
+    "PasswordsFile",
+    "UserRecord",
+    "import_host_tree",
+    "merge",
+    "AFSAccessDeniedError",
+    "AFSAlreadyPartitionedError",
+    "AFSBrokenDirectoryError",
+    "AFSBrokenMapError",
+    "AFSDirectoryEntryExistsError",
+    "AFSDirectoryEntryNotFoundError",
+    "AFSDirectoryFullError",
+    "AFSDirectoryNotEmptyError",
+    "AFSDiscNotCompactedError",
+    "AFSError",
+    "AFSFileLockedError",
+    "AFSFormatError",
+    "AFSHostImportError",
+    "AFSInfoSectorError",
+    "AFSInsufficientADFSSpaceError",
+    "AFSInsufficientSpaceError",
+    "AFSMergeConflictError",
+    "AFSNewMapNotSupportedError",
+    "AFSPathError",
+    "AFSQuotaExceededError",
+    "AFSRepartitionError",
+    "AfsDate",
+    "Cylinder",
+    "Geometry",
+    "Sector",
+    "SystemInternalName",
+]

oaknut_afs-10.0.1/src/oaknut/afs/access.py

@@ -0,0 +1,198 @@
+"""AFS on-disc access byte.
+
+The Level 3 File Server stores an object's access attributes in a
+single byte at offset 20 of its directory entry (see
+``docs/afs-onwire.md`` §Directory entry). The bit layout **differs**
+from the standard Acorn attribute byte used by client-side NFS/ANFS
+clients and by ``oaknut.file.Access``. Per ``Uade01.asm:257-275`` and
+Beebmaster's PDF:
+
+====  =========================
+Bit   Meaning
+====  =========================
+0     Public read
+1     Public write
+2     Owner read
+3     Owner write
+4     Locked
+5     Directory type (1 = dir)
+6-7   Unused on disc
+====  =========================
+
+Masks from the ROM:
+
+- ``ACCMSK = 0x1F`` — bits 0–4 (locked + all R/W bits)
+- ``TLAMSK = 0x3F`` — type + locked + all R/W bits
+- ``RWMSK  = 0x0F`` — owner + public R/W only
+
+The access string form used by Econet clients (``"LR/WR"``, ``"LWR/R"``,
+``"D/"``, etc.) is the same form users see in ``*EX`` listings and is
+documented in the Beebmaster PDF's "Example Access Strings" table. This
+module parses and formats that string.
+
+Conversions to and from the wire-format ``oaknut.file.Access`` (which
+uses a different bit layout) are provided so that ``host_bridge``
+metadata round-trips correctly.
+"""
+
+from __future__ import annotations
+
+from enum import IntFlag
+
+# ---------------------------------------------------------------------------
+# Bit positions — the on-disc layout.
+# ---------------------------------------------------------------------------
+
+_BIT_PUBLIC_READ = 0x01
+_BIT_PUBLIC_WRITE = 0x02
+_BIT_OWNER_READ = 0x04
+_BIT_OWNER_WRITE = 0x08
+_BIT_LOCKED = 0x10
+_BIT_DIRECTORY = 0x20
+
+
+class AFSAccess(IntFlag):
+    """On-disc AFS access byte.
+
+    The integer value of any combination is the byte stored in the
+    ``DRACCS`` field of a directory entry — it may be written straight
+    into a ``SectorsView`` without further translation::
+
+        entry_bytes[20] = int(AFSAccess.from_string("LR/R"))
+
+    Composable with ``|``::
+
+        AFSAccess.OWNER_READ | AFSAccess.OWNER_WRITE | AFSAccess.PUBLIC_READ
+    """
+
+    PUBLIC_READ = _BIT_PUBLIC_READ
+    PUBLIC_WRITE = _BIT_PUBLIC_WRITE
+    OWNER_READ = _BIT_OWNER_READ
+    OWNER_WRITE = _BIT_OWNER_WRITE
+    LOCKED = _BIT_LOCKED
+    DIRECTORY = _BIT_DIRECTORY
+
+    @classmethod
+    def from_byte(cls, value: int) -> AFSAccess:
+        """Build an ``AFSAccess`` from a raw access byte.
+
+        Unknown bits (6 and 7) are silently ignored, matching the
+        server's tolerance for junk in the unused bits.
+        """
+        return cls(value & 0x3F)
+
+    def to_byte(self) -> int:
+        """Return the raw access byte suitable for on-disc storage."""
+        return int(self) & 0x3F
+
+    # -----------------------------------------------------------------
+    # String form — "LWR/WR" style
+    # -----------------------------------------------------------------
+
+    def to_string(self) -> str:
+        """Format as the human-readable ``"owner/public"`` string.
+
+        Directory objects render as ``"D/"`` or ``"DL/"`` — consistent
+        with the server's ``*EX`` listings and with the Beebmaster PDF.
+        """
+        if self & AFSAccess.DIRECTORY:
+            owner = "D"
+            if self & AFSAccess.LOCKED:
+                owner += "L"
+            return f"{owner}/"
+
+        owner = ""
+        if self & AFSAccess.LOCKED:
+            owner += "L"
+        if self & AFSAccess.OWNER_WRITE:
+            owner += "W"
+        if self & AFSAccess.OWNER_READ:
+            owner += "R"
+
+        public = ""
+        if self & AFSAccess.PUBLIC_WRITE:
+            public += "W"
+        if self & AFSAccess.PUBLIC_READ:
+            public += "R"
+
+        return f"{owner}/{public}"
+
+    @classmethod
+    def from_string(cls, text: str) -> AFSAccess:
+        """Parse an ``"owner/public"`` access string.
+
+        Accepts the forms in the Beebmaster PDF's "Example Access
+        Strings" table:
+
+        - ``"/"`` — no access at all (byte 0x00)
+        - ``"L/"`` — locked, otherwise no access
+        - ``"LR/R"``, ``"LWR/WR"``, ``"WR/R"``, ``"R/"`` …
+        - ``"D/"``, ``"DL/"`` — directories (the access bits are ignored
+          for directories per the PDF; the server only honours locked)
+
+        Letters may appear in any order within each side, but the
+        forward slash is mandatory. Upper/lower case is accepted;
+        whitespace is not.
+        """
+        if "/" not in text:
+            raise ValueError(f"AFSAccess.from_string: missing '/' in {text!r}")
+
+        owner, public = text.split("/", 1)
+        owner = owner.upper()
+        public = public.upper()
+
+        result = cls(0)
+
+        # Directory: the 'D' prefix is recognised even though directories
+        # don't strictly use the R/W bits.
+        if "D" in owner:
+            result |= cls.DIRECTORY
+            # Directories may only be locked or unlocked; the server
+            # ignores R/W on a directory.
+            if "L" in owner:
+                result |= cls.LOCKED
+            _reject_unexpected(owner, "DL", text)
+            if public:
+                raise ValueError(
+                    f"AFSAccess.from_string: directories take no public access bits, got {text!r}"
+                )
+            return result
+
+        # File access.
+        if "L" in owner:
+            result |= cls.LOCKED
+        if "W" in owner:
+            result |= cls.OWNER_WRITE
+        if "R" in owner:
+            result |= cls.OWNER_READ
+        _reject_unexpected(owner, "LWR", text)
+
+        if "W" in public:
+            result |= cls.PUBLIC_WRITE
+        if "R" in public:
+            result |= cls.PUBLIC_READ
+        _reject_unexpected(public, "WR", text)
+
+        return result
+
+    # -----------------------------------------------------------------
+    # Type-checking helpers
+    # -----------------------------------------------------------------
+
+    @property
+    def is_directory(self) -> bool:
+        return bool(self & AFSAccess.DIRECTORY)
+
+    @property
+    def is_locked(self) -> bool:
+        return bool(self & AFSAccess.LOCKED)
+
+
+def _reject_unexpected(segment: str, allowed: str, original: str) -> None:
+    allowed_set = set(allowed)
+    unexpected = [c for c in segment if c not in allowed_set]
+    if unexpected:
+        raise ValueError(
+            f"AFSAccess.from_string: unexpected character(s) "
+            f"{''.join(unexpected)!r} in {original!r} (allowed: {allowed!r})"
+        )