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.
Files changed (45) hide show
  1. {nbdev-3.3.28/nbdev.egg-info → nbdev-3.3.30}/PKG-INFO +3 -4
  2. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/__init__.py +1 -1
  3. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/clean.py +2 -1
  4. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/config.py +2 -3
  5. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/diff_core.py +5 -57
  6. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/doclinks.py +12 -8
  7. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/processors.py +14 -5
  8. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/serve.py +4 -6
  9. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/serve_drv.py +11 -1
  10. nbdev-3.3.30/nbdev/skill.py +60 -0
  11. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/test.py +2 -4
  12. {nbdev-3.3.28 → nbdev-3.3.30/nbdev.egg-info}/PKG-INFO +3 -4
  13. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/requires.txt +1 -4
  14. {nbdev-3.3.28 → nbdev-3.3.30}/pyproject.toml +3 -3
  15. {nbdev-3.3.28 → nbdev-3.3.30}/tests/test_diff.py +1 -14
  16. nbdev-3.3.28/nbdev/skill.py +0 -63
  17. {nbdev-3.3.28 → nbdev-3.3.30}/CONTRIBUTING.md +0 -0
  18. {nbdev-3.3.28 → nbdev-3.3.30}/LICENSE +0 -0
  19. {nbdev-3.3.28 → nbdev-3.3.30}/README.md +0 -0
  20. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/_modidx.py +0 -0
  21. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/cli.py +0 -0
  22. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/diff.py +0 -0
  23. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/export.py +0 -0
  24. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/extract_attachments.py +0 -0
  25. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/frontmatter.py +0 -0
  26. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/imports.py +0 -0
  27. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/maker.py +0 -0
  28. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/merge.py +0 -0
  29. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/migrate.py +0 -0
  30. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/moddocs.py +0 -0
  31. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/process.py +0 -0
  32. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/qmd.py +0 -0
  33. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/quarto.py +0 -0
  34. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/quarto_render.py +0 -0
  35. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/readme_filter.py +0 -0
  36. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/release.py +0 -0
  37. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/scrubmagics.py +0 -0
  38. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/showdoc.py +0 -0
  39. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev/sync.py +0 -0
  40. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/SOURCES.txt +0 -0
  41. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/dependency_links.txt +0 -0
  42. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/entry_points.txt +0 -0
  43. {nbdev-3.3.28 → nbdev-3.3.30}/nbdev.egg-info/top_level.txt +0 -0
  44. {nbdev-3.3.28 → nbdev-3.3.30}/setup.cfg +0 -0
  45. {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.28
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.10
15
+ Requires-Python: >=3.11
16
16
  Description-Content-Type: text/markdown
17
17
  License-File: LICENSE
18
- Requires-Dist: fastcore>=2.2.28
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.28"
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 and optionally ids from text reprs"
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
- try: import tomllib
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 difflib import unified_diff, SequenceMatcher
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
- lines = _source_lines(old_source, new_source, context, final_newline)
132
- if not lines: return ''
133
- body = [l.removesuffix('\n') for l in lines[2:]]
134
- res = [render_line(l, maxlen, color) if isinstance(l,str) else _render_spans(l, maxlen, color) for l in _refine(body)]
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 _re_backticks.sub(self._link_sym, l)
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
- in_fence=False
305
- lines = md.splitlines()
306
- for i,l in enumerate(lines):
307
- if l.startswith("```"): in_fence=not in_fence
308
- elif not l.startswith(' ') and not in_fence: lines[i] = self.link_line(l)
309
- return '\n'.join(lines)
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
- self.k = CaptureShell(profile=bool(get_config().exec_profile))
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 not hasattr(self, 'k'): return
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 ipynb processor (experimental)
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,subprocess,threading,sys
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=='.ipynb': return s,d,FilterDefaults
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
- kw = {} if in_notebook() else {'method':'spawn'}
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
- dst.write_text(res + f.getvalue())
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, **kw)
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.28
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.10
15
+ Requires-Python: >=3.11
16
16
  Description-Content-Type: text/markdown
17
17
  License-File: LICENSE
18
- Requires-Dist: fastcore>=2.2.28
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"
@@ -1,4 +1,4 @@
1
- fastcore>=2.2.28
1
+ fastcore>=2.2.45
2
2
  execnb>=0.3.3
3
3
  astunparse
4
4
  ghapi>=2.0.2
@@ -9,9 +9,6 @@ build
9
9
  fastgit>=0.0.7
10
10
  pyyaml
11
11
 
12
- [:python_version < "3.11"]
13
- tomli
14
-
15
12
  [dev]
16
13
  ipywidgets
17
14
  nbdev-numpy
@@ -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.10"
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.28", "execnb>=0.3.3", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
22
- "setuptools", "build", "fastgit>=0.0.7", "pyyaml", "tomli; python_version < '3.11'", ]
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, 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):
@@ -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