deploy: bf76fb4

index.html.md

@@ -0,0 +1,80 @@
+# execnb
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+[![CI](https://github.com/fastai/execnb/actions/workflows/test.yaml/badge.svg)](https://github.com/fastai/execnb/actions/workflows/test.yaml)
+[![Deploy to GitHub
+Pages](https://github.com/fastai/execnb/actions/workflows/deploy.yaml/badge.svg)](https://github.com/fastai/execnb/actions/workflows/deploy.yaml)
+
+## Install
+
+Either:
+
+    pip install execnb
+
+or if you use conda:
+
+    conda install -c fastai execnb
+
+(You can replace `conda` with `mamba` in the line above if you have
+mamba installed.)
+
+## How to use
+
+Use
+[`CaptureShell`](https://fastai.github.io/execnb/shell.html#captureshell)
+to run Jupyter code and capture notebook outputs, without running a
+Jupyter server (or even having it installed):
+
+``` python
+from execnb.nbio import *
+from execnb.shell import *
+from fastcore.utils import *
+```
+
+``` python
+s = CaptureShell()
+s.run('1+1')
+```
+
+    [{'data': {'text/plain': ['2']},
+      'metadata': {},
+      'output_type': 'execute_result',
+      'execution_count': 1}]
+
+To execute a notebook and save it with outputs filled in, use
+[`CaptureShell.execute`](https://fastai.github.io/execnb/shell.html#captureshell.execute):
+
+``` python
+try:
+    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': 3, 'metadata': {}, 'output_type': 'execute_result'}]
+
+You can also execute notebooks from the command line with
+[`exec_nb`](https://fastai.github.io/execnb/shell.html#exec_nb):
+
+``` python
+!exec_nb --help
+```
+
+    usage: exec_nb [-h] [--dest DEST] [--exc_stop] [--inject_code INJECT_CODE]
+                   [--inject_path INJECT_PATH] [--inject_idx INJECT_IDX]
+                   src
+
+    Execute notebook from `src` and save with outputs to `dest`
+
+    positional arguments:
+      src                        Notebook path to read from
+
+    optional arguments:
+      -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)

nbio.html.md

@@ -0,0 +1,305 @@
+# nbio
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+## Reading a notebook
+
+A notebook is just a json file.
+
+<details open class="code-fold">
+<summary>Exported source</summary>
+
+``` python
+def _read_json(self, encoding=None, errors=None):
+    return loads(Path(self).read_text(encoding=encoding, errors=errors))
+```
+
+</details>
+
+``` python
+minimal_fn = Path('../tests/minimal.ipynb')
+minimal_txt = AttrDict(_read_json(minimal_fn))
+```
+
+It contains two sections, the `metadata`…:
+
+``` python
+minimal_txt.metadata
+```
+
+    {'kernelspec': {'display_name': 'Python 3 (ipykernel)',
+      'language': 'python',
+      'name': 'python3'}}
+
+…and, more importantly, the `cells`:
+
+``` python
+minimal_txt.cells
+```
+
+    [{'cell_type': 'markdown',
+      'metadata': {},
+      'source': ['## A minimal notebook']},
+     {'cell_type': 'code',
+      'execution_count': None,
+      'metadata': {},
+      'outputs': [{'data': {'text/plain': ['2']},
+        'execution_count': None,
+        'metadata': {},
+        'output_type': 'execute_result'}],
+      'source': ['# Do some arithmetic\n', '1+1']}]
+
+The second cell here is a `code` cell, however it contains no outputs,
+because it hasn’t been executed yet. To execute a notebook, we first
+need to convert it into a format suitable for `nbclient` (which expects
+some `dict` keys to be available as attrs, and some available as regular
+`dict` keys). Normally, `nbformat` is used for this step, but it’s
+rather slow and inflexible, so we’ll write our own function based on
+`fastcore`’s handy `dict2obj`, which makes all keys available as both
+attrs *and* keys.
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L21"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### NbCell
+
+>  NbCell (idx, cell)
+
+*`dict` subclass that also provides access to keys as attrs*
+
+We use an `AttrDict` subclass which has some basic functionality for
+accessing notebook cells.
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L50"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### dict2nb
+
+>  dict2nb (js=None, **kwargs)
+
+*Convert dict `js` to an `AttrDict`,*
+
+We can now convert our JSON into this `nbclient`-compatible format,
+which pretty prints the source code of cells in notebooks.
+
+``` python
+minimal = dict2nb(minimal_txt)
+cell = minimal.cells[1]
+cell
+```
+
+``` json
+{ 'cell_type': 'code',
+  'execution_count': None,
+  'idx_': 1,
+  'metadata': {},
+  'outputs': [ { 'data': {'text/plain': ['2']},
+                 'execution_count': None,
+                 'metadata': {},
+                 'output_type': 'execute_result'}],
+  'source': '# Do some arithmetic\n1+1'}
+```
+
+The abstract syntax tree of source code cells is available in the
+`parsed_` property:
+
+``` python
+cell.parsed_(), cell.parsed_()[0].value.op
+```
+
+    ([<ast.Expr>], <ast.Add>)
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L57"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### read_nb
+
+>  read_nb (path)
+
+*Return notebook at `path`*
+
+This reads the JSON for the file at `path` and converts it with
+[`dict2nb`](https://fastai.github.io/execnb/nbio.html#dict2nb). For
+instance:
+
+``` python
+minimal = read_nb(minimal_fn)
+str(minimal.cells[0])
+```
+
+    "{'cell_type': 'markdown', 'metadata': {}, 'source': '## A minimal notebook', 'idx_': 0}"
+
+The file name read is stored in `path_`:
+
+``` python
+minimal.path_
+```
+
+    '../tests/minimal.ipynb'
+
+## Creating a notebook
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L64"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### new_nb
+
+>  new_nb (cells=None, meta=None, nbformat=4, nbformat_minor=5)
+
+*Returns an empty new notebook*
+
+Use this function when creating a new notebook. Useful for when you
+don’t want to create a notebook on disk first and then read it.
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L69"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### mk_cell
+
+>  mk_cell (text, cell_type='code', **kwargs)
+
+*Create an [`NbCell`](https://fastai.github.io/execnb/nbio.html#nbcell)
+containing `text`*
+
+<table>
+<thead>
+<tr>
+<th></th>
+<th><strong>Type</strong></th>
+<th><strong>Default</strong></th>
+<th><strong>Details</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>text</td>
+<td></td>
+<td></td>
+<td><code>source</code> attr in cell</td>
+</tr>
+<tr>
+<td>cell_type</td>
+<td>str</td>
+<td>code</td>
+<td><code>cell_type</code> attr in cell</td>
+</tr>
+<tr>
+<td>kwargs</td>
+<td></td>
+<td></td>
+<td></td>
+</tr>
+</tbody>
+</table>
+
+``` python
+mk_cell('print(1)', execution_count=0)
+```
+
+``` json
+{ 'cell_type': 'code',
+  'directives_': {},
+  'execution_count': 0,
+  'idx_': 0,
+  'metadata': {},
+  'source': 'print(1)'}
+```
+
+## Writing a notebook
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L81"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### nb2dict
+
+>  nb2dict (d, k=None)
+
+*Convert parsed notebook to `dict`*
+
+This returns the exact same dict as is read from the notebook JSON.
+
+``` python
+minimal_fn = Path('../tests/minimal.ipynb')
+minimal = read_nb(minimal_fn)
+
+minimal_dict = _read_json(minimal_fn)
+assert minimal_dict==nb2dict(minimal)
+```
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L89"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### nb2str
+
+>  nb2str (nb)
+
+*Convert `nb` to a `str`*
+
+To save a notebook we first need to convert it to a `str`:
+
+``` python
+print(nb2str(minimal)[:45])
+```
+
+    {
+     "cells": [
+      {
+       "cell_type": "markdown",
+
+------------------------------------------------------------------------
+
+<a
+href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L95"
+target="_blank" style="float:right; font-size:smaller">source</a>
+
+### write_nb
+
+>  write_nb (nb, path)
+
+*Write `nb` to `path`*
+
+This returns the exact same string as saved by Jupyter.
+
+``` python
+tmp = Path('tmp.ipynb')
+try:
+    minimal_txt = minimal_fn.read_text()
+    write_nb(minimal, tmp)
+    assert minimal_txt==tmp.read_text()
+finally: tmp.unlink()
+```
+
+Here’s how to put all the pieces of `execnb.nbio` together:
+
+``` python
+nb = new_nb([mk_cell('print(1)')])
+path = Path('test.ipynb')
+write_nb(nb, path)
+nb2 = read_nb(path)
+print(nb2.cells)
+path.unlink()
+```
+
+    [{'cell_type': 'code', 'metadata': {}, 'source': 'print(1)', 'idx_': 0}]

robots.txt

@@ -0,0 +1 @@
+Sitemap: https://fastai.github.io/execnb/sitemap.xml