Skip to content

Commit 354f073

Browse files
github-actions[bot]github-actions[bot]
committed
deploy: fdcaf61 
0 parents  commit 354f073

29 files changed

+9682
-0
lines changed

‎.nojekyll‎

Whitespace-only changes.

‎02_shell_files/figure-commonmark/cell-17-output-1.png‎

45.4 KB
Loading

‎02_shell_files/figure-html/cell-17-output-1.png‎

45.4 KB
Loading

‎index.html‎

Lines changed: 695 additions & 0 deletions
Large diffs are not rendered by default.

‎index.html.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# execnb
2+
3+
4+
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
5+
6+
[![CI](https://github.com/fastai/execnb/actions/workflows/test.yaml/badge.svg)](https://github.com/fastai/execnb/actions/workflows/test.yaml)
7+
[![Deploy to GitHub
8+
Pages](https://github.com/fastai/execnb/actions/workflows/deploy.yaml/badge.svg)](https://github.com/fastai/execnb/actions/workflows/deploy.yaml)
9+
10+
## Install
11+
12+
Either:
13+
14+
pip install execnb
15+
16+
or if you use conda:
17+
18+
conda install -c fastai execnb
19+
20+
(You can replace `conda` with `mamba` in the line above if you have
21+
mamba installed.)
22+
23+
## How to use
24+
25+
Use
26+
[`CaptureShell`](https://fastai.github.io/execnb/shell.html#captureshell)
27+
to run Jupyter code and capture notebook outputs, without running a
28+
Jupyter server (or even having it installed):
29+
30+
``` python
31+
from execnb.nbio import *
32+
from execnb.shell import *
33+
from fastcore.utils import *
34+
```
35+
36+
``` python
37+
s = CaptureShell()
38+
s.run('1+1')
39+
```
40+
41+
[{'data': {'text/plain': ['2']},
42+
'metadata': {},
43+
'output_type': 'execute_result',
44+
'execution_count': 1}]
45+
46+
To execute a notebook and save it with outputs filled in, use
47+
[`CaptureShell.execute`](https://fastai.github.io/execnb/shell.html#captureshell.execute):
48+
49+
``` python
50+
try:
51+
s.execute('../tests/clean.ipynb', 'tmp.ipynb')
52+
print(read_nb('tmp.ipynb').cells[1].outputs)
53+
finally: Path('tmp.ipynb').unlink()
54+
```
55+
56+
[{'name': 'stdout', 'output_type': 'stream', 'text': ['1\n']}, {'data': {'text/plain': ['2']}, 'execution_count': 3, 'metadata': {}, 'output_type': 'execute_result'}]
57+
58+
You can also execute notebooks from the command line with
59+
[`exec_nb`](https://fastai.github.io/execnb/shell.html#exec_nb):
60+
61+
``` python
62+
!exec_nb --help
63+
```
64+
65+
usage: exec_nb [-h] [--dest DEST] [--exc_stop] [--inject_code INJECT_CODE]
66+
[--inject_path INJECT_PATH] [--inject_idx INJECT_IDX]
67+
src
68+
69+
Execute notebook from `src` and save with outputs to `dest`
70+
71+
positional arguments:
72+
src Notebook path to read from
73+
74+
optional arguments:
75+
-h, --help show this help message and exit
76+
--dest DEST Notebook path to write to (default: )
77+
--exc_stop Stop on exceptions? (default: False)
78+
--inject_code INJECT_CODE Code to inject into a cell
79+
--inject_path INJECT_PATH Path to file containing code to inject into a cell
80+
--inject_idx INJECT_IDX Cell to replace with `inject_code` (default: 0)

‎nbio.html‎

Lines changed: 891 additions & 0 deletions
Large diffs are not rendered by default.

‎nbio.html.md‎

Lines changed: 305 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,305 @@
1+
# nbio
2+
3+
4+
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
5+
6+
## Reading a notebook
7+
8+
A notebook is just a json file.
9+
10+
<details open class="code-fold">
11+
<summary>Exported source</summary>
12+
13+
``` python
14+
def _read_json(self, encoding=None, errors=None):
15+
return loads(Path(self).read_text(encoding=encoding, errors=errors))
16+
```
17+
18+
</details>
19+
20+
``` python
21+
minimal_fn = Path('../tests/minimal.ipynb')
22+
minimal_txt = AttrDict(_read_json(minimal_fn))
23+
```
24+
25+
It contains two sections, the `metadata`…:
26+
27+
``` python
28+
minimal_txt.metadata
29+
```
30+
31+
{'kernelspec': {'display_name': 'Python 3 (ipykernel)',
32+
'language': 'python',
33+
'name': 'python3'}}
34+
35+
…and, more importantly, the `cells`:
36+
37+
``` python
38+
minimal_txt.cells
39+
```
40+
41+
[{'cell_type': 'markdown',
42+
'metadata': {},
43+
'source': ['## A minimal notebook']},
44+
{'cell_type': 'code',
45+
'execution_count': None,
46+
'metadata': {},
47+
'outputs': [{'data': {'text/plain': ['2']},
48+
'execution_count': None,
49+
'metadata': {},
50+
'output_type': 'execute_result'}],
51+
'source': ['# Do some arithmetic\n', '1+1']}]
52+
53+
The second cell here is a `code` cell, however it contains no outputs,
54+
because it hasn’t been executed yet. To execute a notebook, we first
55+
need to convert it into a format suitable for `nbclient` (which expects
56+
some `dict` keys to be available as attrs, and some available as regular
57+
`dict` keys). Normally, `nbformat` is used for this step, but it’s
58+
rather slow and inflexible, so we’ll write our own function based on
59+
`fastcore`’s handy `dict2obj`, which makes all keys available as both
60+
attrs *and* keys.
61+
62+
------------------------------------------------------------------------
63+
64+
<a
65+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L21"
66+
target="_blank" style="float:right; font-size:smaller">source</a>
67+
68+
### NbCell
69+
70+
> NbCell (idx, cell)
71+
72+
*`dict` subclass that also provides access to keys as attrs*
73+
74+
We use an `AttrDict` subclass which has some basic functionality for
75+
accessing notebook cells.
76+
77+
------------------------------------------------------------------------
78+
79+
<a
80+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L50"
81+
target="_blank" style="float:right; font-size:smaller">source</a>
82+
83+
### dict2nb
84+
85+
> dict2nb (js=None, **kwargs)
86+
87+
*Convert dict `js` to an `AttrDict`,*
88+
89+
We can now convert our JSON into this `nbclient`-compatible format,
90+
which pretty prints the source code of cells in notebooks.
91+
92+
``` python
93+
minimal = dict2nb(minimal_txt)
94+
cell = minimal.cells[1]
95+
cell
96+
```
97+
98+
``` json
99+
{ 'cell_type': 'code',
100+
'execution_count': None,
101+
'idx_': 1,
102+
'metadata': {},
103+
'outputs': [ { 'data': {'text/plain': ['2']},
104+
'execution_count': None,
105+
'metadata': {},
106+
'output_type': 'execute_result'}],
107+
'source': '# Do some arithmetic\n1+1'}
108+
```
109+
110+
The abstract syntax tree of source code cells is available in the
111+
`parsed_` property:
112+
113+
``` python
114+
cell.parsed_(), cell.parsed_()[0].value.op
115+
```
116+
117+
([<ast.Expr>], <ast.Add>)
118+
119+
------------------------------------------------------------------------
120+
121+
<a
122+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L57"
123+
target="_blank" style="float:right; font-size:smaller">source</a>
124+
125+
### read_nb
126+
127+
> read_nb (path)
128+
129+
*Return notebook at `path`*
130+
131+
This reads the JSON for the file at `path` and converts it with
132+
[`dict2nb`](https://fastai.github.io/execnb/nbio.html#dict2nb). For
133+
instance:
134+
135+
``` python
136+
minimal = read_nb(minimal_fn)
137+
str(minimal.cells[0])
138+
```
139+
140+
"{'cell_type': 'markdown', 'metadata': {}, 'source': '## A minimal notebook', 'idx_': 0}"
141+
142+
The file name read is stored in `path_`:
143+
144+
``` python
145+
minimal.path_
146+
```
147+
148+
'../tests/minimal.ipynb'
149+
150+
## Creating a notebook
151+
152+
------------------------------------------------------------------------
153+
154+
<a
155+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L64"
156+
target="_blank" style="float:right; font-size:smaller">source</a>
157+
158+
### new_nb
159+
160+
> new_nb (cells=None, meta=None, nbformat=4, nbformat_minor=5)
161+
162+
*Returns an empty new notebook*
163+
164+
Use this function when creating a new notebook. Useful for when you
165+
don’t want to create a notebook on disk first and then read it.
166+
167+
------------------------------------------------------------------------
168+
169+
<a
170+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L69"
171+
target="_blank" style="float:right; font-size:smaller">source</a>
172+
173+
### mk_cell
174+
175+
> mk_cell (text, cell_type='code', **kwargs)
176+
177+
*Create an [`NbCell`](https://fastai.github.io/execnb/nbio.html#nbcell)
178+
containing `text`*
179+
180+
<table>
181+
<thead>
182+
<tr>
183+
<th></th>
184+
<th><strong>Type</strong></th>
185+
<th><strong>Default</strong></th>
186+
<th><strong>Details</strong></th>
187+
</tr>
188+
</thead>
189+
<tbody>
190+
<tr>
191+
<td>text</td>
192+
<td></td>
193+
<td></td>
194+
<td><code>source</code> attr in cell</td>
195+
</tr>
196+
<tr>
197+
<td>cell_type</td>
198+
<td>str</td>
199+
<td>code</td>
200+
<td><code>cell_type</code> attr in cell</td>
201+
</tr>
202+
<tr>
203+
<td>kwargs</td>
204+
<td></td>
205+
<td></td>
206+
<td></td>
207+
</tr>
208+
</tbody>
209+
</table>
210+
211+
``` python
212+
mk_cell('print(1)', execution_count=0)
213+
```
214+
215+
``` json
216+
{ 'cell_type': 'code',
217+
'directives_': {},
218+
'execution_count': 0,
219+
'idx_': 0,
220+
'metadata': {},
221+
'source': 'print(1)'}
222+
```
223+
224+
## Writing a notebook
225+
226+
------------------------------------------------------------------------
227+
228+
<a
229+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L81"
230+
target="_blank" style="float:right; font-size:smaller">source</a>
231+
232+
### nb2dict
233+
234+
> nb2dict (d, k=None)
235+
236+
*Convert parsed notebook to `dict`*
237+
238+
This returns the exact same dict as is read from the notebook JSON.
239+
240+
``` python
241+
minimal_fn = Path('../tests/minimal.ipynb')
242+
minimal = read_nb(minimal_fn)
243+
244+
minimal_dict = _read_json(minimal_fn)
245+
assert minimal_dict==nb2dict(minimal)
246+
```
247+
248+
------------------------------------------------------------------------
249+
250+
<a
251+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L89"
252+
target="_blank" style="float:right; font-size:smaller">source</a>
253+
254+
### nb2str
255+
256+
> nb2str (nb)
257+
258+
*Convert `nb` to a `str`*
259+
260+
To save a notebook we first need to convert it to a `str`:
261+
262+
``` python
263+
print(nb2str(minimal)[:45])
264+
```
265+
266+
{
267+
"cells": [
268+
{
269+
"cell_type": "markdown",
270+
271+
------------------------------------------------------------------------
272+
273+
<a
274+
href="https://github.com/fastai/execnb/blob/master/execnb/nbio.py#L95"
275+
target="_blank" style="float:right; font-size:smaller">source</a>
276+
277+
### write_nb
278+
279+
> write_nb (nb, path)
280+
281+
*Write `nb` to `path`*
282+
283+
This returns the exact same string as saved by Jupyter.
284+
285+
``` python
286+
tmp = Path('tmp.ipynb')
287+
try:
288+
minimal_txt = minimal_fn.read_text()
289+
write_nb(minimal, tmp)
290+
assert minimal_txt==tmp.read_text()
291+
finally: tmp.unlink()
292+
```
293+
294+
Here’s how to put all the pieces of `execnb.nbio` together:
295+
296+
``` python
297+
nb = new_nb([mk_cell('print(1)')])
298+
path = Path('test.ipynb')
299+
write_nb(nb, path)
300+
nb2 = read_nb(path)
301+
print(nb2.cells)
302+
path.unlink()
303+
```
304+
305+
[{'cell_type': 'code', 'metadata': {}, 'source': 'print(1)', 'idx_': 0}]

‎robots.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Sitemap: https://fastai.github.io/execnb/sitemap.xml

0 commit comments

Comments
 (0)