Merge pull request #19 from zph/add-auto-prompting

Add auto prompting during plan if no args supplied

Author: zph

.config/README.md.template

@@ -28,6 +28,24 @@ In this context, a runbook is a mixture of markdown and executable code that con
 1. Plan that runbook for a specific run `runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
 1. Run the instance of a runbook with either `runbook run runbook-name.ipynb` or use VSCode to run it `code runbooks/run/runbook-name.ipynb`
 
+## Installation
+
+We recommend using [uv](https://docs.astral.sh/uv/) or [pipx](https://pypi.org/project/pipx/) for installing runbook as a cli tool.
+
+```sh
+uv tool install git+https://github.com/zph/runbook.git
+# or
+pipx install git+https://github.com/zph/runbook.git
+```
+
+Or pin to a version
+
+```sh
+uv tool install git+https://github.com/zph/runbook.git@v0.0.1
+
+pipx install git+https://github.com/zph/runbook.git@v0.0.1
+```
+
 ## CLI
 
 ```sh
@@ -73,9 +91,6 @@ long as executions run through `runbook run ...` command
 ## Deno / Typescript
 1. Parameter cells should use `let` declarations to allow for param overriding
     - This is required to correctly support executing the ts version of notebooks.
-1. Confirm/prompt functions always return false in notebooks due to lack of support
-    in deno kernel. We may invest in upstreaming a patch to support this as it has support
-    in python notebooks
 
 # Readme Changes
 

NOTES.md

@@ -11,10 +11,10 @@
 - [ ] Use execute and upload output to S3 for non-interactive: https://github.com/nteract/papermill/tree/main?tab=readme-ov-file#execute-via-cli
 
 ## P0
-- [ ] Setup versioning and bumper (using versioner from npm ecosystem @release-it and @release-it/bumper)
+- [x] Setup versioning and bumper (using versioner from npm ecosystem @release-it and @release-it/bumper)
 - [x] Fix tag key getting stripped out of planned runbooks b/c it breaks papermill
 - [ ] Setup a watcher for auto-exporting html or other formats
-- [ ] Setup tagging in the notebooks to auto-set those values
+- [x] Setup tagging in the notebooks to auto-set those values
 - [ ] Setup git to autoclear cell outputs for a given folder's notebooks (ie templates) https://stackoverflow.com/a/58004619
 - [x] Assess if we need shell completions
    - [x] Yes, very nice and use https://click.palletsprojects.com/en/8.1.x/shell-completion/#custom-type-completion to define for custom types, ie only find ipynb files for edit, create, etc

README.md

@@ -33,6 +33,24 @@ Use [pipx](https://github.com/pypa/pipx)
 1. Plan that runbook for a specific run `runbook plan runbook-name.ipynb --embed file.json --parameters '{"arg": 1, "foo": "baz"}'
 1. Run the instance of a runbook with either `runbook run runbook-name.ipynb` or use VSCode to run it `code runbooks/run/runbook-name.ipynb`
 
+## Installation
+
+We recommend using [uv](https://docs.astral.sh/uv/) or [pipx](https://pypi.org/project/pipx/) for installing runbook as a cli tool.
+
+```sh
+uv tool install git+https://github.com/zph/runbook.git
+# or
+pipx install git+https://github.com/zph/runbook.git
+```
+
+Or pin to a version
+
+```sh
+uv tool install git+https://github.com/zph/runbook.git@v0.0.1
+
+pipx install git+https://github.com/zph/runbook.git@v0.0.1
+```
+
 ## CLI
 
 ```sh
@@ -95,9 +113,6 @@ long as executions run through `runbook run ...` command
 ## Deno / Typescript
 1. Parameter cells should use `let` declarations to allow for param overriding
     - This is required to correctly support executing the ts version of notebooks.
-1. Confirm/prompt functions always return false in notebooks due to lack of support
-    in deno kernel. We may invest in upstreaming a patch to support this as it has support
-    in python notebooks
 
 # Readme Changes
 

runbook/cli/commands/create.py

@@ -1,7 +1,7 @@
 from os import path
 
 import click
-from nbconvert.nbconvertapp import NbConvertApp
+from runbook.cli.lib import nbconvert_launch_instance
 from runbook.cli.validators import validate_create_language, validate_template
 
 
@@ -11,15 +11,18 @@
     "-t",
     "--template",
     envvar="TEMPLATE",
-    default="./runbooks/binder/_template-python.ipynb",
+    default="./runbooks/binder/_template-deno.ipynb",
     type=click.Path(exists=True, file_okay=True),
     callback=validate_template,
 )
