fastcore 2.1.3__tar.gz → 2.1.4__tar.gz

{fastcore-2.1.3/fastcore.egg-info → fastcore-2.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastcore
-Version: 2.1.3
+Version: 2.1.4
 Summary: Python supercharged for fastai development
 Author-email: Jeremy Howard and Sylvain Gugger <infos@fast.ai>
 License: Apache-2.0

fastcore-2.1.4/fastcore/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.1.4"

{fastcore-2.1.3 → fastcore-2.1.4}/fastcore/_modidx.py

@@ -354,6 +354,7 @@ d = { 'settings': { 'branch': 'main',
                                    'fastcore.docments.sig2str': ('docments.html#sig2str', 'fastcore/docments.py'),
                                    'fastcore.docments.sig_source': ('docments.html#sig_source', 'fastcore/docments.py')},
             'fastcore.docscrape': {},
+            'fastcore.editskill': {},
             'fastcore.foundation': { 'fastcore.foundation.CollBase': ('foundation.html#collbase', 'fastcore/foundation.py'),
                                      'fastcore.foundation.CollBase.__delitem__': ( 'foundation.html#collbase.__delitem__',
                                                                                    'fastcore/foundation.py'),
@@ -479,7 +480,12 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.meta.use_kwargs': ('meta.html#use_kwargs', 'fastcore/meta.py'),
                                'fastcore.meta.use_kwargs_dict': ('meta.html#use_kwargs_dict', 'fastcore/meta.py')},
             'fastcore.nb_imports': {},
-            'fastcore.nbio': { 'fastcore.nbio.NbCell': ('nbio.html#nbcell', 'fastcore/nbio.py'),
+            'fastcore.nbio': { 'fastcore.nbio.CellRow': ('nbio.html#cellrow', 'fastcore/nbio.py'),
+                               'fastcore.nbio.CellRow.__init__': ('nbio.html#cellrow.__init__', 'fastcore/nbio.py'),
+                               'fastcore.nbio.CellRow.__repr__': ('nbio.html#cellrow.__repr__', 'fastcore/nbio.py'),
+                               'fastcore.nbio.CellRows': ('nbio.html#cellrows', 'fastcore/nbio.py'),
+                               'fastcore.nbio.CellRows.__repr__': ('nbio.html#cellrows.__repr__', 'fastcore/nbio.py'),
+                               'fastcore.nbio.NbCell': ('nbio.html#nbcell', 'fastcore/nbio.py'),
                                'fastcore.nbio.NbCell.__eq__': ('nbio.html#nbcell.__eq__', 'fastcore/nbio.py'),
                                'fastcore.nbio.NbCell.__hash__': ('nbio.html#nbcell.__hash__', 'fastcore/nbio.py'),
                                'fastcore.nbio.NbCell.__init__': ('nbio.html#nbcell.__init__', 'fastcore/nbio.py'),
@@ -504,14 +510,18 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.nbio.Notebook.add': ('nbio.html#notebook.add', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.cells': ('nbio.html#notebook.cells', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.concise': ('nbio.html#notebook.concise', 'fastcore/nbio.py'),
-                               'fastcore.nbio.Notebook.find': ('nbio.html#notebook.find', 'fastcore/nbio.py'),
+                               'fastcore.nbio.Notebook.find_cells': ('nbio.html#notebook.find_cells', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.md': ('nbio.html#notebook.md', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.meta': ('nbio.html#notebook.meta', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.move': ('nbio.html#notebook.move', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.open': ('nbio.html#notebook.open', 'fastcore/nbio.py'),
                                'fastcore.nbio.Notebook.save': ('nbio.html#notebook.save', 'fastcore/nbio.py'),
-                               'fastcore.nbio.Notebook.view': ('nbio.html#notebook.view', 'fastcore/nbio.py'),
+                               'fastcore.nbio.Notebook.summary': ('nbio.html#notebook.summary', 'fastcore/nbio.py'),
+                               'fastcore.nbio.Notebook.to_dict': ('nbio.html#notebook.to_dict', 'fastcore/nbio.py'),
+                               'fastcore.nbio.Notebook.view_cell': ('nbio.html#notebook.view_cell', 'fastcore/nbio.py'),
+                               'fastcore.nbio._cell_method': ('nbio.html#_cell_method', 'fastcore/nbio.py'),
                                'fastcore.nbio._dict2obj': ('nbio.html#_dict2obj', 'fastcore/nbio.py'),
+                               'fastcore.nbio._dir_attrs': ('nbio.html#_dir_attrs', 'fastcore/nbio.py'),
                                'fastcore.nbio._dir_line': ('nbio.html#_dir_line', 'fastcore/nbio.py'),
                                'fastcore.nbio._dir_pre': ('nbio.html#_dir_pre', 'fastcore/nbio.py'),
                                'fastcore.nbio._directive': ('nbio.html#_directive', 'fastcore/nbio.py'),
@@ -534,7 +544,9 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.nbio.cells2xml': ('nbio.html#cells2xml', 'fastcore/nbio.py'),
                                'fastcore.nbio.concat_streams': ('nbio.html#concat_streams', 'fastcore/nbio.py'),
                                'fastcore.nbio.dict2nb': ('nbio.html#dict2nb', 'fastcore/nbio.py'),
+                               'fastcore.nbio.find_cells': ('nbio.html#find_cells', 'fastcore/nbio.py'),
                                'fastcore.nbio.first_code_ln': ('nbio.html#first_code_ln', 'fastcore/nbio.py'),
+                               'fastcore.nbio.item2xml': ('nbio.html#item2xml', 'fastcore/nbio.py'),
                                'fastcore.nbio.mk_cell': ('nbio.html#mk_cell', 'fastcore/nbio.py'),
                                'fastcore.nbio.mk_display': ('nbio.html#mk_display', 'fastcore/nbio.py'),
                                'fastcore.nbio.mk_error': ('nbio.html#mk_error', 'fastcore/nbio.py'),
@@ -552,6 +564,7 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.nbio.render_text': ('nbio.html#render_text', 'fastcore/nbio.py'),
                                'fastcore.nbio.repair_cell': ('nbio.html#repair_cell', 'fastcore/nbio.py'),
                                'fastcore.nbio.repair_nb': ('nbio.html#repair_nb', 'fastcore/nbio.py'),
+                               'fastcore.nbio.summary_nb': ('nbio.html#summary_nb', 'fastcore/nbio.py'),
                                'fastcore.nbio.validate_cell': ('nbio.html#validate_cell', 'fastcore/nbio.py'),
                                'fastcore.nbio.validate_nb': ('nbio.html#validate_nb', 'fastcore/nbio.py'),
                                'fastcore.nbio.view_cell': ('nbio.html#view_cell', 'fastcore/nbio.py'),
@@ -735,7 +748,6 @@ d = { 'settings': { 'branch': 'main',
                               'fastcore.xml.dict2xml': ('xml.html#dict2xml', 'fastcore/xml.py'),
                               'fastcore.xml.ft': ('xml.html#ft', 'fastcore/xml.py'),
                               'fastcore.xml.highlight': ('xml.html#highlight', 'fastcore/xml.py'),
-                              'fastcore.xml.item2xml': ('xml.html#item2xml', 'fastcore/xml.py'),
                               'fastcore.xml.mk_getattr': ('xml.html#mk_getattr', 'fastcore/xml.py'),
                               'fastcore.xml.showtags': ('xml.html#showtags', 'fastcore/xml.py'),
                               'fastcore.xml.to_xml': ('xml.html#to_xml', 'fastcore/xml.py'),

fastcore-2.1.4/fastcore/editskill.py

@@ -0,0 +1,63 @@
+"""Text, file, cell, and notebook editing from `fastcore.tools` and `fastcore.nbio`, plus the conventions the whole fastai editing toolkit follows. Read this before working with the editing tools in any package that shares them.
+
+`from fastcore.editskill import *` loads the fastcore editing layer: the text primitives and file tools of `fastcore.tools`, and the notebook I/O and cell editors of `fastcore.nbio`. Sibling packages extend the same toolkit, and where they are installed prefer them as noted: `exhash` for hash-verified editing, `rgapi` for search, `llmsurgery`/`dialoghelper` for dialogs.
+
+## Carriers
+
+Each editing function works on one carrier: text (a str in memory), a file (a path on disk), a cell (one cell's source in an .ipynb file, addressed by `path, cell_id`), or a notebook (the parsed .ipynb; `Notebook` and `NbCell` are its held-object forms). These are the representation layer: an .ipynb is a file of cells, whatever produced it. The dialog layer above adds the msg and dlg carriers: a Solveit dialog is an .ipynb whose cells are messages (notes, runnable code, prompt/reply pairs), and `llmsurgery.dlgskill` and `dialoghelper` provide the message tools, following the conventions here with their own nouns. The word picks the layer: cell tools answer representation questions ("why does Jupyter reject this file?"), msg tools answer content questions ("what does this message say?").
+
+## Naming
+
+Two name shapes cover the toolkit, and the pivot is the verb's direct object:
+
+- An operation on a whole carrier takes the carrier as its noun: verb_carrier. `view_file`, `create_file`, `read_nb`, `write_nb`, `view_cell`, `validate_nb`; in the dialog layer `view_msg` and `view_dlg`. Coined verbs follow the same shape: `lnhashview_cell` is "lnhashview this cell". When the verb's object is instead the medium's unit, and that unit names its carrier uniquely, no prefix is needed - the unit noun is the carrier signal: `find_msgs`, `add_msg`, `del_msgs` (msgs live only in dialogs), `find_cells`, `summary_nb`'s rows (cells live only in notebooks).
+- An operation within a carrier already owns its noun (`insert_line`, `del_lines`, `replace_lines`, `str_replace`), so the carrier prefixes as a namespace and the op name survives intact: carrier_op, as in `file_del_lines`, `cell_del_lines`, `msg_del_lines`. The bare op names are the text-level primitives, and every carrier version keeps the identical signature after its address arguments, so each family is learned once and recognized everywhere.
+
+The exceptions are deliberate and closed. `str_replace` keeps the name and argument order established by Anthropic's text editor tool. Instrument-named ops put the instrument first and elide their unit: `ast_replace` (the AST pattern is how the edit finds its target) and `exhash` (hash-verified line addresses travel inside its commands), carrier-prefixed like any other line-level op: `file_ast_replace`, `msg_ast_replace`, `file_exhash`, `cell_exhash`. Converters are named x2y (`nb2dict`, `cell2xml`; in llmsurgery, `dlg` on exactly one side of every converter), and on a held object the converter is a `to_y` method (`nb.to_dict()`). Plural marks arity: `view_cell` takes one cell, `lnhashview_cells` several, `del_msgs` many.
+
+## Parameters
+
+One vocabulary, identical wherever it appears:
+
+- The carrier's address comes first (`text`; `path`; `path, cell_id`; a message `id`), the payload next, and ambient context last as keyword-only (message tools name their dialog that way).
+- `start_line`/`end_line`: 1-based, inclusive, `None` for first/last, negative counting from the end. Destructive ops (`del_lines`) accept no defaults: state the range.
+- `re_filter`/`invert_filter`: restrict an edit to lines matching (or not matching) a regex, like ex's `g//` and `g!//`; combines with the range.
+- Searches read patterns as regex by default; editors read them as literal text until `use_regex=True`. Searching is read-only, so its default favors power; editing favors safety.
+- `nums` and `lnhashs` on any view: line numbers, or `lineno|hash|` addresses. `maxlen` caps characters per summary line; `trunc_out`/`trunc_in` truncate outputs and sources in dialog views.
+- Search tools share one filter vocabulary: `pattern` first, `root='.'`, and the same include/exclude/ext/hidden/ignore block across `fd`, `ls`, `rg`, and `nbrg`. Variants differ by defaults, not API: `ls` is `fd` with listing defaults. Boolean filters narrow as `only_*` and widen as `include_*`.
+- `context=` counts the medium's own units: lines (or blocks in summary mode) for files, cells for notebooks, messages for dialogs. Dialog search defaults to context 1 because the neighbouring note usually explains the match: the why lives next to the what.
+- Every editor returns a diff ("none: No changes." when nothing changed). The diff is the verification: read it instead of re-viewing the target.
+
+## Functions and methods
+
+Every operation has two shapes with one contract each. The function is a transaction: it addresses a file by path, applies the edit, writes, and returns a diff. The method is a session: it mutates the object in hand, and nothing reaches disk until an explicit save. The correspondence is mechanical - the method is the function minus its address arguments, keeping its name except that a carrier token which became `self` drops: `cell_str_replace(path, cell_id, ...)` is `c.str_replace(...)` on a held `NbCell`, `find_cells(path, pat)` is `nb.find_cells(pat)` on a held `Notebook`. Function-side reads return dead snapshot rows carrying addresses, source, and meta; session-side reads return the live objects. Use one shape at a time per file: save before switching to functions, reopen after.
+
+## Addresses
+
+Edits say where with line numbers or lnhash addresses. Take addresses from the read you were already doing instead of with a second look: views accept `nums=True` or `lnhashs=True`, and searches return addresses directly (`rg(lnhashs=True)`). Prefer lnhash addresses whenever `exhash` is installed: they are verified against current content at edit time, so a stale address fails loudly instead of editing nearby text, which is exactly what makes taking addresses early safe. Plain line numbers are unverified and shift as edits apply, so re-view after each edit and apply multi-edits bottom-to-top. `exhash.skill` owns the address format and the verified editor.
+
+When you don't yet know where to edit, locate with a summary first: `rgapi`'s `rg(summary=True)` and `nbrg`, and llmsurgery's `summary_dlg`, each show one line per natural unit of their medium (block, cell, message), carrying the unit's address. Summaries locate, views read, addresses edit, diffs confirm.
+
+## What's where
+
+- `fastcore.tools`: text primitives, file tools, and `line_hash`/`lnhash`/`lnhash_at` for creating addresses without exhash installed.
+- `fastcore.nbio`: notebook read/write/validate/repair, cell construction, cell editors, and the `Notebook`/`NbCell` session objects with their snapshot queries (`find_cells`, `summary_nb`).
+- `exhash.skill`: hash-verified editing for files and cells; prefer it for edits where installed.
+- `rgapi.skill`: `rg`/`fd`/`ls`/`nbrg` search with lnhash output.
+- `remold`: structural search and rewrite for Python source (declarative ast-grep rules, LibCST matcher transforms, symbol queries); the engine behind `ast_replace`.
+- `llmsurgery.dlgskill`, `dialoghelper`: the dialog layer, including its own theory of dialogs and projections.
+
+Docs: https://fastcore.fast.ai/tools.html.md and https://fastcore.fast.ai/nbio.html.md
+"""
+
+from fastcore.tools import (insert_line, str_replace, strs_replace, replace_lines, del_lines, ast_replace,
+    file_insert_line, file_str_replace, file_strs_replace, file_replace_lines, file_del_lines, file_ast_replace,
+    view_file, create_file, line_hash, lnhash, lnhash_at)
+from fastcore.nbio import (read_nb, write_nb, new_nb, mk_cell, validate_nb, validate_cell, repair_nb, repair_cell,
+    view_cell, cell_insert_line, cell_str_replace, cell_strs_replace, cell_replace_lines, cell_del_lines, cell_ast_replace, Notebook, NbCell, find_cells, summary_nb)
+
+__all__ = ['insert_line', 'str_replace', 'strs_replace', 'replace_lines', 'del_lines', 'ast_replace',
+    'file_insert_line', 'file_str_replace', 'file_strs_replace', 'file_replace_lines', 'file_del_lines', 'file_ast_replace',
+    'view_file', 'create_file', 'line_hash', 'lnhash', 'lnhash_at',
+    'read_nb', 'write_nb', 'new_nb', 'mk_cell', 'validate_nb', 'validate_cell', 'repair_nb', 'repair_cell',
+    'view_cell', 'cell_insert_line', 'cell_str_replace', 'cell_strs_replace', 'cell_replace_lines', 'cell_del_lines', 'cell_ast_replace', 'Notebook', 'NbCell', 'find_cells', 'summary_nb']

{fastcore-2.1.3 → fastcore-2.1.4}/fastcore/nbio.py

@@ -1,6 +1,8 @@
 """Reading and writing Jupyter notebooks
 
-Cell tools apply `fastcore.tools`' string editing primitives to one notebook cell's source, addressed by path and cell id, mirroring that module's file tools: the same operations and parameters, with `path, cell_id` in place of `path`. Each editor returns a diff of the change, and `view_cell` shows a cell's source with optional line numbers or exhash addresses.
+Cell tools apply `fastcore.tools`' string editing primitives to one notebook cell's source, addressed by path and cell id, mirroring that module's file tools: the same operations and parameters, with `path, cell_id` in place of `path`. Each editor (including the structural `cell_ast_replace`) returns a diff of the change, and `view_cell` shows a cell's source with optional line numbers or exhash addresses.
+
+Naming and parameter conventions shared across the editing toolkit are documented in `fastcore.editskill`, which also re-exports this module's editing tools.
 
 Docs: https://fastcore.fast.ai/nbio.html.md"""
 
@@ -8,10 +10,11 @@ Docs: https://fastcore.fast.ai/nbio.html.md"""
 
 # %% auto #0
 __all__ = ['langs', 'cell_insert_line', 'cell_str_replace', 'cell_strs_replace', 'cell_replace_lines', 'cell_del_lines',
-           'nb_lang', 'NbCell', 'dict2nb', 'read_nb', 'mk_cell', 'new_nb', 'first_code_ln', 'nb2dict', 'nb2str',
-           'write_nb', 'cell_edit', 'view_cell', 'validate_cell', 'validate_nb', 'repair_cell', 'repair_nb',
-           'preferred_out', 'mk_stream', 'mk_result', 'mk_display', 'mk_error', 'concat_streams', 'preferred_msg_out',
-           'render_output', 'render_outputs', 'render_text', 'cell2xml', 'cells2xml', 'Notebook']
+           'cell_ast_replace', 'nb_lang', 'NbCell', 'dict2nb', 'read_nb', 'mk_cell', 'new_nb', 'first_code_ln',
+           'nb2dict', 'nb2str', 'write_nb', 'cell_edit', 'view_cell', 'validate_cell', 'validate_nb', 'repair_cell',
+           'repair_nb', 'preferred_out', 'mk_stream', 'mk_result', 'mk_display', 'mk_error', 'concat_streams',
+           'preferred_msg_out', 'render_output', 'render_outputs', 'render_text', 'item2xml', 'cell2xml', 'cells2xml',
+           'Notebook', 'CellRow', 'CellRows', 'summary_nb', 'find_cells']
 
 # %% ../nbs/13_nbio.ipynb #954ca1aa
 from .basics import *
@@ -19,9 +22,9 @@ from .xtras import rtoken_hex,clean_cli_output,take_lines,str_diff
 from .imports import *
 from .ansi import ansi2html
 from .meta import delegates,splice_sig
-from .tools import insert_line,str_replace,strs_replace,replace_lines,del_lines,lnhash
+from .tools import insert_line,str_replace,strs_replace,replace_lines,del_lines,ast_replace,lnhash
 
-import ast,functools
+import ast,copy,functools
 from collections import defaultdict
 from pprint import pformat,pprint
 from json import loads,dumps
@@ -154,13 +157,17 @@ def _directive(s, lang='python'):
     return name, ('' if v=='true' else v)
 
 # %% ../nbs/13_nbio.ipynb #16c08410
-def _meta_directives(cell):
-    "Directives from the `nbdev` dict in cell metadata, as `{name: value}`; values must be str (`'true'` for a bare directive)"
-    d = cell.get('metadata',{}).get('nbdev',{})
+def _meta_directives(meta):
+    "Directives from the `nbdev` dict in metadata dict `meta`, as `{name: value}`; values must be str (`'true'` for a bare directive)"
+    d = (meta or {}).get('nbdev',{})
     if bad := [k for k,v in d.items() if not isinstance(v,str)]:
         raise TypeError(f"`nbdev` metadata directive values must be str (e.g 'true'/'false'), got non-str for: {bad}")
     return {k:'' if v=='true' else v for k,v in d.items()}
 
+def _dir_attrs(meta):
+    "Metadata directives as XML attrs: bare directives become True, so they render as bare attributes"
+    return {k:v or True for k,v in _meta_directives(meta).items()}
+
 def _unparse_dir(v):
     "Inverse of `_meta_directives` value parsing: value string back to a metadata value"
     return 'true' if v=='' else v
@@ -182,7 +189,7 @@ def _directives_get(self):
     if '_directives_' not in self:
         dirs,_ = self._partition()
         cmts = dict(t for t in (_directive(s, self.lang_) for s in dirs) if t)
-        meta = _meta_directives(self)
+        meta = _meta_directives(self.get('metadata'))
         self['_meta_names_'] = set(meta) - set(cmts)
         self['_directives_'] = cmts | {k:v for k,v in meta.items() if k not in cmts}
     return dict(self['_directives_'])
@@ -244,7 +251,9 @@ def nb2dict(d, k=None):
 # %% ../nbs/13_nbio.ipynb #21ffe533
 def nb2str(nb):
     "Convert `nb` to a `str`"
-    if isinstance(nb, (AttrDict,list)): nb = nb2dict(nb)
+    # Unconditional: a plain dict can hold live NbCells (e.g. spliced in by a processor), whose working
+    # attrs (`idx_` etc) and str `source` must not serialize. Idempotent on already-canonical dicts.
+    nb = nb2dict(nb)
     return dumps(nb, sort_keys=True, indent=1, ensure_ascii=False) + "\n"
 
 # %% ../nbs/13_nbio.ipynb #d979e25a
@@ -272,6 +281,7 @@ def _nb_cell(nb, cell_id):
     return res[0]
 
 def cell_edit(f, name=None):
+    "Wrap text editor `f` as a cell editing function: `path, cell_id` addressing, diff-or-error return"
     def wrapper(path:str, cell_id:str, *args, **kw):
         nb = read_nb(path)
         cell = _nb_cell(nb, cell_id)
@@ -292,6 +302,7 @@ cell_str_replace = cell_edit(str_replace, 'cell_str_replace')
 cell_strs_replace = cell_edit(strs_replace, 'cell_strs_replace')
 cell_replace_lines = cell_edit(replace_lines, 'cell_replace_lines')
 cell_del_lines = cell_edit(del_lines, 'cell_del_lines')
+cell_ast_replace = cell_edit(ast_replace, 'cell_ast_replace')
 
 # %% ../nbs/13_nbio.ipynb #421b2b9c
 def view_cell(
@@ -377,7 +388,7 @@ def repair_nb(nb):
     return res
 
 # %% ../nbs/13_nbio.ipynb #530b9cd1
-from .xml import NB,to_xml,ft,item2xml
+from .xml import NB,to_xml,ft
 
 # %% ../nbs/13_nbio.ipynb #9f22b923
 def preferred_out(data, html1st=True, include_imgs=False):
@@ -480,11 +491,25 @@ def render_text(outputs, html1st=False):
     if not items: return ''
     return items[0][0] if len(items)==1 else '\n'.join(o[1] for o in items)
 
+# %% ../nbs/13_nbio.ipynb #d32fc4bc
+def item2xml(
+    typ, # Tag name: the cell or message type, e.g. 'code', 'markdown', 'raw', 'prompt'
+    content='', # The item's source text
+    out='', # Rendered output text
+    id=None, # Optional id attribute
+    meta=None, # Cell/message metadata: directives in its `nbdev` dict render as attrs, bare ones as bare attrs
+    **attrs, # Extra attributes; falsy values are dropped, names stay verbatim (no hyphenation)
+):
+    "A notebook cell or dialog message as concise XML: content, then an `<out>` section when `out` is non-empty"
+    kw = {k:v for k,v in {'id':id, **_dir_attrs(meta), **attrs}.items() if v}
+    return ft(typ, content, ft('out', out), attrmap=str, **kw) if out else ft(typ, content, attrmap=str, **kw)
+
 # %% ../nbs/13_nbio.ipynb #ca73be1c
 def cell2xml(cell, ids=True, incl_out=True):
     "Convert NbCell to concise XML format"
     outputs = getattr(cell, 'outputs', None) if incl_out else None
-    return item2xml(cell.cell_type, cell.source, render_text(outputs) if outputs else '', id=cell.id if ids else None)
+    return item2xml(cell.cell_type, cell.source, render_text(outputs) if outputs else '', id=cell.id if ids else None,
+                    meta=cell.get('metadata'))
 
 def cells2xml(cells, wrap=NB, ids=True, incl_out=True, **kw):
     "Convert notebook cells to XML format"
@@ -523,6 +548,19 @@ class Notebook:
     @property
     def concise (self): return cells2xml(self.cells, path=self.path.name, incl_out=False)
 
+# %% ../nbs/13_nbio.ipynb #af50ea0b
+def _cell_method(f):
+    def method(self, *args, **kw):
+        old = self.source
+        self.set_source(f(old, *args, **kw))
+        return PrettyString(str_diff(old, self.source) or 'none: No changes.')
+    res = splice_sig(method, f, 'text')
+    res.__name__ = res.__qualname__ = f.__name__
+    res.__doc__ = (f.__doc__ or '') + "\nIn-memory edit of this cell's `source`, returning a diff; nothing is written to disk."
+    return res
+
+for _f in (insert_line, str_replace, strs_replace, replace_lines, del_lines, ast_replace): setattr(NbCell, _f.__name__, _cell_method(_f))
+
 # %% ../nbs/13_nbio.ipynb #161b6662
 @patch
 def add(self:Notebook, source, cell_type='code', idx=None, after=None, before=None, **kwargs):
@@ -545,7 +583,7 @@ def md(self:Notebook, source, idx=None, after=None, before=None, **kwargs):
 
 # %% ../nbs/13_nbio.ipynb #5a09a2fa
 @patch
-def find(self:Notebook, pat, cell_type=None):
+def find_cells(self:Notebook, pat, cell_type=None):
     "Find cells with source matching regex `pat`"
     return [c for c in self.cells if re.search(pat, c.source) and (not cell_type or c.cell_type==cell_type)]
 
@@ -563,8 +601,50 @@ def move(self:Notebook, src_ids, after=None, before=None):
 
 # %% ../nbs/13_nbio.ipynb #e064c39e
 @patch
-def view(self:Notebook, id, nums=True):
+def view_cell(self:Notebook, id, nums=True):
     "Show cell source with optional line numbers"
     lines = self[id].source.splitlines()
     if nums: lines = [f'{i+1:6d} │ {l}' for i,l in enumerate(lines)]
     return '\n'.join(lines)
+
+# %% ../nbs/13_nbio.ipynb #804670bc
+class CellRow:
+    "Snapshot of one cell, shown as `id:t[directives]:source` (t: c=code m=markdown r=raw)"
+    def __init__(self, c, maxlen=120):
+        self.id,self.cell_type,self.source,self.maxlen = c.id,c.cell_type,c.source,maxlen
+        self.meta = copy.deepcopy(dict(c.get('metadata',{})))
+    def __repr__(self):
+        d = self.meta.get('nbdev',{})
+        tag = ' '.join(k if v in ('','true') else f'{k}={v}' for k,v in d.items())
+        src = self.source.replace('\n', '\\n')
+        if len(src)>self.maxlen: src = src[:self.maxlen]+'…'
+        return f"{self.id}:{self.cell_type[0]}{'['+tag+']' if tag else ''}:{src}"
+
+class CellRows(list):
+    def __repr__(self): return '\n'.join(repr(o) for o in self)
+
+# %% ../nbs/13_nbio.ipynb #62d7f8d1
+@patch
+def summary(self:Notebook, maxlen=120):
+    "One `CellRow` line per cell"
+    return CellRows(CellRow(c, maxlen) for c in self.cells)
+
+def summary_nb(
+    path, # Notebook file to read
+    maxlen:int=120, # Maximum source characters per line
+):
+    "One snapshot line per cell of the notebook at `path`"
+    return Notebook.open(path).summary(maxlen)
+
+def find_cells(
+    path, # Notebook file to search
+    pat:str='', # Regex over cell source
+    cell_type:str=None, # Optional limit by type ('code', 'markdown', or 'raw')
+):
+    "Snapshot `CellRows` for matching cells in the notebook at `path`"
+    return CellRows(CellRow(c) for c in Notebook.open(path).find_cells(pat, cell_type))
+
+@patch
+def to_dict(self:Notebook):
+    "The plain dict form of the held notebook (`nb2dict`): the representation layer"
+    return nb2dict(self.nb)

{fastcore-2.1.3 → fastcore-2.1.4}/fastcore/tools.py

@@ -1,10 +1,10 @@
 """Text and file editing primitives shared by the fastai editing tools
 
-The editors here are string-level: each takes `text` plus edit parameters and returns the new text, raising `ValueError` when an edit can't apply. The file tools below wrap them with path I/O and diff reporting; message-level wrappers live in llmsurgery. (This module previously held experimental LLM path-editing and command tools, superseded by safecmd, rgapi, and the tools here.)
+The editors here are string-level: each takes `text` plus edit parameters and returns the new text, raising `ValueError` when an edit can't apply. The file tools below wrap them with path I/O and diff reporting; message-level wrappers live in llmsurgery. (This module previously held experimental LLM path-editing and command tools, superseded by safecmd, rgapi, and the tools here.) Naming, parameter, and workflow conventions for the whole editing toolkit, this module included, are documented in `fastcore.editskill`, which also re-exports these tools alongside `fastcore.nbio`'s.
 
 `line_hash`, `lnhash`, and `lnhash_at` implement the [exhash](https://answerdotai.github.io/exhash) line-address format in pure Python: `lineno|hash|`, where the hash is 4 hex chars of crc32. They let any tool create lnhash-addressed views of text it holds, without depending on the exhash package.
 
-File tools wrap the primitives with path I/O, returning unified diffs of what changed ("none: No changes." / "error: ..." otherwise). The path is the first argument (with `view_file`/`create_file` named verb-first, since the file is the verb's object rather than the location of an edit), e.g:
+File tools wrap the primitives with path I/O, returning unified diffs of what changed ("none: No changes." / "error: ..." otherwise). The path is the first argument, e.g:
 
     view_file('~/a/b.py', 3)
     create_file('~/a/b/c.py', 'content here')
@@ -12,7 +12,7 @@ File tools wrap the primitives with path I/O, returning unified diffs of what ch
     file_del_lines('myfile.py', 2, 4)
     file_replace_lines('myfile.py', new_content=src)   # no line numbers: replace the entire contents
 
-`file_str_replace`, `file_strs_replace`, and `file_del_lines` support `re_filter` and `invert_filter` for targeting only lines matching (or not matching) a regex, like ex's `g//` and `g!//`, combined with `start_line`/`end_line` to restrict to a region. `ast_replace(text, repls)` and `file_ast_replace(path, repls)` apply ast-grep `(pattern, replacement)` rules with `$VAR` metavariables (requires the optional `remold` package). Where the `exhash` package is available, prefer it for editing: its hash-verified addressing fails loudly on stale context instead of editing nearby text.
+`file_str_replace`, `file_strs_replace`, and `file_del_lines` support `re_filter` and `invert_filter` for targeting only lines matching (or not matching) a regex, like ex's `g//` and `g!//`, combined with `start_line`/`end_line` to restrict to a region. `ast_replace(text, repls)` and `file_ast_replace(path, repls)` apply ast-grep `(pattern, replacement)` rules with `$VAR` metavariables (requires the optional `remold` package).
 
 Docs: https://fastcore.fast.ai/tools.html.md"""
 
@@ -204,6 +204,7 @@ returns: diff of changes, or "none: No changes.", or "error: ..."
 
 # %% ../nbs/12_tools.ipynb #a6f7361d
 def file_edit(f, name=None):
+    "Wrap text editor `f` as a file editing function: `path` addressing, diff-or-error return"
     def wrapper(path:str, *args, **kw):
         path = Path(path).expanduser()
         text = path.read_text()

{fastcore-2.1.3 → fastcore-2.1.4}/fastcore/xml.py

@@ -5,14 +5,14 @@ Docs: https://fastcore.fast.ai/xml.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/09_xml.ipynb.
 
 # %% auto #0
-__all__ = ['voids', 'attrmap', 'valmap', 'FT', 'ft', 'Html', 'Safe', 'to_xml', 'dict2xml', 'item2xml', 'highlight', 'showtags',
-           'mk_getattr', 'Head', 'Title', 'Meta', 'Link', 'Style', 'Body', 'Pre', 'Code', 'Div', 'Span', 'P', 'H1',
-           'H2', 'H3', 'H4', 'H5', 'H6', 'Strong', 'Em', 'B', 'I', 'U', 'S', 'Strike', 'Sub', 'Sup', 'Hr', 'Br', 'Img',
-           'A', 'Nav', 'Ul', 'Ol', 'Li', 'Dl', 'Dt', 'Dd', 'Table', 'Thead', 'Tbody', 'Tfoot', 'Tr', 'Th', 'Td',
-           'Caption', 'Col', 'Colgroup', 'Form', 'Input', 'Textarea', 'Button', 'Select', 'Option', 'Label', 'Fieldset',
-           'Legend', 'Details', 'Summary', 'Main', 'Header', 'Footer', 'Section', 'Article', 'Aside', 'Figure',
-           'Figcaption', 'Mark', 'Small', 'Iframe', 'Object', 'Embed', 'Param', 'Video', 'Audio', 'Source', 'Canvas',
-           'Svg', 'Math', 'Script', 'Noscript', 'Template', 'Slot']
+__all__ = ['voids', 'attrmap', 'valmap', 'FT', 'ft', 'Html', 'Safe', 'to_xml', 'dict2xml', 'highlight', 'showtags', 'mk_getattr',
+           'Head', 'Title', 'Meta', 'Link', 'Style', 'Body', 'Pre', 'Code', 'Div', 'Span', 'P', 'H1', 'H2', 'H3', 'H4',
+           'H5', 'H6', 'Strong', 'Em', 'B', 'I', 'U', 'S', 'Strike', 'Sub', 'Sup', 'Hr', 'Br', 'Img', 'A', 'Nav', 'Ul',
+           'Ol', 'Li', 'Dl', 'Dt', 'Dd', 'Table', 'Thead', 'Tbody', 'Tfoot', 'Tr', 'Th', 'Td', 'Caption', 'Col',
+           'Colgroup', 'Form', 'Input', 'Textarea', 'Button', 'Select', 'Option', 'Label', 'Fieldset', 'Legend',
+           'Details', 'Summary', 'Main', 'Header', 'Footer', 'Section', 'Article', 'Aside', 'Figure', 'Figcaption',
+           'Mark', 'Small', 'Iframe', 'Object', 'Embed', 'Param', 'Video', 'Audio', 'Source', 'Canvas', 'Svg', 'Math',
+           'Script', 'Noscript', 'Template', 'Slot']
 
 # %% ../nbs/09_xml.ipynb #f6c9a7f5
 from .utils import *
@@ -241,18 +241,6 @@ def dict2xml(d, do_escape=False, unwrap=None):
         if first(d) in listify(unwrap): return first(d.values())
     return to_xml(*[ft(k, str(v)) for k,v in d.items()], do_escape=do_escape)
 
-# %% ../nbs/09_xml.ipynb #7b26e0f9
-def item2xml(
-    typ, # Tag name: the cell or message type, e.g. 'code', 'markdown', 'raw', 'prompt'
-    content='', # The item's source text
-    out='', # Rendered output text
-    id=None, # Optional id attribute
-    **attrs, # Extra attributes; falsy values are dropped
-):
-    "A notebook cell or dialog message as concise XML: content, then an `<out>` section when `out` is non-empty"
-    kw = {k:v for k,v in dict(id=id, **attrs).items() if v}
-    return ft(typ, content, ft('out', out), **kw) if out else ft(typ, content, **kw)
-
 # %% ../nbs/09_xml.ipynb #5f0e91e0
 def highlight(s, lang='html'):
     "Markdown to syntax-highlight `s` in language `lang`"

{fastcore-2.1.3 → fastcore-2.1.4/fastcore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastcore
-Version: 2.1.3
+Version: 2.1.4
 Summary: Python supercharged for fastai development
 Author-email: Jeremy Howard and Sylvain Gugger <infos@fast.ai>
 License: Apache-2.0

{fastcore-2.1.3 → fastcore-2.1.4}/fastcore.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ fastcore/basics.py
 fastcore/dispatch.py
 fastcore/docments.py
 fastcore/docscrape.py
+fastcore/editskill.py
 fastcore/foundation.py
 fastcore/imghdr.py
 fastcore/imports.py

{fastcore-2.1.3 → fastcore-2.1.4}/fastcore.egg-info/entry_points.txt

@@ -6,4 +6,4 @@ replace_wildcards = fastcore.py2pyi:replace_wildcards
 fastcore = fastcore._modidx:d
 
 [pyskills]
-fastcore.tools = fastcore.tools
+fastcore.editskill = fastcore.editskill

{fastcore-2.1.3 → fastcore-2.1.4}/pyproject.toml

@@ -22,7 +22,7 @@ Documentation = "https://fastcore.fast.ai/"
 fastcore = "fastcore._modidx:d"
 
 [project.entry-points.pyskills]
-"fastcore.tools" = "fastcore.tools"
+"fastcore.editskill" = "fastcore.editskill"
 
 [project.optional-dependencies]
 dev = ['numpy', 'nbdev>=0.2.39', 'matplotlib', 'pillow', 'torch', 'pandas', 'nbclassic', 'pysym2md>=0.0.6', 'llms-txt', 'plum-dispatch', 'toolslm']

fastcore-2.1.3/fastcore/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.1.3"