astronote 0.1.4

Add your description here

astronote: AST to Reprodceble Output NOTEbook

This tool allows to generate a Jupyter notebook from a Python script. The generated notebook includes the original source code and hyperparameters used for execution, enabling reproducibility and easy sharing of results.

Usage

A notebook entry is defined by decorating a function with @notebook_entry. This marks the function as an entry point for notebook generation. When the decorated function is executed, astronote captures its source code and parameters, and generates a notebook that includes this information.

from astronote import notebook_entry


def func() -> str:
    return "This is a sub-function, not a notebook entry."


def calc(x: int, y: int) -> int:
    return x + y


@notebook_entry
def main(a: int = 10, b: int = 20) -> str:
    result = calc(a, b)
    return f"The result of calc({a}, {b}) is {result}"


if __name__ == "__main__":
    main()

And run the script with:

astronote example.py

you are able to find the generated notebook in the same directory as example.py with a name like example.ipynb.

To embed local helper code directly into the generated notebook instead of keeping imports, use --expand-module for imported module names and --embed-file for local .py paths:

astronote examples/example_multiple_file.py --expand-module sub_mod
astronote examples/example_multiple_file.py --embed-file examples/sub_mod.py

When --embed-file is used, the .py path must resolve to a local module that is actually imported by the source script.

pyproject.toml Configuration

CLI options can also be provided from [tool.astronote] in pyproject.toml. CLI arguments take precedence over pyproject.toml, and list-style options are merged as pyproject.toml first, then CLI.

[tool.astronote]
source = "examples/example_single_file.py"
parameter_file = "examples/params.json"
override = ['beta="from_pyproject"']
entrypoint = "run"
expand_module = ["sub_mod"]
embed_file = ["examples/sub_mod.py"]
output = "dist/example_single_file.ipynb"
show_analysis = true
show_schema = true

With that configuration, astronote can be run without repeating those options on the command line.