+
+# TODO: switch to language and template defaulting to Deno
+# based on operational experience at work
 @click.option(
     "-l",
     "--language",
     envvar="LANGUAGE",
-    default="./runbooks/binder/_template-python.ipynb",
+    default="deno",
     callback=validate_create_language,
 )
 @click.pass_context
@@ -36,9 +39,7 @@ def create(ctx, filename, template, language):
         )
     # TODO: remove hardcoding of folder outer name and rely on config file
     path.join("runbooks", "binder", filename)
-    # TODO: hide the nbconvert verbose output?
     argv = [
-        "--ClearOutputPreprocessor.enabled=True",
         template,
         "--to",
         "notebook",
@@ -48,7 +49,7 @@ def create(ctx, filename, template, language):
         path.join("runbooks", "binder"),
     ]
 
-    NbConvertApp().launch_instance(argv=argv)
+    nbconvert_launch_instance(argv, clear_output=True)
 
     click.echo(
         click.style(

runbook/cli/commands/plan.py

@@ -1,16 +1,56 @@
+import json
 import os
 from datetime import datetime
 from os import path
 from pathlib import Path
 
 import click
+import nbformat
+from runbook.cli.lib import nbconvert_launch_instance
 from runbook.cli.validators import validate_plan_params, validate_runbook_file_path
+from runbook.constants import RUNBOOK_METADATA
 
 import papermill as pm
 
 
-# TODO: standardize ids in output files through custom processor
-# use something like ulid, we don't need full UUIDs
+def get_notebook_language(notebook_path: str) -> str:
+    """
+    Determine the language of the notebook by checking the first code cell's metadata.
+    Returns 'python', 'typescript', or 'unknown'
+    """
+    nb = nbformat.read(notebook_path, as_version=4)
+    for cell in nb.cells:
+        if cell.cell_type == "code":
+            # Check kernel info
+            if "kernelspec" in nb.metadata:
+                kernel_name = nb.metadata.kernelspec.name.lower()
+                if "python" in kernel_name:
+                    return "python"
+                elif "typescript" in kernel_name or "ts" in kernel_name:
+                    return "typescript"
+            # Check language info
+            if "language_info" in nb.metadata:
+                language = nb.metadata.language_info.name.lower()
+                if "python" in language:
+                    return "python"
+                elif "typescript" in language or "ts" in language:
+                    return "typescript"
+    return "unknown"
+
+
+import ast
+
+
+def get_parser_by_language(language: str):
+    if language == "typescript":
+        return json.loads
+    elif language == "python":
+        return ast.literal_eval
+    else:
+        # Default to json.loads for unknown languages
+        return json.loads
+
+
 @click.command()
 @click.argument(
     "input", type=click.Path(file_okay=True), callback=validate_runbook_file_path
@@ -39,7 +79,7 @@ def plan(ctx, input, embed, identifier="", params={}):
     full_output = f"{output_folder}/{output_basename_without_ext}.ipynb"
 
     runbook_param_injection = {
-        "__RUNBOOK_METADATA__": {
+        RUNBOOK_METADATA: {
             "RUNBOOK_FOLDER": output_folder,
             "RUNBOOK_FILE": full_output,
             "RUNBOOK_SOURCE": input,
@@ -48,6 +88,31 @@ def plan(ctx, input, embed, identifier="", params={}):
         }
     }
 
+    # TODO: add test cases for auto-planning
+    # As of 2025 Jan it's manual regression testing
+    if len(params) == 0:
+        inferred_params = pm.inspect_notebook(input)
+        notebook_language = get_notebook_language(input)
+        value_parser = get_parser_by_language(notebook_language)
+        # Inferred_type_name is language specific
+        for key, value in inferred_params.items():
+            if key != RUNBOOK_METADATA:
+                default = value["default"].rstrip(";")
+                typing = value["inferred_type_name"]
+                type_hint = ""
+                help_hint = ""
+                if typing:
+                    type_hint = f" ({typing})"
+                if value["help"]:
+                    help_hint = f"(hint: {value['help']})"
+
+                raw_value = click.prompt(
+                    f"""Enter value for {key}{type_hint}{help_hint}""",
+                    default=default,
+                    value_proc=value_parser,
+                )
+                params[key] = raw_value
+
     injection_params = {**runbook_param_injection, **params}
 
     if not Path(output_folder).exists():
@@ -64,17 +129,13 @@ def plan(ctx, input, embed, identifier="", params={}):
     )
 
     argv = [
-        "--ClearOutputPreprocessor.enabled=True",
         "--inplace",
         full_output,
     ]
 
     # TODO: join the unified logic of create and plan
 
-    # TODO: hide the nbconvert verbose output?
-    from nbconvert.nbconvertapp import NbConvertApp
-
-    NbConvertApp().launch_instance(argv=argv)
+    nbconvert_launch_instance(argv, clear_output=True)
 
     for f in embed:
         shutil.copyfile(src=f, dst=f"{output_folder}/{path.basename(f)}")

runbook/cli/lib.py

@@ -1,5 +1,8 @@
 import hashlib
+import sys
+from io import StringIO
 
+from nbconvert.nbconvertapp import NbConvertApp
 from ulid import ULID
 
 
@@ -14,3 +17,23 @@ def sha256sum(filename):
 # use ULID() directly
 def ts_id(length=10):
     return str(ULID())[0:length]
+
+
+# Suppresses nbconvert output
+def nbconvert_launch_instance(argv, clear_output=True):
+    if clear_output:
+        argv.insert(0, "--ClearOutputPreprocessor.enabled=True")
+    stdout = sys.stdout
+    stderr = sys.stderr
+    sys.stdout = StringIO()
+    sys.stderr = StringIO()
+    try:
+        NbConvertApp().launch_instance(argv=argv)
+    except Exception as e:
+        print(sys.stdout.getvalue())
+        print(sys.stderr.getvalue())
+        raise e
+    finally:
+        # Restore stdout/stderr
+        sys.stdout = stdout
+        sys.stderr = stderr

runbook/cli/validators.py

@@ -4,6 +4,8 @@
 from pathlib import Path
 
 import click
+
+# TODO: use click prompt lib instead of questionary to avoid dependency
 import questionary
 
 
@@ -26,8 +28,10 @@ def validate_template(ctx, param, value):
 def validate_create_language(ctx, param, value):
     if value == "./runbooks/binder/_template-python.ipynb":
         return value
+    if value == "./runbooks/binder/_template-deno.ipynb":
+        return value
     if value in ["python", "deno"]:
-        return f"./runbooks/binder/_template-{value}"
+        return f"./runbooks/binder/_template-{value}.ipynb"
     else:
         raise click.BadOptionUsage("--language", "options are python or deno")
 
@@ -36,6 +40,10 @@ def validate_plan_params(ctx, param, value):
     if isinstance(value, dict):
         return value
 
+    # We allow this for the auto-plan case
+    if value == "" or value == None:
+        return {}
+
     try:
         v = json.loads(value)
         if isinstance(v, dict):

runbook/constants.py

@@ -0,0 +1 @@
+RUNBOOK_METADATA = "__RUNBOOK_METADATA__"