fastcore 2.1.2__tar.gz → 2.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastcore
-Version: 2.1.2
+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.2 → 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'),
@@ -521,6 +531,7 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.nbio._join': ('nbio.html#_join', 'fastcore/nbio.py'),
                                'fastcore.nbio._meta_directives': ('nbio.html#_meta_directives', 'fastcore/nbio.py'),
                                'fastcore.nbio._mkout': ('nbio.html#_mkout', 'fastcore/nbio.py'),
+                               'fastcore.nbio._nb_cell': ('nbio.html#_nb_cell', 'fastcore/nbio.py'),
                                'fastcore.nbio._read_json': ('nbio.html#_read_json', 'fastcore/nbio.py'),
                                'fastcore.nbio._rejoin_cell': ('nbio.html#_rejoin_cell', 'fastcore/nbio.py'),
                                'fastcore.nbio._rejoin_mime': ('nbio.html#_rejoin_mime', 'fastcore/nbio.py'),
@@ -529,10 +540,13 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.nbio._split_mime': ('nbio.html#_split_mime', 'fastcore/nbio.py'),
                                'fastcore.nbio._unparse_dir': ('nbio.html#_unparse_dir', 'fastcore/nbio.py'),
                                'fastcore.nbio.cell2xml': ('nbio.html#cell2xml', 'fastcore/nbio.py'),
+                               'fastcore.nbio.cell_edit': ('nbio.html#cell_edit', 'fastcore/nbio.py'),
                                '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'),
