Skip to content

Repository files navigation

Python code generator for Isabelle/HOL

Isabelle/Python logo

A custom Isabelle/HOL code-generation backend that targets Python 3.

Requirements

  • A recent Isabelle/HOL release (with isabelle on your PATH, currently only Isabelle2025-2 has been tested)
  • uv, which runs Python at the version in .python-version, the target version of the generated code

Installing as a component

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_Theory

Using the code generator

In order to use this generator you have to import one of the following theories:

  • Python.Python
  • Python.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.

Reserved names

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-words

which 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.

Values and modules

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_Examples

or 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.

Tail calls as loops

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_Examples

or 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.

Running the tests

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.py

run_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.py

If 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

Known limitations

  • No support yet for real, rat, or other numeric types beyond int/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 with Code_Python.add_transparent_wrapper_sym. For an example, look at examples/Example_transparent_wrapper.thy.

License

BSD

Releases

Packages

Contributors

Languages