nbdev 3.3.28__tar.gz → 3.3.30__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {nbdev-3.3.28/nbdev.egg-info → nbdev-3.3.30}/PKG-INFO +3 -4
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/__init__.py +1 -1
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/clean.py +2 -1
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/config.py +2 -3
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/diff_core.py +5 -57
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/doclinks.py +12 -8
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/processors.py +14 -5
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/serve.py +4 -6
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/serve_drv.py +11 -1
- nbdev-3.3.30/nbdev/skill.py +60 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/test.py +2 -4
- {nbdev-3.3.28 → nbdev-3.3.30/nbdev.egg-info}/PKG-INFO +3 -4
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/requires.txt +1 -4
- {nbdev-3.3.28 → nbdev-3.3.30}/pyproject.toml +3 -3
- {nbdev-3.3.28 → nbdev-3.3.30}/tests/test_diff.py +1 -14
- nbdev-3.3.28/nbdev/skill.py +0 -63
- {nbdev-3.3.28 → nbdev-3.3.30}/CONTRIBUTING.md +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/LICENSE +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/README.md +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/_modidx.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/cli.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/diff.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/export.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/extract_attachments.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/frontmatter.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/imports.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/maker.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/merge.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/migrate.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/moddocs.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/process.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/qmd.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/quarto.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/quarto_render.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/readme_filter.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/release.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/scrubmagics.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/showdoc.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/sync.py +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/SOURCES.txt +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/dependency_links.txt +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/entry_points.txt +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/top_level.txt +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/setup.cfg +0 -0
- {nbdev-3.3.28 → nbdev-3.3.30}/tests/test_quarto_render.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: nbdev
|
|
3
|
-
Version: 3.3.
|
|
3
|
+
Version: 3.3.30
|
|
4
4
|
Summary: Create delightful software with Jupyter Notebooks
|
|
5
5
|
Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -12,10 +12,10 @@ Classifier: Intended Audience :: Developers
|
|
|
12
12
|
Classifier: Natural Language :: English
|
|
13
13
|
Classifier: Programming Language :: Python :: 3
|
|
14
14
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
-
Requires-Python: >=3.
|
|
15
|
+
Requires-Python: >=3.11
|
|
16
16
|
Description-Content-Type: text/markdown
|
|
17
17
|
License-File: LICENSE
|
|
18
|
-
Requires-Dist: fastcore>=2.2.
|
|
18
|
+
Requires-Dist: fastcore>=2.2.45
|
|
19
19
|
Requires-Dist: execnb>=0.3.3
|
|
20
20
|
Requires-Dist: astunparse
|
|
21
21
|
Requires-Dist: ghapi>=2.0.2
|
|
@@ -25,7 +25,6 @@ Requires-Dist: setuptools
|
|
|
25
25
|
Requires-Dist: build
|
|
26
26
|
Requires-Dist: fastgit>=0.0.7
|
|
27
27
|
Requires-Dist: pyyaml
|
|
28
|
-
Requires-Dist: tomli; python_version < "3.11"
|
|
29
28
|
Provides-Extra: dev
|
|
30
29
|
Requires-Dist: ipywidgets; extra == "dev"
|
|
31
30
|
Requires-Dist: nbdev-numpy; extra == "dev"
|
|
@@ -6,7 +6,7 @@ Modules:
|
|
|
6
6
|
- `nbdev.moddocs`: # Module docs: creating them from existing notebooks
|
|
7
7
|
- `nbdev.skill`: Write, read and review nbdev notebooks as source, documentation, examples and tests. You MUST read this before any work on a project with notebooks."""
|
|
8
8
|
|
|
9
|
-
__version__ = "3.3.
|
|
9
|
+
__version__ = "3.3.30"
|
|
10
10
|
|
|
11
11
|
from .doclinks import nbdev_export
|
|
12
12
|
from .showdoc import show_doc
|
|
@@ -62,12 +62,13 @@ def _clean_cell_output_id(lines):
|
|
|
62
62
|
|
|
63
63
|
# %% ../nbs/api/11_clean.ipynb #b4cde615
|
|
64
64
|
def _clean_cell_output(cell, clean_ids, allowed_out_meta_keys):
|
|
65
|
-
"Remove `cell` output execution count
|
|
65
|
+
"Remove `cell` output execution count, optionally ids from text reprs, and representations listed under `nbdev.strip`"
|
|
66
66
|
outputs = cell.get('outputs', [])
|
|
67
67
|
for o in outputs:
|
|
68
68
|
if 'execution_count' in o: o['execution_count'] = None
|
|
69
69
|
data = o.get('data', {})
|
|
70
70
|
data.pop("application/vnd.google.colaboratory.intrinsic+json", None)
|
|
71
|
+
for k in nested_idx(o, 'metadata', 'nbdev', 'strip') or []: data.pop(k, None)
|
|
71
72
|
for k in data:
|
|
72
73
|
if k.startswith('text') and clean_ids: data[k] = _clean_cell_output_id(data[k])
|
|
73
74
|
if k.startswith('image') and "svg" not in k: data[k] = data[k].rstrip()
|
|
@@ -22,8 +22,7 @@ import ast,importlib,re
|
|
|
22
22
|
from IPython.display import Markdown
|
|
23
23
|
from fastcore.nbio import read_nb,NbCell
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
except ImportError: import tomli as tomllib
|
|
25
|
+
import tomllib
|
|
27
26
|
|
|
28
27
|
# %% ../nbs/api/01_config.ipynb #117128e6
|
|
29
28
|
pyproject_nm = 'pyproject.toml'
|
|
@@ -171,7 +170,7 @@ def _find_nbdev_pyproject(path=None):
|
|
|
171
170
|
# %% ../nbs/api/01_config.ipynb #3dac70e0
|
|
172
171
|
nbdev_defaults = dict(nbs_path='nbs', doc_path='_docs', tst_flags='notest', recursive=True, readme_nb='index.ipynb',
|
|
173
172
|
clean_ids=True, clear_all=False, put_version_in_init=True, jupyter_hooks=False, custom_sidebar=False, branch='main',
|
|
174
|
-
doc_procs=[], export_procs=[], exec_profile=True, cell_timeout=600)
|
|
173
|
+
doc_procs=[], export_procs=[], exec_profile=True, exec_all=False, cell_timeout=600)
|
|
175
174
|
|
|
176
175
|
_path_keys = 'lib_path', 'nbs_path', 'doc_path'
|
|
177
176
|
|
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
"Word-level terminal diffs of plain text, shared by file and notebook rendering."
|
|
2
2
|
|
|
3
|
-
from
|
|
3
|
+
from fastcore.diff import MIN_RATIO, source_diff, diff_lines
|
|
4
4
|
from fastcore.utils import *
|
|
5
5
|
|
|
6
6
|
__all__ = ['MAXLEN', 'MIN_RATIO', 'truncate', 'render_line', 'source_diff', 'render_source_diff']
|
|
7
7
|
|
|
8
8
|
MAXLEN = 180 # Most visible characters per displayed line; 0 means unlimited
|
|
9
|
-
MIN_RATIO = 0.5 # Minimum shared-word similarity for merging a changed line pair
|
|
10
9
|
_dcolors = {'## …':'\x1b[34m', '# ':'\x1b[1;7m', '#':'\x1b[1m', '-':'\x1b[31m', '+':'\x1b[32m', '@':'\x1b[36m'}
|
|
11
10
|
_wcolors = {'-':'\x1b[31;9m', '+':'\x1b[32m'}
|
|
12
11
|
_wmarks = {'-':('[-','-]'), '+':('{+','+}')}
|
|
@@ -29,57 +28,6 @@ def render_line(
|
|
|
29
28
|
return f'{c}{line}\x1b[0m' if c else line
|
|
30
29
|
|
|
31
30
|
|
|
32
|
-
def _source_lines(old, new, context, final_newline):
|
|
33
|
-
def lines(s): return s.splitlines(keepends=True) if final_newline else [l+'\n' for l in s.splitlines()]
|
|
34
|
-
return list(unified_diff(lines(old), lines(new), n=context))
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
def source_diff(
|
|
38
|
-
old_source, # Original source string
|
|
39
|
-
new_source, # New source string
|
|
40
|
-
context=3, # Unchanged lines shown either side of a change
|
|
41
|
-
final_newline=True # Distinguish a missing final newline (unnecessary for notebook cells)?
|
|
42
|
-
):
|
|
43
|
-
"Unified source diff, including missing-final-newline markers."
|
|
44
|
-
lines = _source_lines(old_source, new_source, context, final_newline)
|
|
45
|
-
return '\n'.join(l.removesuffix('\n') + ('' if l.endswith('\n') else '\n\') for l in lines)
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
def _word_diff(a, b):
|
|
49
|
-
if a==b: return None
|
|
50
|
-
if SequenceMatcher(None, re.findall(r'\w+', a), re.findall(r'\w+', b), autojunk=False).ratio()<MIN_RATIO: return None
|
|
51
|
-
ta,tb = (re.findall(r'\w+|\s+|[^\w\s]', s) for s in (a,b))
|
|
52
|
-
res = []
|
|
53
|
-
for tag,i1,i2,j1,j2 in SequenceMatcher(None, ta, tb, autojunk=False).get_opcodes():
|
|
54
|
-
if tag=='equal': res.append((' ', ''.join(ta[i1:i2])))
|
|
55
|
-
else:
|
|
56
|
-
if i2>i1: res.append(('-', ''.join(ta[i1:i2])))
|
|
57
|
-
if j2>j1: res.append(('+', ''.join(tb[j1:j2])))
|
|
58
|
-
return res
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
def _refine(lines):
|
|
62
|
-
res,i = [],0
|
|
63
|
-
while i<len(lines):
|
|
64
|
-
if not lines[i].startswith('-'):
|
|
65
|
-
res.append(lines[i])
|
|
66
|
-
i += 1
|
|
67
|
-
continue
|
|
68
|
-
j = i
|
|
69
|
-
while j<len(lines) and lines[j].startswith('-'): j += 1
|
|
70
|
-
k = j
|
|
71
|
-
while k<len(lines) and lines[k].startswith('+'): k += 1
|
|
72
|
-
olds,news = lines[i:j],lines[j:k]
|
|
73
|
-
bo,bn = [],[]
|
|
74
|
-
for o,n in zip(olds,news):
|
|
75
|
-
w = _word_diff(o[1:], n[1:])
|
|
76
|
-
if w: res,bo,bn = res+bo+bn+[w],[],[]
|
|
77
|
-
else: bo,bn = bo+[o],bn+[n]
|
|
78
|
-
res += bo+olds[len(news):]+bn+news[len(olds):]
|
|
79
|
-
i = k
|
|
80
|
-
return res
|
|
81
|
-
|
|
82
|
-
|
|
83
31
|
def _slice_spans(spans, start, end):
|
|
84
32
|
res,pos = [],0
|
|
85
33
|
for k,t in spans:
|
|
@@ -128,10 +76,10 @@ def render_source_diff(
|
|
|
128
76
|
final_newline=True # Distinguish a missing final newline (unnecessary for notebook cells)?
|
|
129
77
|
):
|
|
130
78
|
"Render source changes, cropping long word-diff lines around the first change."
|
|
131
|
-
|
|
132
|
-
if not
|
|
133
|
-
|
|
134
|
-
|
|
79
|
+
rows = diff_lines(old_source, new_source, context=context, final_newline=final_newline, min_ratio=MIN_RATIO)
|
|
80
|
+
if not rows: return ''
|
|
81
|
+
res = [_render_spans(spans, maxlen, color) if kind=='!' else render_line(kind+''.join(t for _,t in spans), maxlen, color)
|
|
82
|
+
for kind,spans in rows]
|
|
135
83
|
if final_newline:
|
|
136
84
|
for name,text in (('old',old_source), ('new',new_source)):
|
|
137
85
|
if text and not text.endswith('\n'): res.append(render_line(fr'\ No newline at end of {name} file', maxlen, color))
|
|
@@ -230,6 +230,7 @@ def _qual_syms(entries):
|
|
|
230
230
|
|
|
231
231
|
# %% ../nbs/api/05_doclinks.ipynb #53505fa4
|
|
232
232
|
_re_backticks = re.compile(r'`([^`\s]+?)(?:\(\))?`')
|
|
233
|
+
_re_linkify = re.compile(r'\[(?:`[^`]*`|[^\]`])*\](?:\((?:[^()]|\([^()]*\))*\)|\[[^\]]*\])?|' + _re_backticks.pattern)
|
|
233
234
|
|
|
234
235
|
# %% ../nbs/api/05_doclinks.ipynb #3a24b883
|
|
235
236
|
@lru_cache(None)
|
|
@@ -291,19 +292,22 @@ class NbdevLookup:
|
|
|
291
292
|
|
|
292
293
|
def _link_sym(self, m):
|
|
293
294
|
l = m.group(1)
|
|
295
|
+
if l is None: return m.group(0)
|
|
294
296
|
s = self.doc(l)
|
|
295
297
|
if s is None: return m.group(0)
|
|
296
298
|
l = l.replace('\\', r'\\')
|
|
297
299
|
if m.group(0).endswith('()`'): l += '()'
|
|
298
300
|
return rf"[`{l}`]({s})"
|
|
299
301
|
|
|
300
|
-
def link_line(self, l): return
|
|
302
|
+
def link_line(self, l): return _re_linkify.sub(self._link_sym, l)
|
|
301
303
|
|
|
302
304
|
def linkify(self, md):
|
|
303
|
-
if md:
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
305
|
+
if not md: return md
|
|
306
|
+
fence = None
|
|
307
|
+
lines = md.splitlines(keepends=True)
|
|
308
|
+
for i,l in enumerate(lines):
|
|
309
|
+
if fence:
|
|
310
|
+
if re.fullmatch(rf' {{0,3}}{fence[0]}{{{len(fence)},}}\s*', l): fence = None
|
|
311
|
+
elif m := re.match(r' {0,3}(`{3,}|~{3,})', l): fence = m[1]
|
|
312
|
+
elif not l.startswith((' ', '\t')): lines[i] = self.link_line(l)
|
|
313
|
+
return ''.join(lines)
|
|
@@ -228,11 +228,15 @@ def _ast_contains(trees, types):
|
|
|
228
228
|
|
|
229
229
|
def _tl_contains(trees, types): return any(isinstance(t, types) for t in trees)
|
|
230
230
|
|
|
231
|
-
def _do_eval(cell):
|
|
231
|
+
def _do_eval(cell, all_cells=False, dflt=True, flags=frozenset()):
|
|
232
232
|
if cell_lang(cell) != 'python': return
|
|
233
233
|
if not cell.source or 'nbdev_export'+'()' in cell.source: return
|
|
234
234
|
trees = cell.parsed_()
|
|
235
235
|
if cell.cell_type != 'code' or not trees: return
|
|
236
|
+
if all_cells:
|
|
237
|
+
v = cell.directives_.get('eval')
|
|
238
|
+
run = dflt if v is None else v.lower() != 'false'
|
|
239
|
+
return run and not (cell.directives_.keys() & flags) and 'skip-execution' not in cell.metadata.get('tags', [])
|
|
236
240
|
if cell.directives_.get('eval', '').lower() == 'false': return
|
|
237
241
|
|
|
238
242
|
_show_dirs = {'export','exports','exporti','exec_doc'}
|
|
@@ -245,17 +249,22 @@ def _do_eval(cell):
|
|
|
245
249
|
|
|
246
250
|
# %% ../nbs/api/10_processors.ipynb #867cf721
|
|
247
251
|
class exec_show_docs(Processor):
|
|
248
|
-
"Execute cells needed for `show_docs` output, including exported cells and imports"
|
|
252
|
+
"Execute cells needed for `show_docs` output, including exported cells and imports, or every cell under `exec_all`"
|
|
249
253
|
def begin(self):
|
|
250
254
|
if nb_lang(self.nb) != 'python': return
|
|
251
|
-
|
|
255
|
+
cfg,fm = get_config(),getattr(self.nb, 'frontmatter_', {})
|
|
256
|
+
self.all_cells = str2bool(fm.get('exec_all', cfg.exec_all))
|
|
257
|
+
self.dflt = fm_default_eval(fm)
|
|
258
|
+
flags = cfg.tst_flags
|
|
259
|
+
self.flags = set(flags.split() if isinstance(flags, str) else flags)
|
|
260
|
+
self.k = CaptureShell(profile=bool(cfg.exec_profile))
|
|
252
261
|
self.k.run_cell('from nbdev.showdoc import show_doc')
|
|
253
262
|
|
|
254
263
|
def __call__(self, cell):
|
|
255
|
-
if not self.nb.has_docs_ or
|
|
264
|
+
if not hasattr(self, 'k') or not (self.nb.has_docs_ or self.all_cells): return
|
|
256
265
|
fm = getattr(self.nb, 'frontmatter_', {})
|
|
257
266
|
if str2bool(fm.get('skip_showdoc', False)): return
|
|
258
|
-
if _do_eval(cell): self.k.cell(cell)
|
|
267
|
+
if _do_eval(cell, self.all_cells, self.dflt, self.flags): self.k.cell(cell)
|
|
259
268
|
title = fm.get('title', '')
|
|
260
269
|
if (e := self.k.exc):
|
|
261
270
|
raise Exception(f"Error{' in notebook: '+title if title else ''} in cell {cell.idx_} :\n{cell.source}\n{type(e).__name__}: {e}") from e
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""A parallel
|
|
1
|
+
"""A parallel notebook and Quarto processor (experimental)
|
|
2
2
|
|
|
3
3
|
Docs: https://nbdev.fast.ai/api/serve.html.md"""
|
|
4
4
|
|
|
@@ -8,13 +8,12 @@ Docs: https://nbdev.fast.ai/api/serve.html.md"""
|
|
|
8
8
|
__all__ = ['proc_nbs']
|
|
9
9
|
|
|
10
10
|
# %% ../nbs/api/17_serve.ipynb #6899a335
|
|
11
|
-
import ast
|
|
11
|
+
import ast
|
|
12
12
|
from shutil import rmtree,copy2
|
|
13
13
|
from fnmatch import fnmatch
|
|
14
14
|
|
|
15
15
|
from fastcore.utils import *
|
|
16
16
|
from fastcore.parallel import parallel
|
|
17
|
-
from fastcore.script import call_parse
|
|
18
17
|
from fastcore.meta import delegates
|
|
19
18
|
|
|
20
19
|
from .config import get_config
|
|
@@ -46,7 +45,7 @@ def _proc_file(s, cache, path):
|
|
|
46
45
|
if d.exists() and s.stat().st_mtime<=d.stat().st_mtime: return
|
|
47
46
|
|
|
48
47
|
d.parent.mkdir(parents=True, exist_ok=True)
|
|
49
|
-
if s.suffix
|
|
48
|
+
if s.suffix in ('.ipynb','.qmd'): return s,d,FilterDefaults
|
|
50
49
|
md = _is_qpy(s)
|
|
51
50
|
if md is not None: return s,d,md.strip()
|
|
52
51
|
else: copy2(s,d)
|
|
@@ -95,7 +94,6 @@ def proc_nbs(
|
|
|
95
94
|
_rm_stale(cache, path)
|
|
96
95
|
|
|
97
96
|
files = files.map(_proc_file, cache=cache, path=path).filter()
|
|
98
|
-
|
|
99
|
-
parallel(nbdev.serve_drv.main, files, n_workers=n_workers, pause=0.01, **kw)
|
|
97
|
+
parallel(nbdev.serve_drv.main, files, n_workers=n_workers, pause=0.01, max_tasks_per_child=1)
|
|
100
98
|
if cache.exists(): cache.touch()
|
|
101
99
|
return cache
|
|
@@ -1,15 +1,24 @@
|
|
|
1
1
|
import os
|
|
2
2
|
from fastcore.nbio import read_nb,write_nb
|
|
3
|
+
from nbdev.doclinks import NbdevLookup
|
|
4
|
+
from nbdev.frontmatter import _re_fm_md
|
|
3
5
|
from io import StringIO
|
|
4
6
|
from contextlib import redirect_stdout
|
|
5
7
|
|
|
8
|
+
def link_qmd(text):
|
|
9
|
+
"Linkify a Quarto document without changing its YAML frontmatter."
|
|
10
|
+
fm = _re_fm_md.match(text)
|
|
11
|
+
start = fm.end() if fm else 0
|
|
12
|
+
return text[:start] + NbdevLookup().linkify(text[start:])
|
|
13
|
+
|
|
6
14
|
def exec_scr(src, dst, md):
|
|
7
15
|
f = StringIO()
|
|
8
16
|
g = {}
|
|
9
17
|
with redirect_stdout(f): exec(compile(src.read_text(), src, 'exec'), g)
|
|
10
18
|
res = ""
|
|
11
19
|
if md: res += "---\n" + md + "\n---\n\n"
|
|
12
|
-
|
|
20
|
+
text = res + f.getvalue()
|
|
21
|
+
dst.write_text(link_qmd(text) if dst.suffix=='.qmd' else text)
|
|
13
22
|
|
|
14
23
|
def exec_nb(src, dst, cb):
|
|
15
24
|
nb = read_nb(src)
|
|
@@ -21,6 +30,7 @@ def main(o):
|
|
|
21
30
|
os.environ["IN_TEST"] = "1"
|
|
22
31
|
if src.suffix=='.ipynb': exec_nb(src, dst, x)
|
|
23
32
|
elif src.suffix=='.py': exec_scr(src, dst, x)
|
|
33
|
+
elif src.suffix=='.qmd': dst.write_text(link_qmd(src.read_text()))
|
|
24
34
|
else: raise Exception(src)
|
|
25
35
|
del os.environ["IN_TEST"]
|
|
26
36
|
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# NB: this file is designed for an LLM reader, not a human. Add it to your LLM's context and ask it to explain.
|
|
2
|
+
"""Write, read and review nbdev notebooks as source, documentation, examples and tests. You MUST read this before any work on a project with notebooks.
|
|
3
|
+
|
|
4
|
+
notation: /why
|
|
5
|
+
|
|
6
|
+
## Source
|
|
7
|
+
|
|
8
|
+
- published library notebooks: implementation, explanation, examples, outputs, failure demos interleaved /read top to bottom; internal project: match neighbours
|
|
9
|
+
- per file: `# AUTOGENERATED! DO NOT EDIT!` → edit its notebook (`# %% ../nbs/04_usage.ipynb #a45f753a` names the cell), never module, `__all__`, `_modidx.py`, module docstring /`nbdev-export` regenerates them; unmarked: hand-written
|
|
10
|
+
- understand and review through notebooks and their git diff, not generated modules /no prose, examples, tests there
|
|
11
|
+
- notebooks teach APIs, lessons are the tests; plain `.py`, tested by `tests/*.py`: rare dense mechanism iterated under pytest; never add pytests to a project lacking them unless asked
|
|
12
|
+
- project questions: `nbs/index.ipynb`, README's source; after editing it: `nbdev-readme`
|
|
13
|
+
|
|
14
|
+
## Authoring
|
|
15
|
+
|
|
16
|
+
- before editing: whole notebook or every cell's summary
|
|
17
|
+
- new notebook: first read a role model such as claudette's `00_core.ipynb` for literate form; one of tutorial, how-to, explanation, reference; H1 title cell, `>` subtitle, intro; H2 per major concept, short narratives unsplit; each heading its own markdown cell /Jupyter collapse
|
|
18
|
+
- one idea at a time: small implementation, explanation, lesson; every substantive API gets a lesson; basic functionality outside the API with little logic: usually none
|
|
19
|
+
- lesson: markdown intro, split when complicated; extend examples, no near-duplicates: explain the differing argument, no repeated setup; classes: `@patch` each method beside its explanation unless that obscures the API
|
|
20
|
+
- new behaviour worth teaching (often not, for trivial logic): choose its narrative position; lesson first, ideally by changing an existing one; run preceding cells, see it fail; intro and implementation above it, see it pass; any changed assertion likewise fails on old code, passes on new
|
|
21
|
+
- bug fix: make an existing example hit the failing path only for subtle logic likely to recur or a tiny readable change, else add an assertion to it; never a cell just to witness a fix; no documented behaviour change: no lesson change
|
|
22
|
+
- explore in the notebook, not a separate kernel, after reading existing examples; keep useful findings as lessons, delete the rest; try to leave the notebook better
|
|
23
|
+
- `_name`: machinery without independent contract, not everything used internally; helper useful only internally: often awkward design
|
|
24
|
+
|
|
25
|
+
## Lessons
|
|
26
|
+
|
|
27
|
+
- readability first: code and displayed output guide readers through what code does; displayed value worth testing: assign, test, show; test the point, not incidentals like formatting; errors only where readers are likely to hit them
|
|
28
|
+
- realistic values, minimal setup, reused objects, direct supporting assertions; `fastcore.test`, `expect_fail`, in ordinary code cells
|
|
29
|
+
- evidence: compact `_repr_markdown_`, structured summary, plot, table, image, HTML; large output: say what matters, store focused results
|
|
30
|
+
- test-serving cells, e.g. safety-only setup, glue checks: off the page; usually remove; substantive logic check → `#| hide` or pytest; discuss such changes carefully
|
|
31
|
+
- reader-facing examples: no plumbing, mocks, dense comprehensions, long setup → small helper or hidden check
|
|
32
|
+
- rewrites to consider: commented example → markdown and code, keeping constraint comments; numbered steps → markdown/code pairs; `print` inside a sentence → prose or displayed value; final `print(x)` → `x`; reassignment stages, blank-line groups → introduced cells; `try`/`except` → `expect_fail`; long docstring → markdown; TODO, FIXME in example comments → resolve or issue
|
|
33
|
+
|
|
34
|
+
## Prose and exports
|
|
35
|
+
|
|
36
|
+
- markdown: rationale, distinctions, guarantees, extended explanation, examples, warnings; not code narration or filler; normally after definitions /generated page reads correctly
|
|
37
|
+
- symbol docstrings short; parameters, return: docments beside signature; backticked `symbol` → nbdev link
|
|
38
|
+
- module docstring: `nbdev-export` joins title's `>` description and exported markdown after H1; long: one exported markdown cell per major section; shared constraints, workflows only /`doc(module)` lists functions
|
|
39
|
+
- docstring beyond the default summary: only for modules read alone /`nbdev-export` then lists module in package docs, llms.txt
|
|
40
|
+
- `#| exportd`: code cell → fenced docstring source, not module code; compact runnable demo after its definitions; preceding exported summary ends with a colon; unexported cells between: omitted
|
|
41
|
+
- run code before documenting a claim; `nbdev.export.nb_mdoc` previews assembly
|
|
42
|
+
- `index.ipynb`: export opening paragraphs /package intro
|
|
43
|
+
|
|
44
|
+
## State and execution
|
|
45
|
+
|
|
46
|
+
- define near first use; introduce shared setup; reuse objects; never reassign names later cells use; exploration: end with an expression recording its finding, when useful
|
|
47
|
+
- imports: own cells, lessons too /docs builds run import cells in fresh namespaces: mixed state-dependent code fails or runs at docs time
|
|
48
|
+
- outputs: generated, may be stale mid-edit; source/output mismatch: keep working, never clear by hand or edit notebook JSON; `nbdev-test --save` at PR time if outputs are kept; `--file-re`: several named notebooks in parallel
|
|
49
|
+
|
|
50
|
+
## nbdev v3 (Jan 2026)
|
|
51
|
+
|
|
52
|
+
- `#| hide`: distracting necessities; exported `_helpers` needn't be public; `#| eval: false`: must not run, not broken; later cells can't use its state
|
|
53
|
+
- directives also as metadata `{"nbdev": {"export": "true"}}`; `fastcore.nbio.mk_cell(...).directives` merges both, content wins
|
|
54
|
+
- `pyproject.toml`, not `settings.ini`: `[project]` metadata, `[tool.nbdev]` settings (defaults `nbs_path='nbs'`, `doc_path='_docs'`), version via `dynamic = ["version"]` in `__init__.py`, `_modidx` in `[project.entry-points.nbdev]`
|
|
55
|
+
- CLIs hyphenated (`nbdev-export`, `nbdev-test`), Python names underscored; actions `fastai/workflows/nbdev3-ci`, `quarto-ghp3`
|
|
56
|
+
|
|
57
|
+
## Finish
|
|
58
|
+
|
|
59
|
+
- update affected prose, displays, assertions together; reread touched narrative for readability; `nbdev-test <nb>`
|
|
60
|
+
"""
|
|
@@ -156,7 +156,7 @@ def nbdev_test(
|
|
|
156
156
|
cell_timing_min:float=None, # Print cells slower than this many seconds (default `cell_timing_min` config, else none)
|
|
157
157
|
**kwargs
|
|
158
158
|
):
|
|
159
|
-
"Test in parallel notebooks matching `path`, passing along `flags`"
|
|
159
|
+
"Test in parallel notebooks matching `path`, each in a process of its own, passing along `flags`"
|
|
160
160
|
if path and not Path(path).exists(): kwargs['path_glob'],path = os.path.abspath(path),Path.cwd()
|
|
161
161
|
cfg = get_config(Path(path).resolve() if path else None)
|
|
162
162
|
cell_timeout,cell_timing_min = ifnone(cell_timeout, cfg.cell_timeout),ifnone(cell_timing_min, cfg.get('cell_timing_min'))
|
|
@@ -168,8 +168,6 @@ def nbdev_test(
|
|
|
168
168
|
if len(files)==0: return print('No files were eligible for testing')
|
|
169
169
|
|
|
170
170
|
if n_workers is None: n_workers = 0 if len(files)==1 else min(num_cpus(), 8)
|
|
171
|
-
if in_notebook(): kw = {'method':'spawn'} if os.name=='nt' or sys.platform=='darwin' else {'method':'forkserver'}
|
|
172
|
-
else: kw = {'method':'spawn'} if sys.platform=='darwin' else {}
|
|
173
171
|
wd_pth = cfg.nbs_path
|
|
174
172
|
with working_directory(wd_pth if (wd_pth and wd_pth.exists()) else os.getcwd()):
|
|
175
173
|
setup = cfg.get('test_setup')
|
|
@@ -177,7 +175,7 @@ def nbdev_test(
|
|
|
177
175
|
try:
|
|
178
176
|
results = parallel(test_nb, files, skip_flags=skip_flags, force_flags=force_flags, n_workers=n_workers,
|
|
179
177
|
basepath=cfg.config_path, pause=pause, do_print=do_print, verbose=verbose, save=save,
|
|
180
|
-
cell_timeout=cell_timeout or None, cell_timing_min=cell_timing_min,
|
|
178
|
+
cell_timeout=cell_timeout or None, cell_timing_min=cell_timing_min, max_tasks_per_child=1)
|
|
181
179
|
except KeyboardInterrupt:
|
|
182
180
|
sys.stderr.write('\nnbdev-test interrupted; in-flight notebook stacks shown above\n')
|
|
183
181
|
sys.exit(130)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: nbdev
|
|
3
|
-
Version: 3.3.
|
|
3
|
+
Version: 3.3.30
|
|
4
4
|
Summary: Create delightful software with Jupyter Notebooks
|
|
5
5
|
Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -12,10 +12,10 @@ Classifier: Intended Audience :: Developers
|
|
|
12
12
|
Classifier: Natural Language :: English
|
|
13
13
|
Classifier: Programming Language :: Python :: 3
|
|
14
14
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
-
Requires-Python: >=3.
|
|
15
|
+
Requires-Python: >=3.11
|
|
16
16
|
Description-Content-Type: text/markdown
|
|
17
17
|
License-File: LICENSE
|
|
18
|
-
Requires-Dist: fastcore>=2.2.
|
|
18
|
+
Requires-Dist: fastcore>=2.2.45
|
|
19
19
|
Requires-Dist: execnb>=0.3.3
|
|
20
20
|
Requires-Dist: astunparse
|
|
21
21
|
Requires-Dist: ghapi>=2.0.2
|
|
@@ -25,7 +25,6 @@ Requires-Dist: setuptools
|
|
|
25
25
|
Requires-Dist: build
|
|
26
26
|
Requires-Dist: fastgit>=0.0.7
|
|
27
27
|
Requires-Dist: pyyaml
|
|
28
|
-
Requires-Dist: tomli; python_version < "3.11"
|
|
29
28
|
Provides-Extra: dev
|
|
30
29
|
Requires-Dist: ipywidgets; extra == "dev"
|
|
31
30
|
Requires-Dist: nbdev-numpy; extra == "dev"
|
|
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
|
|
|
6
6
|
name = "nbdev"
|
|
7
7
|
description = "Create delightful software with Jupyter Notebooks"
|
|
8
8
|
readme = "README.md"
|
|
9
|
-
requires-python = ">=3.
|
|
9
|
+
requires-python = ">=3.11"
|
|
10
10
|
license = "Apache-2.0"
|
|
11
11
|
authors = [{name = "Jeremy Howard and the fast.ai community", email = "j@fast.ai"}]
|
|
12
12
|
keywords = ["nbdev", "fastai", "jupyter", "notebook", "export"]
|
|
@@ -18,8 +18,8 @@ classifiers = [
|
|
|
18
18
|
"Programming Language :: Python :: 3 :: Only",
|
|
19
19
|
]
|
|
20
20
|
dynamic = ["version"]
|
|
21
|
-
dependencies = [ "fastcore>=2.2.
|
|
22
|
-
"setuptools", "build", "fastgit>=0.0.7", "pyyaml",
|
|
21
|
+
dependencies = [ "fastcore>=2.2.45", "execnb>=0.3.3", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
|
|
22
|
+
"setuptools", "build", "fastgit>=0.0.7", "pyyaml", ]
|
|
23
23
|
|
|
24
24
|
[project.optional-dependencies]
|
|
25
25
|
dev = [ "ipywidgets", "nbdev-numpy", "nbdev-stdlib", "pandas", "matplotlib", "black", "svg.py", "pysym2md>=0.0.6", "llms-txt", "sphinx", "plum-dispatch", "nbclient", "ipykernel", "pytest", ]
|
|
@@ -1,17 +1,6 @@
|
|
|
1
1
|
import os, re, shlex, subprocess, sys
|
|
2
2
|
from fastcore.nbio import new_nb, write_nb
|
|
3
|
-
from nbdev.diff_core import render_source_diff
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
def test_source_changes():
|
|
7
|
-
old = 'x=1\ny=2\nz=3\nk=4\n'
|
|
8
|
-
new = 'x = 100\ny=2\nw=5\nq=6\n'
|
|
9
|
-
result = render_source_diff(old, new)
|
|
10
|
-
assert '!x{+ +}=[-1-]{+ 100+}' in result
|
|
11
|
-
assert '-z=3\n-k=4\n+w=5\n+q=6' in result
|
|
12
|
-
assert '+hello' in render_source_diff('', 'hello\n')
|
|
13
|
-
assert '-hello' in render_source_diff('hello\n', '')
|
|
14
|
-
assert not render_source_diff(old, old)
|
|
3
|
+
from nbdev.diff_core import render_source_diff
|
|
15
4
|
|
|
16
5
|
|
|
17
6
|
def test_long_line_changes():
|
|
@@ -34,10 +23,8 @@ def test_long_line_changes():
|
|
|
34
23
|
|
|
35
24
|
|
|
36
25
|
def test_final_newline():
|
|
37
|
-
assert r'' in source_diff('hello\n', 'hello')
|
|
38
26
|
assert 'new file' in render_source_diff('hello\n', 'hello')
|
|
39
27
|
assert 'old file' in render_source_diff('hello', 'hello\n')
|
|
40
|
-
assert not render_source_diff('hello\n', 'hello', final_newline=False)
|
|
41
28
|
|
|
42
29
|
|
|
43
30
|
def test_git_driver(tmp_path):
|
nbdev-3.3.28/nbdev/skill.py
DELETED
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
"""Write, read and review nbdev notebooks as source, documentation, examples and tests. You MUST read this before any work on a project with notebooks.
|
|
2
|
-
|
|
3
|
-
## Source and reading
|
|
4
|
-
|
|
5
|
-
Published-library notebooks: interleave implementation, explanation, examples, outputs and failure demonstrations for top-to-bottom reading. Internal projects: match surrounding notebooks.
|
|
6
|
-
|
|
7
|
-
Check each file, not the repo: `# AUTOGENERATED! DO NOT EDIT!` names the source notebook; `# %% ../nbs/04_usage.ipynb #a45f753a` identifies its source cell. Edit that notebook, never generated modules, `__all__`, `_modidx.py`, or module docstrings; `nbdev-export` regenerates them. Unmarked modules are hand-written. Understand and review work through notebooks and their `git diff`, never generated modules: those lack prose, examples and tests.
|
|
8
|
-
|
|
9
|
-
Use notebooks to teach APIs through narrative/examples, plain `.py` for dense mechanism iterated under pytest (rarely; never add pytests to a project without them unless asked). Lessons test notebook code; `tests/*.py` test plain modules. For project-level questions, read `nbs/index.ipynb` (README.md's source); regenerate with `nbdev-readme` after changes.
|
|
10
|
-
|
|
11
|
-
## Authoring
|
|
12
|
-
|
|
13
|
-
Before notebook edits, read the whole notebook or a summary of every cell. For a new notebook, read a role model such as claudette's `00_core.ipynb` to learn the literate form. Choose tutorial, how-to, explanation, or reference. Open with an H1 title cell, `>` subtitle and brief introduction. Use H2s for major concepts without fragmenting short narratives; each heading gets its own markdown cell for Jupyter collapse.
|
|
14
|
-
|
|
15
|
-
Develop one idea at a time: small implementation, explanation, lesson for every substantive API. Basic functionality outside the API, with little logic, generally needs no lesson. Introduce lessons in markdown; split when the introduction becomes complicated. Extend examples rather than adding near-duplicates. Build classes with `@patch` beside each method's explanation unless that obscures the API.
|
|
16
|
-
|
|
17
|
-
When new behavior needs teaching (often unnecessary for trivial logic), choose its narrative position, write the lesson first (better, slightly modify an existing lesson), run preceding cells as needed, see it fail. Add its markdown introduction and implementation above it; run implementation and lesson to see it pass. For bugs, revise an existing example to exercise the failing path; if no revision fits, add an assertion to it. No documented behavior change: change no lesson cells. Never add a cell merely to witness a fix.
|
|
18
|
-
|
|
19
|
-
Read existing examples before experimenting. Explore in the notebook, not a separate kernel check; keep useful explorations as lessons, delete the rest. Always try to leave the notebook better. Reserve underscore names for machinery without a coherent independent contract, not everything used internally. A helper useful only internally often signals awkward design.
|
|
20
|
-
|
|
21
|
-
## Lessons
|
|
22
|
-
|
|
23
|
-
Readability comes first: guide readers through what code does using code and displayed output. If a displayed value is worth testing, assign, test, then show it. Test the point of the code, not incidentals such as formatting. Show errors only when readers are likely to hit them.
|
|
24
|
-
|
|
25
|
-
Use realistic values, minimal setup, reused objects and direct supporting assertions. Show evidence with compact `_repr_markdown_`, structured summaries, plots, tables, images or HTML; explain what matters in large outputs and keep stored results focused. Use `fastcore.test` assertions and `expect_fail` in ordinary code cells.
|
|
26
|
-
|
|
27
|
-
Test-serving cells don't belong on the page: signs include safety-only setup and glue checks. Usually remove them; move substantive logic checks to `#| hide` or pytest. Discuss such changes carefully. Keep plumbing, mocks, dense comprehensions and long setup out of reader-facing examples: extract a small helper or hide the check.
|
|
28
|
-
|
|
29
|
-
Consider these rewrites:
|
|
30
|
-
- Commented examples -> prose/code; numbered steps -> markdown/code pairs. Keep comments stating constraints code cannot show.
|
|
31
|
-
- Sentence-wrapped `print` -> prose/displayed value; final `print(x)` -> bare `x`.
|
|
32
|
-
- Reassignment stages and blank-line groups -> separate cells, each introduced.
|
|
33
|
-
- Near-duplicates: explain the differing argument; don't repeat setup.
|
|
34
|
-
- Errors: `expect_fail`, not `try`/`except`. Long docstrings -> markdown.
|
|
35
|
-
- Resolve TODO/FIXME example comments or move them to issues.
|
|
36
|
-
|
|
37
|
-
## Prose and exports
|
|
38
|
-
|
|
39
|
-
In markdown, explain rationale, distinctions and guarantees, not code line-by-line or filler transitions. Place it for correct generated-page reading, normally after definitions. Use short symbol docstrings, parameter/return docments beside signatures and backticked symbols for nbdev links. Extended explanation, examples and warnings belong in markdown.
|
|
40
|
-
|
|
41
|
-
`nbdev-export` assembles module docstrings from the title's `>` description and exported markdown after H1; use one exported markdown cell per major section for long docstrings. `doc(module)` lists functions; in module prose, explain only shared constraints/workflows.
|
|
42
|
-
|
|
43
|
-
`#| exportd` includes a code cell as fenced docstring source, not module code. Use compact runnable demos after required definitions; end the preceding exported summary with a colon. Intervening unexported definitions don't appear in the docstring. Check claims by running code before documenting; preview assembly with `nbdev.export.nb_mdoc`. A docstring beyond the default summary makes `nbdev-export` list the module in package docs and `llms.txt`. Only extend docstrings of modules read independently. Export `index.ipynb`'s opening paragraphs for the package intro.
|
|
44
|
-
|
|
45
|
-
## State and execution
|
|
46
|
-
|
|
47
|
-
Define values near first use, introduce shared setup, reuse established objects; don't reassign names later cells depend on. End explorations with the expression recording what was learned when useful. Keep imports in dedicated cells, lessons included: docs builds execute import-containing cells in fresh namespaces; mixed state-dependent code can fail or run at documentation time.
|
|
48
|
-
|
|
49
|
-
Outputs are generated and may be stale during edits. Don't stop work, clear them manually, or edit notebook JSON because of source/output mismatch. At PR time, regenerate with `nbdev-test --save` if the project keeps saved outputs. `nbdev-test --file-re` runs several named notebooks in parallel.
|
|
50
|
-
|
|
51
|
-
## Directives and nbdev v3
|
|
52
|
-
|
|
53
|
-
- `#| default_exp` names the generated module; `#| export` includes a cell there. Exported underscore helpers need not be public.
|
|
54
|
-
- `#| hide` hides distracting necessities from the page.
|
|
55
|
-
- `#| eval: false`: code that must not run, not broken code. Later cells can't use its state.
|
|
56
|
-
- Metadata directives work too: `{"nbdev": {"export": "true"}}`; `fastcore.nbio.mk_cell(...).directives` merges both forms, content winning conflicts.
|
|
57
|
-
|
|
58
|
-
nbdev v3 (Jan 2026): `pyproject.toml`, not `settings.ini`; metadata in `[project]`, settings in `[tool.nbdev]` (defaults `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, `_modidx` in `[project.entry-points.nbdev]`. CLIs use hyphens (`nbdev-export`, `nbdev-test`); Python names retain underscores. GitHub actions: `fastai/workflows/nbdev3-ci`, `quarto-ghp3`.
|
|
59
|
-
|
|
60
|
-
## Finish
|
|
61
|
-
|
|
62
|
-
Revise affected prose, displays and assertions together; changed assertions must fail on old code and pass on new. Re-read touched narrative for readability. Run `nbdev-test <nb>`.
|
|
63
|
-
"""
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|