Skip to content

Commit d23a108

Browse files
github-actions[bot]github-actions[bot]
committed
deploy: a72eebb 
0 parents  commit d23a108

File tree

171 files changed

+82222
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

171 files changed

+82222
-0
lines changed

‎.nojekyll

Whitespace-only changes.

‎CNAME

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
nbdev.fast.ai

‎api/clean.html

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

‎api/clean.html.md

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# clean
2+
3+
4+
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
5+
6+
To avoid pointless conflicts while working with jupyter notebooks (with
7+
different execution counts or cell metadata), it is recommended to clean
8+
the notebooks before committing anything (done automatically if you
9+
install the git hooks with
10+
[`nbdev_install_hooks`](https://nbdev.fast.ai/api/clean.html#nbdev_install_hooks)).
11+
The following functions are used to do that.
12+
13+
## Trust
14+
15+
------------------------------------------------------------------------
16+
17+
<a
18+
href="https://github.com/AnswerDotAI/nbdev/blob/main/nbdev/clean.py#L25"
19+
target="_blank" style="float:right; font-size:smaller">source</a>
20+
21+
### nbdev_trust
22+
23+
> nbdev_trust (fname:str=None, force_all:bool=False)
24+
25+
*Trust notebooks matching `fname`*
26+
27+
<table>
28+
<thead>
29+
<tr>
30+
<th></th>
31+
<th><strong>Type</strong></th>
32+
<th><strong>Default</strong></th>
33+
<th><strong>Details</strong></th>
34+
</tr>
35+
</thead>
36+
<tbody>
37+
<tr>
38+
<td>fname</td>
39+
<td>str</td>
40+
<td>None</td>
41+
<td>A notebook name or glob to trust</td>
42+
</tr>
43+
<tr>
44+
<td>force_all</td>
45+
<td>bool</td>
46+
<td>False</td>
47+
<td>Also trust notebooks that haven’t changed</td>
48+
</tr>
49+
</tbody>
50+
</table>
51+
52+
## Clean
53+
54+
------------------------------------------------------------------------
55+
56+
<a
57+
href="https://github.com/AnswerDotAI/nbdev/blob/main/nbdev/clean.py#L86"
58+
target="_blank" style="float:right; font-size:smaller">source</a>
59+
60+
### clean_nb
61+
62+
> clean_nb (nb, clear_all=False, allowed_metadata_keys:list=None,
63+
> allowed_cell_metadata_keys:list=None, clean_ids=True)
64+
65+
*Clean `nb` from superfluous metadata*
66+
67+
<table>
68+
<colgroup>
69+
<col style="width: 6%" />
70+
<col style="width: 25%" />
71+
<col style="width: 34%" />
72+
<col style="width: 34%" />
73+
</colgroup>
74+
<thead>
75+
<tr>
76+
<th></th>
77+
<th><strong>Type</strong></th>
78+
<th><strong>Default</strong></th>
79+
<th><strong>Details</strong></th>
80+
</tr>
81+
</thead>
82+
<tbody>
83+
<tr>
84+
<td>nb</td>
85+
<td></td>
86+
<td></td>
87+
<td>The notebook to clean</td>
88+
</tr>
89+
<tr>
90+
<td>clear_all</td>
91+
<td>bool</td>
92+
<td>False</td>
93+
<td>Remove all cell metadata and cell outputs?</td>
94+
</tr>
95+
<tr>
96+
<td>allowed_metadata_keys</td>
97+
<td>list</td>
98+
<td>None</td>
99+
<td>Preserve the list of keys in the main notebook metadata</td>
100+
</tr>
101+
<tr>
102+
<td>allowed_cell_metadata_keys</td>
103+
<td>list</td>
104+
<td>None</td>
105+
<td>Preserve the list of keys in cell level metadata</td>
106+
</tr>
107+
<tr>
108+
<td>clean_ids</td>
109+
<td>bool</td>
110+
<td>True</td>
111+
<td>Remove ids from plaintext reprs?</td>
112+
</tr>
113+
</tbody>
114+
</table>
115+
116+
Jupyter adds a trailing <code></code> to images in cell outputs.
117+
Vscode-jupyter does not.
118+
Notebooks should be brought to a common style to avoid unnecessary
119+
diffs:
120+
121+
``` python
122+
test_nb = read_nb('../../tests/image.ipynb')
123+
assert test_nb.cells[0].outputs[0].data['image/png'][-1] == "\n" # Make sure it was not converted by acccident
124+
clean_nb(test_nb)
125+
assert test_nb.cells[0].outputs[0].data['image/png'][-1] != "\n"
126+
```
127+
128+
The test notebook has metadata in both the main metadata section and
129+
contains cell level metadata in the second cell:
130+
131+
``` python
132+
test_nb = read_nb('../../tests/metadata.ipynb')
133+
134+
assert {'meta', 'jekyll', 'my_extra_key', 'my_removed_key'} <= test_nb.metadata.keys()
135+
assert {'meta', 'hide_input', 'my_extra_cell_key', 'my_removed_cell_key'} == test_nb.cells[1].metadata.keys()
136+
```
137+
138+
After cleaning the notebook, all extra metadata is removed, only some
139+
keys are allowed by default:
140+
141+
``` python
142+
clean_nb(test_nb)
143+
144+
assert {'jekyll', 'kernelspec'} == test_nb.metadata.keys()
145+
assert {'hide_input'} == test_nb.cells[1].metadata.keys()
146+
```
147+
148+
We can preserve some additional keys at the notebook or cell levels:
149+
150+
``` python
151+
test_nb = read_nb('../../tests/metadata.ipynb')
152+
clean_nb(test_nb, allowed_metadata_keys={'my_extra_key'}, allowed_cell_metadata_keys={'my_extra_cell_key'})
153+
154+
assert {'jekyll', 'kernelspec', 'my_extra_key'} == test_nb.metadata.keys()
155+
assert {'hide_input', 'my_extra_cell_key'} == test_nb.cells[1].metadata.keys()
156+
```
157+
158+
Passing `clear_all=True` removes everything from the cell metadata:
159+
160+
``` python
161+
test_nb = read_nb('../../tests/metadata.ipynb')
162+
clean_nb(test_nb, clear_all=True)
163+
164+
assert {'jekyll', 'kernelspec'} == test_nb.metadata.keys()
165+
test_eq(test_nb.cells[1].metadata, {})
166+
```
167+
168+
Passing `clean_ids=True` removes `id`s from plaintext repr outputs, to
169+
avoid notebooks whose contents change on each run since they often lead
170+
to git merge conflicts. For example:
171+
172+
<PIL.PngImagePlugin.PngImageFile image mode=L size=28x28 at 0x7FB4F8979690>
173+
174+
becomes:
175+
176+
<PIL.PngImagePlugin.PngImageFile image mode=L size=28x28>
177+
178+
------------------------------------------------------------------------
179+
180+
<a
181+
href="https://github.com/AnswerDotAI/nbdev/blob/main/nbdev/clean.py#L109"
182+
target="_blank" style="float:right; font-size:smaller">source</a>
183+
184+
### process_write
185+
186+
> process_write (warn_msg, proc_nb, f_in, f_out=None, disp=False)
187+
188+
------------------------------------------------------------------------
189+
190+
<a
191+
href="https://github.com/AnswerDotAI/nbdev/blob/main/nbdev/clean.py#L132"
192+
target="_blank" style="float:right; font-size:smaller">source</a>
193+
194+
### nbdev_clean
195+
196+
> nbdev_clean (fname:str=None, clear_all:bool=False, disp:bool=False,
197+
> stdin:bool=False)
198+
199+
*Clean all notebooks in `fname` to avoid merge conflicts*
200+
201+
<table>
202+
<colgroup>
203+
<col style="width: 6%" />
204+
<col style="width: 25%" />
205+
<col style="width: 34%" />
206+
<col style="width: 34%" />
207+
</colgroup>
208+
<thead>
209+
<tr>
210+
<th></th>
211+
<th><strong>Type</strong></th>
212+
<th><strong>Default</strong></th>
213+
<th><strong>Details</strong></th>
214+
</tr>
215+
</thead>
216+
<tbody>
217+
<tr>
218+
<td>fname</td>
219+
<td>str</td>
220+
<td>None</td>
221+
<td>A notebook name or glob to clean</td>
222+
</tr>
223+
<tr>
224+
<td>clear_all</td>
225+
<td>bool</td>
226+
<td>False</td>
227+
<td>Remove all cell metadata and cell outputs?</td>
228+
</tr>
229+
<tr>
230+
<td>disp</td>
231+
<td>bool</td>
232+
<td>False</td>
233+
<td>Print the cleaned outputs</td>
234+
</tr>
235+
<tr>
236+
<td>stdin</td>
237+
<td>bool</td>
238+
<td>False</td>
239+
<td>Read notebook from input stream</td>
240+
</tr>
241+
</tbody>
242+
</table>
243+
244+
By default (`fname` left to `None`), all the notebooks in
245+
`config.nbs_path` are cleaned. You can opt in to fully clean the
246+
notebook by removing every bit of metadata and the cell outputs by
247+
passing `clear_all=True`.
248+
249+
If you want to keep some keys in the main notebook metadata you can set
250+
`allowed_metadata_keys` in `settings.ini`. Similarly for cell level
251+
metadata use: `allowed_cell_metadata_keys`. For example, to preserve
252+
both `k1` and `k2` at both the notebook and cell level adding the
253+
following in `settings.ini`:
254+
255+
...
256+
allowed_metadata_keys = k1 k2
257+
allowed_cell_metadata_keys = k1 k2
258+
...
259+
260+
------------------------------------------------------------------------
261+
262+
<a
263+
href="https://github.com/AnswerDotAI/nbdev/blob/main/nbdev/clean.py#L147"
264+
target="_blank" style="float:right; font-size:smaller">source</a>
265+
266+
### clean_jupyter
267+
268+
> clean_jupyter (path, model, **kwargs)
269+
270+
*Clean Jupyter `model` pre save to `path`*
271+
272+
This cleans notebooks on-save to avoid unnecessary merge conflicts. The
273+
easiest way to install it for both Jupyter Notebook and Lab is by
274+
running
275+
[`nbdev_install_hooks`](https://nbdev.fast.ai/api/clean.html#nbdev_install_hooks).
276+
It works by implementing a `pre_save_hook` from Jupyter’s [file save
277+
hook
278+
API](https://jupyter-server.readthedocs.io/en/latest/developers/savehooks.html).
279+
280+
## Hooks
281+
282+
------------------------------------------------------------------------
283+
284+
<a
285+
href="https://github.com/AnswerDotAI/nbdev/blob/main/nbdev/clean.py#L189"
286+
target="_blank" style="float:right; font-size:smaller">source</a>
287+
288+
### nbdev_install_hooks
289+
290+
> nbdev_install_hooks ()
291+
292+
*Install Jupyter and git hooks to automatically clean, trust, and fix
293+
merge conflicts in notebooks*
294+
295+
See
296+
[`clean_jupyter`](https://nbdev.fast.ai/api/clean.html#clean_jupyter)
297+
and [`nbdev_merge`](https://nbdev.fast.ai/api/merge.html#nbdev_merge)
298+
for more about how each hook works.

0 commit comments

Comments
 (0)