Allow running any callable in an CLI notebook

[bollwyvl]

elevator pitch

Provide a way to run any function (or other exported name) from a notebook from the command line.

motivation

argparse (or a heavier-weight dependency like typer or click) adds a fair amount of boilerplate to a notebook which would otherwise be a useful standalone, literate collection of functions.

This is particularly useful in a situation where a notebook is being used as the "meat" of some other CLI-based syntax, such as pixi.toml or dodo.py, where making a script-per-task would be a lot of extra files.

design ideas

Add -e/--entry-point as an alternative to -m.

importnb -e Untitled42:foo.bar.baz a b c

as an equivalent to:

with importnb.Notebook():
    import Untitled42
sys.exit(Untitled.foo.bar.baz("a", "b", "c"))

challenges

Arguments are complex: there's really no accounting for taste, and it's generally not possible to distinguish between positional arguments, flags (-x or --long-x, no argument), and proper options with values.

Being able to get help is also important, but maybe an IPython-style trailing ? or ?? would be workable, but would require quoting under most conditions

importnb -e Untitled42:foo.bar.baz -h
importnb -e "Untitled42:foo.bar.baz?"

Some care would need to be taken for the return code to hand to sys.exit, and might need another flag for some behavior switches:

• pass through int unchanged
• a la doit, treat any truthy or None as 0 (success), and anything else as 1 (fail)

There's probably some clever way (again, another flag) to suggest stdin should be passed as some kind
of argument:

ls * | importnb -e Untitled:foo --stdin=pargs      # call once, with every line as a positional argument
ls * | importnb -e Untitled:foo --stdin=kwarg:bar  # call once, with every line as a named argument
ls * | importnb -e Untitled:foo --stdin=map        # call once per line
ls * | importnb -e Untitled:foo --stdin=any        # call until the first truthy return value
ls * | importnb -e Untitled:foo --stdin=all        # call until the first falsey return value

Natively, these would be as bytes, though maybe being able to specify (or default) the encoding, e.g. --stdin-encoding=utf-8, would be sufficient for most cases.

[bollwyvl]

Some more thought on the arbitrary pargs/kwargs issue: rely on existing (optional) parsers for explicit or streamed inputs:

importnb -e Untitled:foo --json '{"arg_1": true}'
echo arg_1: yes | importnb -e Untitled:foo --yaml - 

... with both of the above resolving to:

with importnb.Notebook():
    import Untitled
Untitled.foo(arg_1=True)

This would work pretty well with upstreams such as jq, taplo and others that have flexible outputs, but might be incompatible with other approaches mentioned above.

[tonyfast]

yea i love this idea. there is some implicit/undocumented form of a parameterized cli with type annotations now, and i like this new approach cause its more explicit. moreover, i can see this being part of a extensible plugin system for importnb. our api is pretty hardened by python's constraints. im drafting an issue about the plugin and will ping ya when its ready.

i think i'm imagining a plugin called something like importnb_run_as_main would be able to consume an imported module and do work if the name is __main__