A custom Isabelle/HOL code-generation backend that targets Python 3.
- A recent Isabelle/HOL release (with
isabelleon yourPATH, currently onlyIsabelle2025-2has been tested) - uv, which runs Python at the version in
.python-version, the target version of the generated code
git clone https://github.com/pure-py/isabelle-python-codegen.git
cd isabelle-python-codegen
isabelle components -u "$(pwd)"This registers the Python session so other Isabelle projects can depend
on it without a -d flag:
session My_Project = Python +
theories
My_TheoryIn order to use this generator you have to import one of the following theories:
Python.PythonPython.Python_Setup
Python.Python introduces only a minimum set of custom printers (Booleans, Unit,
Strings), and relies on the automatically extracted HOL definitions for other
things.
Python.Python_Setup extends Python.Python by printing int and nat as
Python integers, lists as Python lists, pairs as tuples and char as
one-character strings.
Generated code must not use Python's keywords as names, nor hide the builtins
it calls itself (len, list, range, ...). The names to avoid are listed one
per line in etc/python_reserved_words: the keywords, soft keywords and
builtins of the Python version in .python-version. Lines starting with #
are comments. Python.thy reserves every name in the file, together with the
names that the prelude of each generated module binds (dataclass, Any,
Callable, functools, _abort, _unimplemented; prelude_names in
code_python.ML).
A definition, class or datatype with a reserved name gets a trailing
underscore (tuple becomes tuple_), and a variable gets a fresh variant
(len becomes lena).
The list is generated rather than edited by hand. After changing
.python-version, regenerate it with
make reserved-wordswhich runs etc/update_reserved_words.py with the project's Python through
uv run. The script refuses to run under any other Python version than the
one in .python-version. Commit the updated list with the version change.
Python.thy declares the file with external_file, so the next
isabelle build rebuilds the Python session, and every session built on it,
whenever the list changes.
A value is printed as a cached function without arguments, and its uses call it, so it is evaluated once, when it is first used:
@functools.cache
def num_of_nat():
return (Fun.comp(Code_Numeral.num_of_integer, lambda a: a))The option python_cache (on by default) controls the @functools.cache
decorator, on values and on instances without dictionary arguments. Turn it off
to measure what the caching gains; values are then still functions without
arguments, but are recomputed on every use:
isabelle build -o python_cache=false -d . -e Python_Examplesor declare [[python_cache = false]] in a theory, before export_code.
Code that uses the generated modules therefore calls a value too
(Example_nat.nat_sum()). An alias of a function (f_int = f) is printed as an
ordinary function instead.
Importing a module thus evaluates nothing, which matters for two reasons. Each
theory becomes a Python module (unless code_identifier or the module_name of
export_code says otherwise), and code equations may use constants of later
theories, e.g. Num.num_of_nat is implemented by Code_Numeral.num_of_integer.
So the modules can import each other: in the HOL library, about 50 modules form
one import cycle. Python allows this as long as no module reads an attribute of
a module that is still being imported, which evaluating a value could do. And a
value that calls a constant without code (_abort) raises when it is used,
rather than when its module is imported.
Python does not eliminate tail calls, so a function that recurses once per
element hits the default recursion limit of 1000 frames. With the option
python_tail_calls (off by default), a function that calls itself in tail
position is printed with its body inside while True:, and each such call
becomes a reassignment of its parameters followed by continue. Set it for a
whole build, without changing any theory:
isabelle build -o python_tail_calls -d . -e Python_Examplesor in a theory, before export_code:
declare [[python_tail_calls]]Only direct self calls are turned into loops, not mutual recursion. A function
whose equations create closures (a lambda, or a partial application printed as
one) is left recursive: Python closures capture variables, not values, so a
closure created in one iteration would see the next iteration's rebinding.
examples/Example_tail_calls.thy shows both outputs side by side.
This repository comes with three test suites:
- quick
Unit test that extracts Python code from /test/quick/Quick_Test.thy
and runs various tests defined in /test/quick/run_test.py.
isabelle build -d . -e Python_Test_Quick
uv run pytest test/quick/run_test.py -v- slow
This draws in a sizeable section of the HOL library. The file
test/slow/Candidates.thy was originally written by Florian Haftmann from TU München, and taken almost verbatim from the Go backend.
Two different theories extract the code once with Python.Python and once
with Python.Python_Setup. Unfortunately, we can currently not use Isabelle's
code_export _ checking ..., as the code formatter for checking has a hardcoded margin of 80 characters, which causes problems with nested statements in Python.
isabelle build -d . -e Python_Test_Slow
uv run python -m py_compile test/slow/generated_basic/*.py
uv run python -m py_compile test/slow/generated_full/*.py
uv run pytest test/slow/run_test.pyrun_test.py imports every generated module in a fresh interpreter, and checks
that every cached function takes no arguments; the modules that are known not to
import are listed in KNOWN_FAILURES there.
- diff
During the development of this code generator, different Isabelle features were
tested in isolation in different example theories under examples/. To see if
changes to the backend result in changes to the extracted code, the diff test
suite holds golden reference files under test/diff/golden/.
isabelle build -d . -e Python_Examples
uv run pytest test/diff/run_test.pyIf a new example is added, or the output has changed and is confirmed correct, the golden files can be recreated by
isabelle build -d . -e Python_Examples
uv run python test/diff/reseed_goldens.py- No support yet for
real,rat, or other numeric types beyondint/nat. - Introducing a pretty printer that unboxes a type with exactly one constructor
which maps to an identity in Python causes an
undefined name error. To circumvent this, such a symbol must be declared withCode_Python.add_transparent_wrapper_sym. For an example, look atexamples/Example_transparent_wrapper.thy.
BSD
