diff --git a/README.md b/README.md index c90448f..5b2a343 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ or if you use conda: ## How to use -Use [`CaptureShell`](https://AnswerDotAI.github.io/execnb/shell.html#captureshell) to run Jupyter code and capture notebook outputs, without running a Jupyter server (or even having it installed). The API is async, so `await` the run from a notebook or async code, or wrap it in [`asyncio.run`](https://docs.python.org/3/library/asyncio-runner.html#asyncio.run) at a sync entry point: +Use [`CaptureShell`](https://AnswerDotAI.github.io/execnb/shell.html#captureshell) to run Jupyter code and capture notebook outputs, without running a Jupyter server (or even having it installed). The API is sync – each shell runs cells on its own private event loop in a background thread, so it works the same from a script, a notebook, or an async server, and cells may use top-level `await`: ``` python from execnb.shell import * @@ -27,24 +27,24 @@ from fastcore.nbio import * ``` python s = CaptureShell() -await s.run('1+1') +s.run('1+1') ``` [{'data': {'text/plain': ['2']}, 'metadata': {}, 'output_type': 'execute_result', - 'execution_count': None}] + 'execution_count': 1}] To execute a notebook and save it with outputs filled in, use [`CaptureShell.execute`](https://AnswerDotAI.github.io/execnb/shell.html#captureshell.execute): ``` python try: - await s.execute('../tests/clean.ipynb', 'tmp.ipynb') + s.execute('../tests/clean.ipynb', 'tmp.ipynb') print(read_nb('tmp.ipynb').cells[1].outputs) finally: Path('tmp.ipynb').unlink() ``` - [{'name': 'stdout', 'output_type': 'stream', 'text': '1\n'}, {'data': {'text/plain': '2'}, 'execution_count': None, 'metadata': {}, 'output_type': 'execute_result'}] + [{'name': 'stdout', 'output_type': 'stream', 'text': '1\n'}, {'data': {'text/plain': '2'}, 'execution_count': 3, 'metadata': {}, 'output_type': 'execute_result'}] You can also execute notebooks from the command line with [`exec_nb`](https://AnswerDotAI.github.io/execnb/shell.html#exec_nb): @@ -52,21 +52,24 @@ You can also execute notebooks from the command line with [`exec_nb`](https://An !exec_nb --help ``` - usage: exec_nb [-h] [--dest DEST] [--exc_stop] [--inject_code INJECT_CODE] - [--inject_path INJECT_PATH] [--inject_idx INJECT_IDX] [--verbose] + usage: exec_nb [-h] [--dest (str)] [--exc-stop] [--inject-code (str)] + [--inject-path (str)] [--inject-idx (int)] [--verbose] + [--cell-timeout (int)] src Execute notebook from `src` and save with outputs to `dest` positional arguments: - src Notebook path to read from + src Notebook path to read from options: - -h, --help show this help message and exit - --dest DEST Notebook path to write to (default: ) - --exc_stop Stop on exceptions? (default: False) - --inject_code INJECT_CODE Code to inject into a cell - --inject_path INJECT_PATH Path to file containing code to inject into a cell - --inject_idx INJECT_IDX Cell to replace with `inject_code` (default: 0) - --verbose Show stdout/stderr during execution (default: - False) + -h, --help show this help message and exit + --dest (str) Notebook path to write to (default: '') + --exc-stop Stop on exceptions? (default: False) + --inject-code (str) Code to inject into a cell + --inject-path (str) Path to file containing code to inject into a cell + --inject-idx (int) Cell to replace with `inject_code` (default: 0) + --verbose Show stdout/stderr during execution (default: False) + --cell-timeout (int) Seconds before each cell times out (None: no limit) + + execnb 0.3.4 diff --git a/nbs/index.ipynb b/nbs/index.ipynb index e6291ef..b102fe0 100644 --- a/nbs/index.ipynb +++ b/nbs/index.ipynb @@ -74,7 +74,7 @@ "[{'data': {'text/plain': ['2']},\n", " 'metadata': {},\n", " 'output_type': 'execute_result',\n", - " 'execution_count': None}]" + " 'execution_count': 1}]" ] }, "execution_count": null, @@ -105,7 +105,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "[{'name': 'stdout', 'output_type': 'stream', 'text': '1\\n'}, {'data': {'text/plain': '2'}, 'execution_count': None, 'metadata': {}, 'output_type': 'execute_result'}]\n" + "[{'name': 'stdout', 'output_type': 'stream', 'text': '1\\n'}, {'data': {'text/plain': '2'}, 'execution_count': 3, 'metadata': {}, 'output_type': 'execute_result'}]\n" ] } ], @@ -134,24 +134,27 @@ "name": "stdout", "output_type": "stream", "text": [ - "usage: exec_nb [-h] [--dest DEST] [--exc_stop] [--inject_code INJECT_CODE]\r\n", - " [--inject_path INJECT_PATH] [--inject_idx INJECT_IDX] [--verbose]\r\n", + "usage: exec_nb [-h] [--dest (str)] [--exc-stop] [--inject-code (str)]\r\n", + " [--inject-path (str)] [--inject-idx (int)] [--verbose]\r\n", + " [--cell-timeout (int)]\r\n", " src\r\n", "\r\n", "Execute notebook from `src` and save with outputs to `dest`\r\n", "\r\n", "positional arguments:\r\n", - " src Notebook path to read from\r\n", + " src Notebook path to read from\r\n", "\r\n", "options:\r\n", - " -h, --help show this help message and exit\r\n", - " --dest DEST Notebook path to write to (default: )\r\n", - " --exc_stop Stop on exceptions? (default: False)\r\n", - " --inject_code INJECT_CODE Code to inject into a cell\r\n", - " --inject_path INJECT_PATH Path to file containing code to inject into a cell\r\n", - " --inject_idx INJECT_IDX Cell to replace with `inject_code` (default: 0)\r\n", - " --verbose Show stdout/stderr during execution (default:\r\n", - " False)\r\n" + " -h, --help show this help message and exit\r\n", + " --dest (str) Notebook path to write to (default: '')\r\n", + " --exc-stop Stop on exceptions? (default: False)\r\n", + " --inject-code (str) Code to inject into a cell\r\n", + " --inject-path (str) Path to file containing code to inject into a cell\r\n", + " --inject-idx (int) Cell to replace with `inject_code` (default: 0)\r\n", + " --verbose Show stdout/stderr during execution (default: False)\r\n", + " --cell-timeout (int) Seconds before each cell times out (None: no limit)\r\n", + "\r\n", + "execnb 0.3.4\r\n" ] } ],