Metadata-Version: 2.4
Name: oaknut
Version: 0.1.0
Summary: Oaknut family meta-distribution — tools for Acorn computer filesystems, files, and formats.
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
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
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: oaknut-file>=1.0
Requires-Dist: oaknut-dfs>=4.0
Requires-Dist: oaknut-zip>=2.0

# oaknut

Python tools for Acorn computer filesystems, files, and formats — the BBC Micro, Electron, Archimedes, and their descendants.

This repository is a `uv` workspace monorepo containing the `oaknut-*` family of packages. Each package is independently published to PyPI, but they all contribute to a shared `oaknut.` Python namespace so that imports read naturally:

```python
from oaknut.file import AcornMeta, MetaFormat
from oaknut.dfs import DFS, DFSPath
from oaknut.zip import extract_archive
```

## Packages

| PyPI distribution | Import path | Scope |
|---|---|---|
| [`oaknut-file`](packages/oaknut-file/) | `oaknut.file` | Acorn file metadata — INF sidecars (traditional + PiEconetBridge), filename encoding, xattr namespaces, access flags, host bridge |
| [`oaknut-dfs`](packages/oaknut-dfs/) | `oaknut.dfs` | Acorn DFS / Watford DDFS disc images (SSD, DSD), and ADFS disc images (pending extraction into a dedicated `oaknut-adfs` package) |
| [`oaknut-zip`](packages/oaknut-zip/) | `oaknut.zip` | ZIP archives containing Acorn files — SparkFS extras, INF resolution, RISC OS filetype decoding |

Planned additional packages (see `docs/monorepo.md`):

- `oaknut-fs` — universal filesystem abstractions (catalogue ABC, Acorn codec, boot options)
- `oaknut-image` — disc-image abstractions (sector access, geometry, free-space maps)
- `oaknut-adfs` — ADFS (extracted from the current `oaknut-dfs`)
- `oaknut-basic` — BBC BASIC tokeniser / detokeniser
- `oaknut-disc` — the `disc` CLI binary

## Quick start

```sh
git clone https://github.com/rob-smallshire/oaknut.git
cd oaknut
uv sync
uv run pytest
```

The workspace uses [uv](https://github.com/astral-sh/uv) for dependency management. Sibling packages are wired together as path dependencies during development via `[tool.uv.sources]` in the workspace-root `pyproject.toml`, so any change in one package is immediately visible to the others without a publish round-trip.

## Installing from PyPI

Each library package is independently installable:

```sh
pip install oaknut-file
pip install oaknut-dfs
pip install oaknut-zip
```

Or install the whole family via the meta-distribution:

```sh
pip install oaknut
```

## Documentation

- [`docs/monorepo.md`](docs/monorepo.md) — monorepo design, architectural target, package layering
- [`docs/cli-design.md`](docs/cli-design.md) — design of the forthcoming `disc` CLI

## Licence

MIT. See each package's `LICENSE` file.
