nbdev 3.3.12__tar.gz → 3.3.13__tar.gz

{nbdev-3.3.12/nbdev.egg-info → nbdev-3.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.12
+Version: 3.3.13
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License: Apache-2.0
@@ -17,7 +17,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.7
-Requires-Dist: execnb>=0.3.2
+Requires-Dist: execnb>=0.3.3
 Requires-Dist: astunparse
 Requires-Dist: ghapi>=2.0.2
 Requires-Dist: watchdog

{nbdev-3.3.12 → nbdev-3.3.13}/nbdev/__init__.py

@@ -4,9 +4,9 @@ Modules:
 
 - `nbdev.extract_attachments`: A preprocessor that extracts all of the attachments from the notebook file. The extracted attachments are returned in the 'resources' dictionary.
 - `nbdev.moddocs`: # Module docs: creating them from existing notebooks
-- `nbdev.skill`: Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative."""
+- `nbdev.skill`: Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative. Trigger: ALWAYS read this before ANY notebook edit."""
 
-__version__ = "3.3.12"
+__version__ = "3.3.13"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.12 → nbdev-3.3.13}/nbdev/config.py

@@ -315,9 +315,15 @@ def set_version(path, version):
     fname.write_text(code)
 
 # %% ../nbs/api/01_config.ipynb #d00889e5
-def bump_version(v, part=2, unbump=False):
-    "Bump semver part `part` (0=major, 1=minor, 2=patch), counted from the right"
-    parts = (v or '0.0.0').split('.')
+def bump_version(v, part=None, unbump=False):
+    "Bump `.postN` by default when present, otherwise a semver part counted from the right"
+    v = v or '0.0.0'
+    post = re.fullmatch(r'(.*)\.post(\d+)', v)
+    if part is None and post:
+        n = max(0, int(post[2]) + (-1 if unbump else 1))
+        return f'{post[1]}.post{n}'
+    if part is None: part = 2
+    parts = (post[1] if post else v).split('.')
     parts += ['0'] * (3 - len(parts))
     idx = len(parts) - 3 + part
     parts[idx] = str(int(parts[idx]) + (-1 if unbump else 1))

{nbdev-3.3.12 → nbdev-3.3.13}/nbdev/release.py