@@ -550,8 +564,10 @@ 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'),
                                'fastcore.nbio.write_nb': ('nbio.html#write_nb', 'fastcore/nbio.py')},
             'fastcore.net': { 'fastcore.net.HTTP4xxClientError': ('net.html#http4xxclienterror', 'fastcore/net.py'),
                               'fastcore.net.HTTP5xxServerError': ('net.html#http5xxservererror', 'fastcore/net.py'),
@@ -677,14 +693,17 @@ d = { 'settings': { 'branch': 'main',
                                'fastcore.test.test_warns': ('test.html#test_warns', 'fastcore/test.py')},
             'fastcore.tools': { 'fastcore.tools._norm_lines': ('tools.html#_norm_lines', 'fastcore/tools.py'),
                                 'fastcore.tools.ast_replace': ('tools.html#ast_replace', 'fastcore/tools.py'),
+                                'fastcore.tools.create_file': ('tools.html#create_file', 'fastcore/tools.py'),
                                 'fastcore.tools.del_lines': ('tools.html#del_lines', 'fastcore/tools.py'),
-                                'fastcore.tools.file_create': ('tools.html#file_create', 'fastcore/tools.py'),
                                 'fastcore.tools.file_edit': ('tools.html#file_edit', 'fastcore/tools.py'),
-                                'fastcore.tools.file_view': ('tools.html#file_view', 'fastcore/tools.py'),
                                 'fastcore.tools.insert_line': ('tools.html#insert_line', 'fastcore/tools.py'),
+                                'fastcore.tools.line_hash': ('tools.html#line_hash', 'fastcore/tools.py'),
+                                'fastcore.tools.lnhash': ('tools.html#lnhash', 'fastcore/tools.py'),
+                                'fastcore.tools.lnhash_at': ('tools.html#lnhash_at', 'fastcore/tools.py'),
                                 'fastcore.tools.replace_lines': ('tools.html#replace_lines', 'fastcore/tools.py'),
                                 'fastcore.tools.str_replace': ('tools.html#str_replace', 'fastcore/tools.py'),
-                                'fastcore.tools.strs_replace': ('tools.html#strs_replace', 'fastcore/tools.py')},
+                                'fastcore.tools.strs_replace': ('tools.html#strs_replace', 'fastcore/tools.py'),
+                                'fastcore.tools.view_file': ('tools.html#view_file', 'fastcore/tools.py')},
             'fastcore.transform': {},
             'fastcore.utils': {},
             'fastcore.xdg': { 'fastcore.xdg._path_from_env': ('xdg.html#_path_from_env', 'fastcore/xdg.py'),
@@ -729,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.2 → fastcore-2.1.4}/fastcore/nbio.py

@@ -1,23 +1,30 @@
 """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 (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"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/13_nbio.ipynb.
 
 # %% auto #0
-__all__ = ['langs', 'nb_lang', 'NbCell', 'dict2nb', 'read_nb', 'mk_cell', 'new_nb', 'first_code_ln', 'nb2dict', 'nb2str',
-           'write_nb', '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']
+__all__ = ['langs', 'cell_insert_line', 'cell_str_replace', 'cell_strs_replace', 'cell_replace_lines', 'cell_del_lines',
+           '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 *
-from .xtras import rtoken_hex,clean_cli_output,take_lines
+from .xtras import rtoken_hex,clean_cli_output,take_lines,str_diff
 from .imports import *
 from .ansi import ansi2html
-from .meta import delegates
+from .meta import delegates,splice_sig
+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
@@ -150,19 +157,20 @@ 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}`"
-    def _v(v):
-        if isinstance(v,bool): return '' if v else 'false'
-        if isinstance(v,(list,tuple)): return ' '.join(map(str,v))
-        return '' if v=='true' else str(v)
-    return {k:_v(v) for k,v in cell.get('metadata',{}).get('nbdev',{}).items()}
+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"
-    if v=='': return True
-    if v=='false': return False
-    return v
+    return 'true' if v=='' else v
 
 def _dir_line(k, v, lang='python', quarto=False):
     "A canonical directive comment line; with `quarto`, bare directives render as `: true`"
@@ -181,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_'])
@@ -243,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
@@ -255,6 +265,63 @@ def write_nb(nb, path):
     if new!=old:
         with open(path, 'w', encoding='utf-8') as f: f.write(new)
 
+# %% ../nbs/13_nbio.ipynb #3453e541
+_cell_edit_doc = """
+This is a *cell* editing function.
+
+Cell editing standard parameters are `path`: notebook file to modify, and `cell_id`: id of the cell to edit (exact, or unique prefix)
+
+returns: diff of changes, or "none: No changes.", or "error: ..."
+"""
+
+def _nb_cell(nb, cell_id):
+    "Cell in `nb` with id `cell_id` (exact match, or unique prefix)"
+    res = [c for c in nb.cells if c.id==cell_id] or [c for c in nb.cells if c.id.startswith(cell_id)]
+    if len(res)!=1: raise KeyError(f"{'ambiguous' if res else 'no'} cell id: {cell_id!r}")
+    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)
+        text = cell.source
+        try: new_text = f(text, *args, **kw)
+        except ValueError as e: return PrettyString(f'error: {e}')
+        cell.source = new_text
+        write_nb(nb, path)
+        return PrettyString(str_diff(text, new_text) or 'none: No changes.')
+    res = splice_sig(wrapper, f, 'text')
+    if name: res.__name__ = res.__qualname__ = name
+    res.__doc__ = (f.__doc__ or '') + _cell_edit_doc
+    return res
+
+# %% ../nbs/13_nbio.ipynb #bde31026
+cell_insert_line = cell_edit(insert_line, 'cell_insert_line')
+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(
+    path:str, # Notebook file to read
+    cell_id:str, # Id of the cell to view (exact, or unique prefix)
+    start_line:int=1, # Starting line to view
+    end_line:int=None, # End line (defaults to last line if None; may be past EOF, which clamps to the last line)
+    nums:bool=True, # Show line numbers?
+    lnhashs:bool=False # Show exhash `lineno|hash|` addresses instead of line numbers?
+):
+    "View a cell's source, optionally limited to 1-based line range"
+    lines = _nb_cell(read_nb(path), cell_id).source.splitlines()
+    if not lines: return ''
+    if end_line is None or end_line > len(lines): end_line = len(lines)
+    if end_line < 0: end_line = len(lines)+end_line+1
+    if not (1 <= start_line <= len(lines)): return f'error: Invalid start_line {start_line}. Valid range: 1-{len(lines)}'
+    fmt = (lambda i,l: lnhash(i,l)+l) if lnhashs else (lambda i,l: f'{i}: {l}') if nums else (lambda i,l: l)
+    return PrettyString('\n'.join(fmt(i,l) for i,l in enumerate(lines[start_line-1:end_line], start_line)))
+
 # %% ../nbs/13_nbio.ipynb #86453c0f
 def validate_cell(cell, idx=None):
     "Raise `ValueError` for structural problems in notebook cell dict `cell`; returns it unchanged if fine"
@@ -321,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):
@@ -424,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"
@@ -467,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):
@@ -489,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)]
 
@@ -507,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.2 → fastcore-2.1.4}/fastcore/tools.py

@@ -1,27 +1,30 @@
 """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, e.g:
 
-    file_view('~/a/b.py', 3)
-    file_create('~/a/b/c.py', 'content here')
+    view_file('~/a/b.py', 3)
+    create_file('~/a/b/c.py', 'content here')
     file_str_replace('myfile.py', 'old_name', 'new_name')
     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 `ast_file(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"""
 
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/12_tools.ipynb.
 
 # %% auto #0
-__all__ = ['file_insert_line', 'file_str_replace', 'file_strs_replace', 'file_replace_lines', 'file_del_lines', 'ast_file',
-           'insert_line', 'str_replace', 'strs_replace', 'replace_lines', 'del_lines', 'file_view', 'file_create',
-           'file_edit', 'ast_replace']
+__all__ = ['file_insert_line', 'file_str_replace', 'file_strs_replace', 'file_replace_lines', 'file_del_lines',
+           'file_ast_replace', 'insert_line', 'str_replace', 'strs_replace', 'replace_lines', 'del_lines', 'line_hash',
+           'lnhash', 'lnhash_at', 'view_file', 'create_file', 'file_edit', 'ast_replace']
 
 # %% ../nbs/12_tools.ipynb #578246d2
+import zlib
 from .imports import *
 from .meta import splice_sig
 from .basics import PrettyString
@@ -138,11 +141,34 @@ def del_lines(
     else: del lines[s-1:e]
     return ''.join(lines)
 
+# %% ../nbs/12_tools.ipynb #6274581f
+def line_hash(
+    line:str # A single line of text, without trailing newline
+)->str:
+    "4-char hex exhash hash of `line`"
+    return f'{zlib.crc32(line.encode()) & 0xffff:04x}'
+
+def lnhash(
+    lineno:int, # 1-based line number
+    line:str # The line's current text
+)->str:
+    "`lineno|hash|` exhash address for `line` at `lineno`"
+    return f'{lineno}|{line_hash(line)}|'
+
+def lnhash_at(
+    s:str|list|tuple, # A document as a str, or its lines
+    line:int # 1-based line number within `s`
+)->str:
+    "`lineno|hash|` exhash address of line `line` of `s`"
+    if isinstance(s,str): s = s.splitlines()
+    return lnhash(line, s[line-1])
+
 # %% ../nbs/12_tools.ipynb #806c957b
-def file_view(
+def view_file(
     path:str, # Path to view (expands `~` if needed)
     start_line:int=1, # Starting line to view
-    end_line:int=None # End line (defaults to last line if None; may be past EOF, which clamps to the last line - handy when the file size is unknown)
+    end_line:int=None, # End line (defaults to last line if None; may be past EOF, which clamps to the last line - handy when the file size is unknown)
+    lnhashs:bool=False # Prefix `lineno|hash|` exhash addresses instead of `lineno: `
 ):
     "Read file contents, optionally limited to 1-based line range"
     path = Path(path).expanduser()
@@ -152,10 +178,10 @@ def file_view(
     if end_line < 0: end_line = len(lines)+end_line+1
     if not (1 <= start_line <= len(lines)): return f'error: Invalid start_line {start_line}. Valid range: 1-{len(lines)}'
     if end_line > len(lines): end_line = len(lines)
-    return PrettyString('\n'.join(f'{i}: {l}' for i,l in enumerate(lines[start_line-1:end_line], start_line)))
+    return PrettyString('\n'.join((lnhash(i,l) if lnhashs else f'{i}: ')+l for i,l in enumerate(lines[start_line-1:end_line], start_line)))
 
 # %% ../nbs/12_tools.ipynb #424d09e1
-def file_create(
+def create_file(
     path:str, # Path to create (expands `~` if needed)
     contents:str, # Contents of file to create
     overwrite:bool=False, # Replace the file if it already exists?
@@ -178,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()
@@ -218,4 +245,4 @@ def ast_replace(
     except ImportError as e: raise ImportError('ast_replace requires the optional `remold` package: `pip install remold`') from e
     return astmap(*repls)(text)
 
-ast_file = file_edit(ast_replace, 'ast_file')
+file_ast_replace = file_edit(ast_replace, 'file_ast_replace')

{fastcore-2.1.2 → 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.2 → fastcore-2.1.4/fastcore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastcore
-Version: 2.1.2
+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.2 → 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.2 → 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.2 → 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.2/fastcore/__init__.py

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