Installation

oaknut-basic provides both a command-line tool for converting BBC BASIC programs and a Python library that embeds the same codec. Install it on its own to work with .bas / .bbc files outside a disc image; it is also pulled in automatically by oaknut-dfs and oaknut-adfs to back their read_basic / write_basic methods.

Prerequisites

oaknut-basic requires Python 3.11 or newer.

This guide leads with uv because that’s how the project is developed and what every internal command shows. If you do not already have uv, follow Astral’s installation guide. pip works identically with the same package name, and pipx is the supported alternative for tool management.

The command-line tool

Installing the [cli] extra puts an oaknut-basic executable on PATH:

uv tool install "oaknut-basic[cli]"
oaknut-basic --help

Or run it once, without installing, via uvx:

uvx --from "oaknut-basic[cli]" oaknut-basic number menu.bas

The bare oaknut-basic distribution (no extra) is the importable library only; the CLI’s Click and rendering dependencies arrive with the [cli] extra so a program that just imports the codec stays lean.

The library

For programmatic use, add the package to your project:

uv add oaknut-basic

…or with pip into the active virtualenv:

pip install oaknut-basic

A first program — tokenise a listing and write it as a .bbc file:

from pathlib import Path

from oaknut.basic import tokenise

source = "10 PRINT \"HELLO\"\n20 GOTO 10\n"
Path("HELLO.bbc").write_bytes(tokenise(source))

Where to go next