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 package puts an oaknut-basic executable on PATH:

uv tool install oaknut-basic
oaknut-basic --help

Or run it once, without installing, via uvx:

uvx oaknut-basic number menu.bas

The same distribution is also the importable library; installing it with uv add or pip install (below) gives you both the codec and the command.

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