oaknut-file
Acorn file metadata handling for the oaknut package family.
oaknut-file is the shared metadata layer used across the
oaknut family — by
oaknut-dfs, oaknut-adfs, oaknut-afs, oaknut-zip, and the disc
CLI. It provides:
- The
AccessIntFlag enum for Acorn file attribute bytes - The
AcornMetadataclass 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.*anduser.econet_*
Installation
Using uv (recommended):
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.
from oaknut.file import Access
# Compose flags with bitwise OR
flags = Access.R | Access.W | Access.L
print(repr(flags)) # <Access.LWR: 11>
print(hex(flags)) # 0xb
| Flag | Value | Meaning |
|---|---|---|
Access.R |
0x01 | Owner read |
Access.W |
0x02 | Owner write |
Access.E |
0x04 | Execute only |
Access.L |
0x08 | Locked — prevents delete, overwrite, and rename on the disc filing systems |
Access.PR |
0x10 | Public read |
Access.PW |
0x20 | Public write |
Access.X |
0x40 | *RUN-only — may be *RUN but not *LOADed (CFS/ROMFS copy protection) |
Access.X (*RUN-only) is a distinct axis from Access.L (locked):
X is the cassette/ROM copy-protection bit and does not map to or from
the disc filing systems' delete-lock. Access.WR and Access.LWR are
provided as convenience composites for the common owner-read+write and
locked-owner-read+write cases.
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.
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_address=0x1900,
exec_address=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_address=0xFFFFDD00,
exec_address=0xFFFFDD00,
attr=int(Access.R | Access.W | Access.L | Access.PR),
)
print(pieb)
# 0 ffffdd00 ffffdd00 1b
# Auto-detect format on parse (returns (source_label, AcornMeta))
source, meta = parse_inf_line(trad)
print(meta.load_address, meta.exec_address, meta.access)
# 6400 32803 3
source, meta = parse_inf_line(pieb)
print(hex(meta.load_address), hex(meta.access), hex(meta.infer_filetype()))
# 0xffffdd00 0x1b 0xfdd
Filename metadata encoding
Three filename suffix conventions are supported for embedding load/exec addresses or RISC OS filetypes in host filenames.
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, hex(meta.load_address), hex(meta.exec_address))
# PROG 0x1900 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.
from oaknut.file import AcornMeta
meta = AcornMeta(load_address=0xFFFF0E10)
print(meta.is_filetype_stamped, hex(meta.infer_filetype()))
# True 0xf0e
Extended attributes
from oaknut.file import write_acorn_xattrs, read_acorn_xattrs
# Write to user.acorn.* namespace
write_acorn_xattrs(
"myfile.bin",
load_address=0x1900,
exec_address=0x8023,
attr=0x03,
)
# Read back (falls through to user.econet_* if user.acorn.* is absent)
meta = read_acorn_xattrs("myfile.bin")
print(meta.load_address, meta.exec_address, meta.access)
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file oaknut_file-12.12.0.tar.gz.
File metadata
- Download URL: oaknut_file-12.12.0.tar.gz
- Upload date:
- Size: 40.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ee1d8000e3043c06a005f834ec2e2ae98546091ea769c257d8611e28c898b59d
|
|
| MD5 |
e390d97f9bc197280da6afd9399b2892
|
|
| BLAKE2b-256 |
042edc9b80b1b363760a2b2c6486f758b48b44ce23a693af46bb28dafe5c8e0d
|
File details
Details for the file oaknut_file-12.12.0-py3-none-any.whl.
File metadata
- Download URL: oaknut_file-12.12.0-py3-none-any.whl
- Upload date:
- Size: 33.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
34db3dc029d4d2fffe90a181c2ed2893ce2dffad6f95c9e9f2f1d3412f2d9617
|
|
| MD5 |
b25f16987c9f0fca65ec927c091f2bac
|
|
| BLAKE2b-256 |
b3b916a3c092461bcaff8ec981ea1d05b7b5f9009b3e500876c49359dd3b5f70
|