@@ -386,7 +386,7 @@ def release_both(
 # %% ../nbs/api/18_release.ipynb #c0f64b2c
 @call_parse
 def nbdev_bump_version(
-    part:int=2,  # Part of version to bump
+    part:int=None,  # Release part to bump; defaults to post when present, otherwise patch
     unbump:bool=False):  # Reduce version instead of increasing it
     "Increment version in __init__.py by one"
     cfg = get_config()

{nbdev-3.3.12 → nbdev-3.3.13}/nbdev/skill.py

@@ -1,4 +1,4 @@
-"""Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative.
+"""Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative. Trigger: ALWAYS read this before ANY notebook edit.
 
 # The notebook is the product
 
@@ -22,6 +22,15 @@ Open with an H1 title cell plus `>` subtitle line, introduce the page in a sente
 
 Add the smallest useful implementation, explain what it does and why it has that form, demonstrate it executably, assert where that improves the example, display the result a reader should notice, move on. A cell may bundle several closely related checks, but needs a markdown introduction saying what it establishes. If the introduction gets complicated, split the cell. Prefer extending an existing example over adding a near-duplicate cell. Build classes incrementally with `@patch` so each method sits beside its explanation, unless splitting makes the API harder to understand.
 
+# Authoring sequence
+
+Read the whole notebook before changing it. The interleaved prose, examples, and stored outputs are the design rationale. For a new notebook, first read enough of a role-model notebook, such as claudette's `00_core.ipynb`, to learn the literate form.
+
+Pick the place in the narrative where the change belongs. Write the lesson cell for the new behavior first. Run the cells above that place when it needs earlier state. Run the new cell and see it fail. Add a markdown cell above it that introduces the behavior it demonstrates. Add the implementation cell above that. Run the implementation, then the lesson cell, and see it pass.
+
+For a bug fix, do not add a new lesson cell by default. A regression test per fix is a pytest habit. Revise an existing lesson cell so its example passes through the bug's path, and see it fail before the fix. When no revision fits the example, add one assertion line to it. When the fix changes no documented behavior, change no cells.
+
+Explore inside the notebook, not in the kernel. A check that answered your question while building answers it for the next reader. Keep it as a lesson cell, or delete it before finishing when it taught nothing worth keeping.
 # Helpers
 
 Internal use is often the first evidence an abstraction is worth exposing, not a reason to hide it. Reserve underscores for machinery with no coherent independent contract. A helper only useful to the library itself hints at an awkward internal design.
@@ -40,19 +49,19 @@ Keep docstrings to a short statement of what the symbol does. Extended explanati
 
 Preview the assembled docstring with `nbdev.export.nb_mdoc`, and run code to check each claim before writing it. `nbdev-export` adds the module to the generated package docstring and `llms.txt` once its docstring says more than the default summary line, so write these cells only for modules meant to be read on their own. For the package intro, tag the opening paragraphs of `index.ipynb` with `#| export`.
 
-# Examples are documentation and tests
+# Lesson cells
 
-Write each example as page content first, then make it verify behavior: realistic values, the shortest path to the idea, an informative displayed result, direct assertions that reinforce the lesson, reuse of objects introduced earlier, and important errors demonstrated executably with `expect_fail` (one focused example per contract). Keep test plumbing out of reader-facing cells. Mocks, dense comprehensions, and long setup make poor documentation, so extract a tiny helper or hide the check. Assertions verify, but only the final expression's display teaches. End cells with the value worth showing, and design a compact `_repr_markdown_` or structured summary when it turns later examples into documentation for free. Plots, tables, images, and rich HTML all count as evidence. Stored outputs are part of the explanation. Keep them focused, and never dump a large structure without saying what matters in it. Test helpers come from `fastcore.test` (`test_eq`, `expect_fail`, ...), in plain code cells.
+An nbdev notebook has no test cells (rare `#| hide` checks aside). It has *lesson cells*: code cells that teach a point on the page, whose displayed result is the evidence and whose assertions keep the lesson honest forever. Write each one as page content first, then make it verify behavior: realistic values, the shortest path to the idea, an informative displayed result, direct assertions that reinforce the lesson, reuse of objects introduced earlier, and important errors demonstrated executably with `expect_fail` (one focused example per contract). Keep check plumbing out of reader-facing cells. Mocks, dense comprehensions, and long setup make poor documentation, so extract a tiny helper or hide the check. Assertions verify, but only the final expression's display teaches. End cells with the value worth showing, and design a compact `_repr_markdown_` or structured summary when it turns later examples into documentation for free. Plots, tables, images, and rich HTML all count as evidence. Stored outputs are part of the explanation. Keep them focused, and never dump a large structure without saying what matters in it. Assertion helpers come from `fastcore.test` (`test_eq`, `expect_fail`, ...), in plain code cells.
 
 # Tells
 
-Some patterns in a test or example cell can be spotted mechanically, and each reliably signals a rewrite that would improve the page. Each is a strong hint rather than a law. In particular, a comment sometimes states a constraint the code cannot show, and such a comment stays.
+Some patterns in a lesson cell can be spotted mechanically, and each reliably signals a rewrite that would improve the page. Each is a strong hint rather than a law. In particular, a comment sometimes states a constraint the code cannot show, and such a comment stays.
 
 - A comment in an example cell usually marks where the cell should split in two. Split there, and grow the comment into a markdown cell introducing what the next code cell shows.
 - Comments numbering steps mark a tutorial sequence. Give each step its own markdown and code pair.
 - A `print` whose f-string wraps a result in a sentence is prose in code. The sentence belongs in markdown, and the value belongs at the end of the cell as its displayed result.
 - A `print(x)` as a cell's last line hides the rich repr. End with bare `x` instead.
-- A test or example cell that doesn't end in an evaluation to display (its last line is an assertion or an assignment) verifies without teaching. End with the value the checks are about.
+- A lesson cell that doesn't end in an evaluation to display (its last line is an assertion or an assignment) verifies without teaching. End with the value the checks are about.
 - One name reassigned through stages in a single cell hides the intermediate values, which are the point. Give each stage its own cell, ending with a display.
 - Blank lines dividing a cell into groups mark candidate cell boundaries, and each group needs its own sentence of markdown.
 - Adjacent near-duplicate cells differing in one argument are a comparison written as copies. Make the difference the narrative ("with `strict=True` the same call raises...").
@@ -62,7 +71,7 @@ Some patterns in a test or example cell can be spotted mechanically, and each re
 
 # State flows downward
 
-Keep imports in dedicated import cells, define values near first use, reuse established objects, don't reassign names later cells depend on, introduce shared setup explicitly, and end exploratory cells with the expression whose output records what was learned, so a reader never searches far upward for where a value came from. The import rule is strict and covers test cells. The docs build runs each import-containing cell in a fresh namespace where no other cell has run, so a cell mixing imports with other code breaks the build or silently runs at documentation time.
+Keep imports in dedicated import cells, define values near first use, reuse established objects, don't reassign names later cells depend on, introduce shared setup explicitly, and end exploratory cells with the expression whose output records what was learned, so a reader never searches far upward for where a value came from. The import rule is strict and covers lesson cells. The docs build runs each import-containing cell in a fresh namespace where no other cell has run, so a cell mixing imports with other code breaks the build or silently runs at documentation time.
 
 # Directives
 
@@ -76,5 +85,5 @@ Directives can also live in cell *metadata*, under the `nbdev` key (`{"nbdev": {
 
 # Before you finish
 
-Each new test cell ran red then green, failing before the change and passing after. Re-read the touched section as a reader would, against the conventions above. Style damage breaks no test and no export, so the harm only shows on the docs page.
+A behavior change means revising the lesson cells it touches: prose, displayed output, and assertions move together. Where you revised or added an assertion, check it fails against the old code and passes against the new. Many changes need no new cell at all - never add one merely to witness a change. Re-read the touched section as a reader would, against the conventions above. Style damage breaks no test and no export, so the harm only shows on the docs page.
 """

{nbdev-3.3.12 → nbdev-3.3.13}/nbdev/test.py

@@ -65,7 +65,8 @@ def test_nb(
     verbose=False,  # stream stdout/stderr from cells to console?
     save=False,  # write outputs back to notebook on success?
     profile:bool=None, # load the IPython profile, as `ipykernel` does? (default: `exec_profile` config key)
-    cell_timeout:int=600  # seconds before each cell times out (None: no limit)
+    cell_timeout:int=600, # seconds before each cell times out (None: no limit)
+    cell_timing_min:float=None # print cells slower than this many seconds (None: no timing output)
 ):
     "Execute tests in notebook in `fn` except those with `skip_flags`"
     if not IN_NOTEBOOK and threading.current_thread() is threading.main_thread(): signal.signal(signal.SIGINT, _int_handler)
@@ -86,6 +87,10 @@ def test_nb(
             if not does_cell_eval(cell, dflt): return True
             return flags & (getattr(cell, 'directives_', {}) or {}).keys()
 
+        def _postproc(cell):
+            elapsed = cell.metadata['execution']['total']
+            if cell_timing_min is not None and elapsed > cell_timing_min: print(f'{fn.name}:{cell.id}: {elapsed:.3f}s')
+
         start = time.time()
         if profile is None: profile = bool(get_config(fn.parent).exec_profile)
         k = CaptureShell(fn, profile=profile)
@@ -93,7 +98,7 @@ def test_nb(
         if do_print: print(f'Starting {fn}')
         try:
             with working_directory(fn.parent):
-                k.run_all(nb, exc_stop=True, preproc=_no_eval, verbose=verbose, cell_timeout=cell_timeout)
+                k.run_all(nb, exc_stop=True, preproc=_no_eval, postproc=_postproc, verbose=verbose, cell_timeout=cell_timeout)
                 if save: write_nb(nb, fn)
                 res = True
         except: 
@@ -131,6 +136,7 @@ def nbdev_test(
     verbose:bool=False, # Print stdout/stderr from notebook cells?
     save:bool=False, # Write outputs back to notebooks on success?
     cell_timeout:int=600, # Seconds before each cell times out (0: no limit)
+    cell_timing_min:float=None, # Print cells slower than this many seconds (None: no timing output)
     **kwargs
 ):
     "Test in parallel notebooks matching `path`, passing along `flags`"
@@ -150,7 +156,7 @@ def nbdev_test(
         try:
             results = parallel(test_nb, files, skip_flags=skip_flags, force_flags=force_flags, n_workers=n_workers,
                                basepath=cfg.config_path, pause=pause, do_print=do_print, verbose=verbose, save=save,
-                               cell_timeout=cell_timeout or None, **kw)
+                               cell_timeout=cell_timeout or None, cell_timing_min=cell_timing_min, **kw)
         except KeyboardInterrupt:
             sys.stderr.write('\nnbdev-test interrupted; in-flight notebook stacks shown above\n')
             sys.exit(130)

{nbdev-3.3.12 → nbdev-3.3.13/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.12
+Version: 3.3.13
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License: Apache-2.0
@@ -17,7 +17,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.7
-Requires-Dist: execnb>=0.3.2
+Requires-Dist: execnb>=0.3.3
 Requires-Dist: astunparse
 Requires-Dist: ghapi>=2.0.2
 Requires-Dist: watchdog

{nbdev-3.3.12 → nbdev-3.3.13}/nbdev.egg-info/requires.txt

@@ -1,5 +1,5 @@
 fastcore>=2.2.7
-execnb>=0.3.2
+execnb>=0.3.3
 astunparse
 ghapi>=2.0.2
 watchdog

{nbdev-3.3.12 → nbdev-3.3.13}/pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
 ]
 dynamic = ["version"]
-dependencies = [ "fastcore>=2.2.7", "execnb>=0.3.2", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
+dependencies = [ "fastcore>=2.2.7", "execnb>=0.3.3", "astunparse", "ghapi>=2.0.2", "watchdog", "asttokens",
     "setuptools", "build", "fastgit>=0.0.7", "pyyaml", "tomli; python_version < '3.11'", ]
 
 [project.optional-dependencies]