oaknut-dfs
A Python library for reading, writing, and creating Acorn DFS floppy disc images, as used by the BBC Micro.
With oaknut-dfs you can open DFS floppy images (SSD/DSD) to browse the catalogue, read and write files, inspect metadata, and create new formatted discs — all from Python, with a pathlib-inspired API.
Looking for ADFS? The hierarchical Advanced Disc Filing System lives in the sibling
oaknut-adfspackage (from oaknut.adfs import ADFS). DFS and ADFS are independent filing systems and independent packages. For a unified command-line tool across DFS, ADFS, AFS, ROMFS and ZIP, seeoaknut-disc.
Part of the oaknut monorepo.
Supported formats
- Acorn DFS — 40-track and 80-track, single-sided (SSD) and double-sided (DSD)
- Watford DFS — extended catalogue supporting up to 62 files
- DSD interleaving — both interleaved and sequential double-sided layouts
Acorn load/exec addresses, the lock bit, and the BBC Micro character set
(the acorn text codec, £, ¦) are handled through the shared
oaknut-file
metadata layer.
Installation
uv add oaknut-dfs # or: pip install oaknut-dfs
oaknut-dfs is a standard Python package installable with any package
manager; the examples use uv.
Usage
Opening and reading files
The disc format is auto-detected from the file extension and size; pass a format explicitly only to override detection.
from oaknut.dfs import DFS
with DFS.from_file("Zalaga.ssd") as dfs:
print(dfs.title) # 'ZALAG-L'
# Navigate with a pathlib-inspired API.
for entry in dfs.root / "$":
s = entry.stat()
print(f"{entry.name:10s} {s.length:6d} load={s.load_address:08X}")
# Read file data.
data = (dfs.root / "$" / "ZALAGA").read_bytes()
Creating a new disc
from oaknut.dfs import DFS, ACORN_DFS_80T_SINGLE_SIDED
with DFS.create_file("demo.ssd", ACORN_DFS_80T_SINGLE_SIDED, title="DEMO") as dfs:
(dfs.root / "$.HELLO").write_bytes(b"Hello, World!", load_address=0x1900)
(dfs.root / "$.README").write_bytes(b"oaknut-dfs demo disc")
Double-sided discs (DSD)
A DSD image holds two independent sides, each with its own catalogue —
mirroring the BBC Micro, where the sides were accessed as separate drives
(*DRIVE 0 and *DRIVE 2). Select a side with the side= argument.
from oaknut.dfs import DFS
with DFS.from_file("game.dsd") as side0:
print(side0.title)
with DFS.from_file("game.dsd", side=1) as side2:
print(side2.title)
Walking the disc
DFS directories ($, A–Z) appear as children of a virtual root:
with DFS.from_file("disc.ssd") as dfs:
for dirpath, dirnames, filenames in dfs.root.walk():
for name in filenames:
print(dirpath / name)
Development
The package is developed in the oaknut workspace. From the repository root:
uv sync # install all workspace members editable
uv run pytest packages/oaknut-dfs/tests # this package's tests
uv run ruff check # lint
Architecture
A layered design, dependencies flowing strictly downward (every module imports only from the layer below):
DFS (dfs.py) user-facing DFS / DFSPath / DFSStat
↓
CataloguedSurface (catalogued_surface.py)
↓
Catalogue ABC (catalogue.py) ← AcornDFSCatalogue / WatfordDFSCatalogue
↓
Surface / SectorsView (from oaknut-discimage)
dfs.py— user-facingDFS,DFSPath,DFSStat; methods mirror the DFS star commands (load,save,delete,rename,lock, …).catalogue.py— the catalogue ABC (Catalogue,FileEntry,DiscInfo): 31-file cap, single-character directories, 7-char names.acorn_dfs_catalogue.py/watford_dfs_catalogue.py— the Acorn (sectors 0–1, 31 files) and Watford (sectors 0–3, 62 files) catalogues.catalogued_surface.py— pairs aSurfacewith aCatalogue.formats.py— DFS and Watford disc-format constants.
Sector-level access (Surface, SectorsView, UnifiedDisc) lives in
oaknut-discimage;
metadata and the acorn codec in oaknut-file; BBC BASIC
(de)tokenisation (for DFSPath.read_basic / write_basic) in
oaknut-basic.
References
- Acorn DFS disc format — BeebWiki specification for the catalogue layout.
- Disc Filing System — Wikipedia overview of DFS and its variants.
- DiscImageManager — Gerald Holdsworth's reference for DFS and other Acorn formats.
- INF file format —
the
.infsidecar metadata format.
License
MIT — see LICENSE.
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_dfs-12.13.1.tar.gz.
File metadata
- Download URL: oaknut_dfs-12.13.1.tar.gz
- Upload date:
- Size: 102.5 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 |
b838ebf80ac61836ccb419bd7e0bb166711dd9b7c2e9efdc94bead850a4b0b90
|
|
| MD5 |
735fdda70fdbc7f897b28cae5c855ba3
|
|
| BLAKE2b-256 |
8703b2a980a5e68a1558943a4c23324c6d2127e6e0d76ce222db521dd33b0ad0
|
File details
Details for the file oaknut_dfs-12.13.1-py3-none-any.whl.
File metadata
- Download URL: oaknut_dfs-12.13.1-py3-none-any.whl
- Upload date:
- Size: 51.5 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 |
410b7e51f8b0922ac58f640cfd3d7667e7aca62985540852f95a4b0839e1900e
|
|
| MD5 |
47678eb2ce75c81f63a7e190dc58d938
|
|
| BLAKE2b-256 |
fbe01cd36f7d94ab4f9b4cd78b3d3f421bf5d4d98deb3b268cb616edd8c12d47
|
