nbdev 3.3.2__tar.gz → 3.3.4__tar.gz

{nbdev-3.3.2/nbdev.egg-info → nbdev-3.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.2
+Version: 3.3.4
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License: Apache-2.0

{nbdev-3.3.2 → nbdev-3.3.4}/nbdev/__init__.py

@@ -5,7 +5,7 @@ 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.skill`: Author clear, executable nbdev notebooks where code, prose, examples, outputs, and tests form one coherent narrative."""
 
-__version__ = "3.3.2"
+__version__ = "3.3.4"
 
 from .doclinks import nbdev_export
 from .showdoc import show_doc

{nbdev-3.3.2 → nbdev-3.3.4}/nbdev/config.py

@@ -11,7 +11,6 @@ __all__ = ['pyproject_nm', 'pyproject_tmpl', 'nbdev_defaults', 'pyproj_tmpl', 'n
            'update_llms_txt', 'import_obj', 'write_cells']
 
 # %% ../nbs/api/01_config.ipynb #6fd14ecd
-from datetime import datetime
 from fastcore.docments import *
 from fastcore.utils import *
 from fastcore.meta import *
@@ -19,10 +18,9 @@ from fastcore.script import *
 from fastcore.style import *
 from fastcore.xdg import *
 
-import ast,importlib,re,warnings
+import ast,importlib,re
 from IPython.display import Markdown
 from fastcore.nbio import read_nb,NbCell
-from urllib.error import HTTPError
 
 try: import tomllib
 except ImportError: import tomli as tomllib
@@ -42,6 +40,7 @@ def _get_info(owner, repo, default_branch='main', default_kw='nbdev'):
     from ghapi.all import call_gh, APIError
     try: r = call_gh('repos.get', owner=owner, repo=repo)
     except APIError:
+        # chkstyle: ignore-node
         msg= [f"""Could not access repo: {owner}/{repo} to find your default branch - `{default_branch}` assumed.
 Edit `pyproject.toml` if this is incorrect.
 In the future, you can allow nbdev to see private repos by setting the environment variable GITHUB_TOKEN as described here:
@@ -205,8 +204,7 @@ class ConfigToml(AttrDict):
         if 'lib_path' not in self: self['lib_path'] = self.lib_name.replace('-', '_')
 
     @property
-    def version(self):
-        return read_version(self.config_path / self['lib_path']) or '0.0.1'
+    def version(self): return read_version(self.config_path / self['lib_path']) or '0.0.1'
 
     @property
     def d(self): return {k:v for k,v in super().items()}
@@ -253,7 +251,7 @@ def is_nbdev(path=None): return _find_nbdev_pyproject(path) is not None
 def create_output(txt, mime):
     "Add a cell output containing `txt` of the `mime` text MIME sub-type"
     return [dict(data={f"text/{mime}": str(txt).splitlines(True)},
-                 execution_count=1, metadata={}, output_type="execute_result")]
+        execution_count=1, metadata={}, output_type="execute_result")]
 
 # %% ../nbs/api/01_config.ipynb #5a4d8e52
 def show_src(src, lang='python'): return Markdown(f'```{lang}\n{src}\n```')
@@ -318,12 +316,13 @@ def set_version(path, version):
 
 # %% ../nbs/api/01_config.ipynb #d00889e5
 def bump_version(v, part=2, unbump=False):
-    "Bump semver string `v` at index `part` (0=major, 1=minor, 2=patch)"
+    "Bump semver part `part` (0=major, 1=minor, 2=patch), counted from the right"
     parts = (v or '0.0.0').split('.')
     parts += ['0'] * (3 - len(parts))
-    parts[part] = str(int(parts[part]) + (-1 if unbump else 1))
-    for i in range(part+1, 3): parts[i] = '0'
-    return '.'.join(parts[:3])
+    idx = len(parts) - 3 + part
+    parts[idx] = str(int(parts[idx]) + (-1 if unbump else 1))
+    for i in range(idx+1, len(parts)): parts[i] = '0'
+    return '.'.join(parts)
 
 # %% ../nbs/api/01_config.ipynb #e32583e6
 def update_version(path=None):

{nbdev-3.3.2 → nbdev-3.3.4}/nbdev/quarto.py

@@ -208,8 +208,10 @@ def _chk_nbdev_yml(path):
 
 # %% ../nbs/api/14_quarto.ipynb #6b880922
 def _pre_docs(path=None, n_workers:int=defaults.cpus, **kwargs):
-    cfg = get_config()
-    path = Path(path) if path else cfg.nbs_path
+    cfg = get_config(path)
+    path = Path(path).absolute() if path else cfg.nbs_path
+    if not (path/'nbdev.yml').exists(): path = cfg.nbs_path  # given a project root, fall back to its configured nbs
+    os.chdir(cfg.config_path)  # bare `get_config()` runs downstream (including in render workers), so anchor the cwd
     _chk_nbdev_yml(path)
     _ensure_quarto()
     refresh_quarto_yml()
@@ -272,12 +274,14 @@ def _save_cached_readme(cache, cfg):
 # %% ../nbs/api/14_quarto.ipynb #45d6bb5d
 @call_parse
 def nbdev_readme(
-    path:str=None, # Path to notebooks
+    path:str=None, # Path to notebooks (or project root)
     chk_time:bool=False): # Only build if out of date
     "Create README.md from readme_nb (index.ipynb by default). Skips if the file doesn't exist."
-    cfg = get_config()
-    path = Path(path) if path else cfg.nbs_path
+    cfg = get_config(path)
+    path = Path(path).absolute() if path else cfg.nbs_path
+    if not (path/cfg.readme_nb).exists(): path = cfg.nbs_path  # given a project root, fall back to its configured nbs
     if not (path/cfg.readme_nb).exists(): return
+    os.chdir(cfg.config_path)  # bare `get_config()` runs downstream (including in render workers), so anchor the cwd
     _chk_nbdev_yml(path)
     if chk_time and _doc_mtime_not_older(cfg.config_path/'README.md', path/cfg.readme_nb): return
 

{nbdev-3.3.2 → nbdev-3.3.4}/nbdev/serve.py

@@ -70,7 +70,7 @@ def proc_nbs(
     file_re:str='', # Only process notebooks matching regex (other files are always included)
     **kwargs):
     "Process notebooks in `path` for docs rendering"
-    cfg = get_config()
+    cfg = get_config(path or None)
     cache = cfg.config_path/'_proc'
     path = Path(path or cfg.nbs_path)
     files = nbglob(path, func=Path, file_glob='', file_re='', **kwargs)

{nbdev-3.3.2 → nbdev-3.3.4}/nbdev/skill.py

@@ -32,6 +32,14 @@ Markdown explains what the code cannot: why an abstraction exists, what distinct
 
 Keep docstrings to a short statement of what the symbol does. Extended explanation, examples, and warnings go in markdown cells, where they render properly and can include executable results. Document parameters and returns with docments, keeping their docs beside the signature instead of repeating it in the docstring. Backtick symbol names in prose. nbdev links them, so prefer names over hand-maintained URLs.
 
+# Module docstrings
+
+`doc(module)` shows the docstring with the API listing, and for an LLM that is usually the whole read. Treat the docstring as the module's TL;DR. Write a short summary under each major section heading and tag it `#| export`, teaching what a reader cannot guess from signatures and leaving per-function detail to the page.
+
+`#| exportd` on a code cell puts its source in the docstring as a fenced block and keeps it out of the module code. Use it for a compact runnable demo, placed after the definitions it needs. End the summary before it with a colon so the two read as one. Only exported cells join the docstring, so the pair stays adjacent there even when definition cells sit between them in the notebook.
+
+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
 
 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.
@@ -58,12 +66,14 @@ Keep imports in dedicated import cells, define values near first use, reuse esta
 
 # Directives
 
-`#| default_exp` names the module. `#| export` marks exported cells. Underscore-prefixed helpers may export without joining the public API. `#| hide` keeps necessary but distracting material off the page. `#| eval: false` is for cells that genuinely must not run, not for suppressing broken ones, and it cascades. An unevaluated cell cannot create state for later evaluated cells.
+`#| default_exp` names the module. `#| export` marks exported cells. Underscore-prefixed helpers may export without joining the public API. `#| exportd` exports a code cell's source to the module docstring instead of the module. `#| hide` keeps necessary but distracting material off the page. `#| eval: false` is for cells that genuinely must not run, not for suppressing broken ones, and it cascades. An unevaluated cell cannot create state for later evaluated cells.
 
 # nbdev v3
 
 Everything here describes nbdev v3 (released Jan 2026, possibly after a model's training cutoff). Key user-visible changes from v2: config moved from `settings.ini` to `pyproject.toml`, with standard metadata in `[project]`, nbdev-specific keys in `[tool.nbdev]` (defaults `nbs_path='nbs'`, `doc_path='_docs'`), version in `__init__.py` via `dynamic = ["version"]`, and `_modidx` registered under `[project.entry-points.nbdev]`. CLI commands use hyphens (`nbdev-export`, `nbdev-test`, ...) though Python functions keep underscores. GitHub workflows use the v3 actions (`fastai/workflows/nbdev3-ci`, `quarto-ghp3`).
 
+Directives can also live in cell *metadata*, under the `nbdev` key (`{"nbdev": {"export": "true"}}`), instead of `#|` comment lines. Export and the rest of the toolchain honor both; `mk_cell(source, metadata=...).directives` is the merged read, with the comment winning when both set the same key. The editing toolkit keeps the meta form visible: summaries show it bracketed after the type char (`id:c[export]:...` in nbio's `CellRow` and aidialog's previews), XML views render it as attrs (a bare `export` on the tag), and aidialog's `Message` offers `exported` (either form, read-only) and `meta_exported` (meta only, assignable), with `export=`/`meta=` params on the add functions.
+
 # 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.

{nbdev-3.3.2 → nbdev-3.3.4}/nbdev/test.py

@@ -108,8 +108,8 @@ def nbdev_test(
     if len(files)==0: return print('No files were eligible for testing')
 
     if n_workers is None: n_workers = 0 if len(files)==1 else min(num_cpus(), 8)
-    if IN_NOTEBOOK: kw = {'method':'spawn'} if os.name=='nt' else {'method':'forkserver'}
-    else: kw = {'method':'forkserver'} if sys.platform=='darwin' else {}
+    if IN_NOTEBOOK: kw = {'method':'spawn'} if os.name=='nt' or sys.platform=='darwin' else {'method':'forkserver'}
+    else: kw = {'method':'spawn'} if sys.platform=='darwin' else {}
     wd_pth = cfg.nbs_path
     with working_directory(wd_pth if (wd_pth and wd_pth.exists()) else os.getcwd()):
         results = parallel(test_nb, files, skip_flags=skip_flags, force_flags=force_flags, n_workers=n_workers,

{nbdev-3.3.2 → nbdev-3.3.4/nbdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nbdev
-Version: 3.3.2
+Version: 3.3.4
 Summary: Create delightful software with Jupyter Notebooks
 Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
 License: Apache-2.0