oaknut-file 1.0.0__tar.gz

oaknut_file-1.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_file-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: oaknut-file
+Version: 1.0.0
+Summary: Acorn file metadata handling: INF sidecars, filename encoding, xattrs, and access flags
+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: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xattr>=1.0; sys_platform == "darwin"
+Dynamic: license-file
+
+# oaknut-file
+
+[![PyPI version](https://img.shields.io/pypi/v/oaknut-file.svg)](https://pypi.org/project/oaknut-file/)
+[![CI](https://github.com/rob-smallshire/oaknut-file/actions/workflows/tests.yml/badge.svg)](https://github.com/rob-smallshire/oaknut-file/actions/workflows/tests.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/oaknut-file.svg)](https://pypi.org/project/oaknut-file/)
+[![License: MIT](https://img.shields.io/pypi/l/oaknut-file.svg)](https://github.com/rob-smallshire/oaknut-file/blob/master/LICENSE)
+
+Acorn file metadata handling for the oaknut package family.
+
+`oaknut-file` is the shared metadata layer used by
+[`oaknut-zip`](https://github.com/rob-smallshire/oaknut-zip) and
+[`oaknut-dfs`](https://github.com/rob-smallshire/oaknut-dfs). It provides:
+
+- The `Access` IntFlag enum for Acorn file attribute bytes
+- The `AcornMeta` dataclass for load/exec addresses and attributes
+- INF sidecar file parsing and formatting (traditional and PiEconetBridge variants)
+- Filename metadata encoding (`,xxx`, `,llllllll,eeeeeeee`, `,load-exec`)
+- Extended attribute read/write under `user.acorn.*` and `user.econet_*`
+
+## Installation
+
+Using [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv add oaknut-file
+```
+
+`pip install oaknut-file` also works.
+
+The `xattr` package is automatically installed on macOS, where it is
+required for extended attribute support. Linux uses `os.setxattr` from
+the standard library and needs no additional dependency. Windows does
+not support extended attributes; the xattr functions will raise on use.
+
+## Quick start
+
+### Access flags
+
+The `Access` IntFlag enum represents the standard Acorn OSFILE attribute byte.
+Bit values match the filing system API convention used by PiEconetBridge and
+the `user.acorn.attr` extended attribute.
+
+```python
+from oaknut.file import Access
+
+# Compose flags with bitwise OR
+flags = Access.R | Access.W | Access.L
+print(repr(flags))   # <Access.R|W|L: 11>
+print(hex(flags))    # 0x0B
+```
+
+| Flag | Value | Meaning |
+|------|-------|---------|
+| `Access.R`  | 0x01 | Owner read |
+| `Access.W`  | 0x02 | Owner write |
+| `Access.E`  | 0x04 | Execute only |
+| `Access.L`  | 0x08 | Locked |
+| `Access.PR` | 0x10 | Public read |
+| `Access.PW` | 0x20 | Public write |
+
+### INF sidecar files
+
+Two INF sidecar formats are supported. `parse_inf_line()` auto-detects which
+format a line uses, while `format_trad_inf_line()` and `format_pieb_inf_line()`
+let you choose explicitly when writing.
+
+```python
+from oaknut.file import (
+    Access, format_trad_inf_line, format_pieb_inf_line, parse_inf_line,
+)
+
+# Traditional INF: filename load exec length [attr]
+trad = format_trad_inf_line(
+    filename="HELLO",
+    load_addr=0x1900,
+    exec_addr=0x8023,
+    length=0x100,
+    attr=int(Access.R | Access.W),
+)
+print(trad)
+# HELLO       00001900 00008023 00000100 03
+
+# PiEconetBridge INF: owner load exec perm
+pieb = format_pieb_inf_line(
+    load_addr=0xFFFFDD00,
+    exec_addr=0xFFFFDD00,
+    attr=int(Access.R | Access.W | Access.L | Access.PR),
+)
+print(pieb)
+# 0 ffffdd00 ffffdd00 1b
+
+# Auto-detect format on parse
+source, meta = parse_inf_line(trad)
+print(meta)
+# AcornMeta(load_addr=0x1900, exec_addr=0x8023, attr=0x03)
+
+source, meta = parse_inf_line(pieb)
+print(meta)
+# AcornMeta(load_addr=0xFFFFDD00, exec_addr=0xFFFFDD00, attr=0x1B, filetype=0xFDD)
+```
+
+### Filename metadata encoding
+
+Three filename suffix conventions are supported for embedding load/exec
+addresses or RISC OS filetypes in host filenames.
+
+```python
+from oaknut.file import parse_encoded_filename
+
+# RISC OS filetype suffix (3 hex digits)
+clean, meta = parse_encoded_filename("PROG,ffb")
+print(clean, meta.infer_filetype())
+# ('PROG', filetype=0xFFB)
+
+# MOS load-exec suffix (variable-width hex)
+clean, meta = parse_encoded_filename("PROG,1900-801f")
+print(clean, meta.load_addr, meta.exec_addr)
+# ('PROG', load_addr=0x1900, exec_addr=0x801F)
+```
+
+### Filetype-stamped load addresses
+
+When a load address has its top 12 bits set to `0xFFF`, the next 12 bits
+encode a RISC OS filetype.
+
+```python
+from oaknut.file import AcornMeta
+
+meta = AcornMeta(load_addr=0xFFFF0E10)
+print(meta.is_filetype_stamped, hex(meta.infer_filetype()))
+# is_filetype_stamped=True, infer_filetype()=0xF0E
+```
+
+### Extended attributes
+
+```python
+from oaknut.file import write_acorn_xattrs, read_acorn_xattrs
+
+# Write to user.acorn.* namespace
+write_acorn_xattrs(
+    "myfile.bin",
+    load_addr=0x1900,
+    exec_addr=0x8023,
+    attr=0x03,
+)
+
+# Read back (falls through to user.econet_* if user.acorn.* is absent)
+meta = read_acorn_xattrs("myfile.bin")
+print(meta.load_addr, meta.exec_addr, meta.attr)
+```
+
+## Public API
+
+| Module | Exports |
+|--------|---------|
+| `oaknut.file.access` | `Access`, `format_access_hex`, `format_access_text` |
+| `oaknut.file.meta` | `AcornMeta` |
+| `oaknut.file.formats` | `MetaFormat`, `SOURCE_*` labels |
+| `oaknut.file.inf` | `parse_inf_line`, `format_trad_inf_line`, `format_pieb_inf_line`, `read_inf_file`, `write_inf_file` |
+| `oaknut.file.filename_encoding` | `parse_encoded_filename`, `build_filename_suffix`, `build_mos_filename_suffix` |
+| `oaknut.file.xattr` | `read_acorn_xattrs`, `write_acorn_xattrs`, `read_econet_xattrs`, `write_econet_xattrs` |
+
+All public symbols are also re-exported from the top-level `oaknut.file` package.
+
+## License
+
+MIT

oaknut_file-1.0.0/README.md

@@ -0,0 +1,167 @@
+# oaknut-file
+
+[![PyPI version](https://img.shields.io/pypi/v/oaknut-file.svg)](https://pypi.org/project/oaknut-file/)
+[![CI](https://github.com/rob-smallshire/oaknut-file/actions/workflows/tests.yml/badge.svg)](https://github.com/rob-smallshire/oaknut-file/actions/workflows/tests.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/oaknut-file.svg)](https://pypi.org/project/oaknut-file/)
+[![License: MIT](https://img.shields.io/pypi/l/oaknut-file.svg)](https://github.com/rob-smallshire/oaknut-file/blob/master/LICENSE)
+
+Acorn file metadata handling for the oaknut package family.
+
+`oaknut-file` is the shared metadata layer used by
+[`oaknut-zip`](https://github.com/rob-smallshire/oaknut-zip) and
+[`oaknut-dfs`](https://github.com/rob-smallshire/oaknut-dfs). It provides:
+
+- The `Access` IntFlag enum for Acorn file attribute bytes
+- The `AcornMeta` dataclass for load/exec addresses and attributes
+- INF sidecar file parsing and formatting (traditional and PiEconetBridge variants)
+- Filename metadata encoding (`,xxx`, `,llllllll,eeeeeeee`, `,load-exec`)
+- Extended attribute read/write under `user.acorn.*` and `user.econet_*`
+
+## Installation
+
+Using [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv add oaknut-file
+```
+
+`pip install oaknut-file` also works.
+
+The `xattr` package is automatically installed on macOS, where it is
+required for extended attribute support. Linux uses `os.setxattr` from
+the standard library and needs no additional dependency. Windows does
+not support extended attributes; the xattr functions will raise on use.
+
+## Quick start
+
+### Access flags
+
+The `Access` IntFlag enum represents the standard Acorn OSFILE attribute byte.
+Bit values match the filing system API convention used by PiEconetBridge and
+the `user.acorn.attr` extended attribute.
+
+```python
+from oaknut.file import Access
+
+# Compose flags with bitwise OR
+flags = Access.R | Access.W | Access.L
+print(repr(flags))   # <Access.R|W|L: 11>
+print(hex(flags))    # 0x0B
+```
+
+| Flag | Value | Meaning |
+|------|-------|---------|
+| `Access.R`  | 0x01 | Owner read |
+| `Access.W`  | 0x02 | Owner write |
+| `Access.E`  | 0x04 | Execute only |
+| `Access.L`  | 0x08 | Locked |
+| `Access.PR` | 0x10 | Public read |
+| `Access.PW` | 0x20 | Public write |
+
+### INF sidecar files
+
+Two INF sidecar formats are supported. `parse_inf_line()` auto-detects which
+format a line uses, while `format_trad_inf_line()` and `format_pieb_inf_line()`
+let you choose explicitly when writing.
+
+```python
+from oaknut.file import (
+    Access, format_trad_inf_line, format_pieb_inf_line, parse_inf_line,
+)
+
+# Traditional INF: filename load exec length [attr]
+trad = format_trad_inf_line(
+    filename="HELLO",
+    load_addr=0x1900,
+    exec_addr=0x8023,
+    length=0x100,
+    attr=int(Access.R | Access.W),
+)
+print(trad)
+# HELLO       00001900 00008023 00000100 03
+
+# PiEconetBridge INF: owner load exec perm
+pieb = format_pieb_inf_line(
+    load_addr=0xFFFFDD00,
+    exec_addr=0xFFFFDD00,
+    attr=int(Access.R | Access.W | Access.L | Access.PR),
+)
+print(pieb)
+# 0 ffffdd00 ffffdd00 1b
+
+# Auto-detect format on parse
+source, meta = parse_inf_line(trad)
+print(meta)
+# AcornMeta(load_addr=0x1900, exec_addr=0x8023, attr=0x03)
+
+source, meta = parse_inf_line(pieb)
+print(meta)
+# AcornMeta(load_addr=0xFFFFDD00, exec_addr=0xFFFFDD00, attr=0x1B, filetype=0xFDD)
+```
+
+### Filename metadata encoding
+
+Three filename suffix conventions are supported for embedding load/exec
+addresses or RISC OS filetypes in host filenames.
+
+```python
+from oaknut.file import parse_encoded_filename
+
+# RISC OS filetype suffix (3 hex digits)
+clean, meta = parse_encoded_filename("PROG,ffb")
+print(clean, meta.infer_filetype())
+# ('PROG', filetype=0xFFB)
+
+# MOS load-exec suffix (variable-width hex)
+clean, meta = parse_encoded_filename("PROG,1900-801f")
+print(clean, meta.load_addr, meta.exec_addr)
+# ('PROG', load_addr=0x1900, exec_addr=0x801F)
+```
+
+### Filetype-stamped load addresses
+
+When a load address has its top 12 bits set to `0xFFF`, the next 12 bits
+encode a RISC OS filetype.
+
+```python
+from oaknut.file import AcornMeta
+
+meta = AcornMeta(load_addr=0xFFFF0E10)
+print(meta.is_filetype_stamped, hex(meta.infer_filetype()))
+# is_filetype_stamped=True, infer_filetype()=0xF0E
+```
+
+### Extended attributes
+
+```python
+from oaknut.file import write_acorn_xattrs, read_acorn_xattrs
+
+# Write to user.acorn.* namespace
+write_acorn_xattrs(
+    "myfile.bin",
+    load_addr=0x1900,
+    exec_addr=0x8023,
+    attr=0x03,
+)
+
+# Read back (falls through to user.econet_* if user.acorn.* is absent)
+meta = read_acorn_xattrs("myfile.bin")
+print(meta.load_addr, meta.exec_addr, meta.attr)
+```
+
+## Public API
+
+| Module | Exports |
+|--------|---------|
+| `oaknut.file.access` | `Access`, `format_access_hex`, `format_access_text` |
+| `oaknut.file.meta` | `AcornMeta` |
+| `oaknut.file.formats` | `MetaFormat`, `SOURCE_*` labels |
+| `oaknut.file.inf` | `parse_inf_line`, `format_trad_inf_line`, `format_pieb_inf_line`, `read_inf_file`, `write_inf_file` |
+| `oaknut.file.filename_encoding` | `parse_encoded_filename`, `build_filename_suffix`, `build_mos_filename_suffix` |
+| `oaknut.file.xattr` | `read_acorn_xattrs`, `write_acorn_xattrs`, `read_econet_xattrs`, `write_econet_xattrs` |
+
+All public symbols are also re-exported from the top-level `oaknut.file` package.
+
+## License
+
+MIT

oaknut_file-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-file"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Acorn file metadata handling: INF sidecars, filename encoding, xattrs, and access flags"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Filesystems",
+]
+dependencies = [
+    "xattr>=1.0; sys_platform == 'darwin'",
+]
+
+[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",
+    "jinja2>=3.0",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.file.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.bumpversion]
+current_version = "1.0.0"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+tag = true
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+tag_name = "oaknut-file-v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+files = [
+    { filename = "src/oaknut/file/__init__.py" },
+]

oaknut_file-1.0.0/setup.cfg

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

oaknut_file-1.0.0/src/oaknut/file/__init__.py

@@ -0,0 +1,62 @@
+"""Acorn file metadata handling.
+
+Shared metadata layer for the oaknut package family: INF sidecar
+parsing/formatting, filename encoding schemes, extended attributes,
+and access flag management.
+"""
+
+__version__ = "1.0.0"
+
+from oaknut.file.access import Access, format_access_hex, format_access_text
+from oaknut.file.filename_encoding import (
+    build_filename_suffix,
+    build_mos_filename_suffix,
+    parse_encoded_filename,
+)
+from oaknut.file.formats import (
+    SOURCE_DIR,
+    SOURCE_FILENAME,
+    SOURCE_INF_PIEB,
+    SOURCE_INF_TRAD,
+    SOURCE_SPARKFS,
+    MetaFormat,
+)
+from oaknut.file.inf import (
+    format_pieb_inf_line,
+    format_trad_inf_line,
+    parse_inf_line,
+    read_inf_file,
+    write_inf_file,
+)
+from oaknut.file.meta import AcornMeta
+from oaknut.file.xattr import (
+    read_acorn_xattrs,
+    read_econet_xattrs,
+    write_acorn_xattrs,
+    write_econet_xattrs,
+)
+
+__all__ = [
+    "Access",
+    "AcornMeta",
+    "MetaFormat",
+    "SOURCE_DIR",
+    "SOURCE_FILENAME",
+    "SOURCE_INF_PIEB",
+    "SOURCE_INF_TRAD",
+    "SOURCE_SPARKFS",
+    "build_filename_suffix",
+    "build_mos_filename_suffix",
+    "format_access_hex",
+    "format_access_text",
+    "format_pieb_inf_line",
+    "format_trad_inf_line",
+    "parse_encoded_filename",
+    "parse_inf_line",
+    "read_acorn_xattrs",
+    "read_econet_xattrs",
+    "read_inf_file",
+    "write_acorn_xattrs",
+    "write_econet_xattrs",
+    "write_inf_file",
+]

oaknut_file-1.0.0/src/oaknut/file/access.py

@@ -0,0 +1,68 @@
+"""Acorn file access attributes.
+
+The ``Access`` IntFlag enum represents the standard Acorn OSFILE
+attribute byte. Bit values match the filing system API convention,
+ensuring compatibility with PiEconetBridge ``perm`` and the
+``user.acorn.attr`` extended attribute.
+"""
+
+from __future__ import annotations
+
+from enum import IntFlag
+
+
+class Access(IntFlag):
+    """Acorn file access attributes.
+
+    Composable with ``|``::
+
+        Access.R | Access.W | Access.L
+        Access.R | Access.W | Access.PR  # with public read
+
+    The integer value of a combination is the standard Acorn
+    attribute byte, suitable for storage in xattrs or INF files::
+
+        int(Access.R | Access.W)  # 0x03
+    """
+
+    R  = 0x01  # Owner read
+    W  = 0x02  # Owner write
+    E  = 0x04  # Execute only
+    L  = 0x08  # Locked (prevents delete, overwrite, rename)
+    PR = 0x10  # Public read
+    PW = 0x20  # Public write
+
+
+def format_access_hex(attr: int | None) -> str:
+    """Format an attribute byte as a two-digit uppercase hex string.
+
+    Returns empty string for None.
+    """
+    if attr is None:
+        return ""
+    return f"{attr:02X}"
+
+
+def format_access_text(attr: int | None) -> str:
+    """Format attributes as a human-readable access string.
+
+    Returns ``"owner/public"`` form, e.g. ``"LWR/R"``.
+    """
+    if attr is None:
+        return "/"
+
+    owner = ""
+    if attr & Access.L:
+        owner += "L"
+    if attr & Access.W:
+        owner += "W"
+    if attr & Access.R:
+        owner += "R"
+
+    public = ""
+    if attr & Access.PW:
+        public += "W"
+    if attr & Access.PR:
+        public += "R"
+
+    return f"{owner}/{public}"

oaknut_file-1.0.0/src/oaknut/file/filename_encoding.py

@@ -0,0 +1,73 @@
+"""Filename metadata encoding schemes.
+
+Three conventions for encoding Acorn file metadata in host filenames:
+
+- **RISC OS filetype**: ``filename,xxx`` (3-digit hex filetype)
+- **RISC OS load/exec**: ``filename,llllllll,eeeeeeee`` (8+8 digit hex)
+- **MOS load/exec**: ``filename,load-exec`` (variable-width hex)
+"""
+
+from __future__ import annotations
+
+import re
+
+from oaknut.file.meta import AcornMeta
+
+# Regex patterns for each encoding scheme
+SUFFIX_FILETYPE_RE = re.compile(r"^(.*),([0-9a-fA-F]{3})$")
+SUFFIX_LOADEXEC_RE = re.compile(r"^(.*),([0-9a-fA-F]{8}),([0-9a-fA-F]{8})$")
+SUFFIX_MOS_LOADEXEC_RE = re.compile(r"^(.*),([0-9a-fA-F]{1,8})-([0-9a-fA-F]{1,8})$")
+
+
+def parse_encoded_filename(filename: str) -> tuple[str, AcornMeta | None]:
+    """Strip metadata suffix from a filename.
+
+    Tries each encoding scheme in order: RISC OS load/exec,
+    MOS load/exec, filetype. Returns ``(clean_filename, metadata)``
+    where *metadata* is ``None`` if no encoding was found.
+    """
+    # Try RISC OS load/exec first (most specific: 8+8 digits)
+    m = SUFFIX_LOADEXEC_RE.match(filename)
+    if m:
+        load_addr = int(m.group(2), 16)
+        exec_addr = int(m.group(3), 16)
+        return m.group(1), AcornMeta(load_addr=load_addr, exec_addr=exec_addr)
+
+    # Try MOS load/exec (variable-width with hyphen)
+    m = SUFFIX_MOS_LOADEXEC_RE.match(filename)
+    if m:
+        load_addr = int(m.group(2), 16)
+        exec_addr = int(m.group(3), 16)
+        return m.group(1), AcornMeta(load_addr=load_addr, exec_addr=exec_addr)
+
+    # Try filetype (3-digit hex)
+    m = SUFFIX_FILETYPE_RE.match(filename)
+    if m:
+        filetype = int(m.group(2), 16)
+        # Synthesise a RISC OS load address from the filetype
+        load_addr = 0xFFF00000 | (filetype << 8)
+        return m.group(1), AcornMeta(
+            load_addr=load_addr, exec_addr=0, filetype=filetype,
+        )
+
+    return filename, None
+
+
+def build_filename_suffix(meta: AcornMeta) -> str:
+    """Build a RISC OS filename encoding suffix.
+
+    Returns ``,xxx`` for filetype-stamped files, or
+    ``,llllllll,eeeeeeee`` for literal load/exec addresses.
+    """
+    if meta.is_filetype_stamped:
+        ft = meta.infer_filetype()
+        return f",{ft:03x}"
+    return f",{meta.load_addr:08x},{meta.exec_addr:08x}"
+
+
+def build_mos_filename_suffix(meta: AcornMeta) -> str:
+    """Build a MOS filename encoding suffix.
+
+    Returns ``,load-exec`` with variable-width lowercase hex.
+    """
+    return f",{meta.load_addr:x}-{meta.exec_addr:x}"

oaknut_file-1.0.0/src/oaknut/file/formats.py

@@ -0,0 +1,28 @@
+"""Metadata format and source labels.
+
+``MetaFormat`` enumerates the output formats for writing file metadata
+to the host filesystem. The ``SOURCE_*`` constants label where
+metadata was obtained from.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class MetaFormat(str, Enum):
+    """Supported metadata output formats."""
+
+    INF_TRAD = "inf-trad"
+    INF_PIEB = "inf-pieb"
+    XATTR_ACORN = "xattr-acorn"
+    XATTR_PIEB = "xattr-pieb"
+    FILENAME_RISCOS = "filename-riscos"
+    FILENAME_MOS = "filename-mos"
+
+
+SOURCE_SPARKFS = "sparkfs"
+SOURCE_INF_TRAD = "inf-trad"
+SOURCE_INF_PIEB = "inf-pieb"
+SOURCE_FILENAME = "filename"
+SOURCE_DIR = "dir"