fastcore 2.2.26__tar.gz → 2.2.27__tar.gz

{fastcore-2.2.26/fastcore.egg-info → fastcore-2.2.27}/PKG-INFO

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

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/__init__.py

@@ -38,7 +38,7 @@ test_eq(x.unique(), [1,2,3,4,5])
 Modules:
 
 - `fastcore.aio`: Bridging async and sync code: `run_sync`, `iter_sync`, `ctx_sync`, `athreaded`, `maybe_await`, and `then`, plus `Debounce` for coalescing bursts of calls
-- `fastcore.apisurface`: Turn operation metadata into documented, introspectable callables: real signatures, informative docstrings, and browsable grouped namespaces
+- `fastcore.apisurface`: Signatures, documentation and grouped namespaces for generated API clients
 - `fastcore.basics`: Basic functionality used in the fastai library
 - `fastcore.docments`: Document parameters using comments.
 - `fastcore.editskill`: 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.
@@ -55,4 +55,4 @@ Modules:
 - `fastcore.xml`: Concise HTML generation and namespace-aware XML construction.
 - `fastcore.xtras`: Utility functions used in the fastai library"""
 
-__version__ = "2.2.26"
+__version__ = "2.2.27"

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/aio.py

@@ -2,13 +2,25 @@
 
 ## Calling async code from sync code
 
-Async libraries return coroutines, which normally force every caller up the stack to become async too. `run_sync` (coroutines), `iter_sync` (async generators), and `ctx_sync` (async context managers) let ordinary sync code drive them instead, sharing a single event loop that runs on a background daemon thread, created on first use; `maybe_await(o)` awaits `o` only if it's awaitable, else returns it as-is.
+Use these helpers to call async libraries without making your own code async:
+
+- `run_sync` runs a coroutine and returns its result.
+- `iter_sync` iterates an async generator.
+- `ctx_sync` uses an async context manager in a `with` block.
+
+They share an event loop on a background daemon thread, started on first use.
 
 ## Calling sync code from async code
 
-`athreaded` is the same bridge crossed in the other direction: it wraps a blocking function as an honest `async def`, running the original body in a worker thread so the event loop stays free. Use it to give async color to APIs that only exist in blocking form.
+`athreaded` turns a blocking function into an async function that runs its body in a worker thread. This lets async code use blocking libraries without stalling the event loop.
+
+`await maybe_await(o)` awaits `o` if it is awaitable and returns it unchanged otherwise.
+
+`then(x, *fs)` applies each function to the preceding result. It returns a plain value when all steps are synchronous, or an awaitable if `x` or any step is awaitable.
+
+This is useful for clients with both sync and async modes. A method can use `return then(self.gists.get(gid), ~Self.files.values(), first)` in either mode, without duplicating its body.
 
-`then` lets one function body serve sync and async callers alike. It applies each of `fs` in turn, awaiting anything awaitable along the way (the starting value or any step's result), and the caller gets back a plain value if the whole chain was sync, or an awaitable otherwise. This is what a convenience method on a client offering both sync and async modes needs: written as `return then(self.gists.get(gid), ~Self.files.values(), first)`, a sync client returns the file directly while an async client returns something to `await`, with no duplicated method. Because step results are awaited as part of the chain, steps may themselves be async calls; the flip side is that a step cannot return an awaitable *as* its value.
+`then` awaits every awaitable returned by a step. Steps cannot pass awaitables through as data.
 
 Docs: https://fastcore.fast.ai/aio.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/apisurface.py

@@ -1,8 +1,15 @@
-"""Turn operation metadata into documented, introspectable callables: real signatures, informative docstrings, and browsable grouped namespaces
+"""Signatures, documentation and grouped namespaces for generated API clients
 
-A client generated from a machine-readable spec (an OpenAPI document, a Google Discovery document, an SDK symbol graph) is only pleasant to use if its runtime-created callables behave like hand-written ones: tab completion shows real parameters, `?` and `doc()` show real docs, and related operations sit together in namespaces you can browse. This module builds those pieces from plain *operation records*, ducks with these attributes: `name`, `group` (a nesting path: string or list), `summary`, `docs_url`, `params` (ordered parameter names), `required_params`, `param_types`, `param_defaults`, and `param_docs`. `mk_sig` turns a record into an `inspect.Signature` (spec names sanitized to Python identifiers via `sanitized_params`), `mk_doc` renders a docstring, and `OpGroup`/`mk_groups`/`full_docs` assemble named callables into an attribute-chained tree with markdown summaries at every level.
+`apisurface` builds signatures, docstrings and grouped namespaces from API operation metadata. Generated clients can use it to support tab completion and documentation through `?` and `doc()`. `fastspec` uses it for HTTP clients generated from specifications.
 
-`fastspec` builds its HTTP clients on this layer.
+An operation record can be any object with these attributes:
+
+- `name`, `summary` and `docs_url` describe the operation.
+- `group` gives its namespace as a string, or a list for nested groups.
+- `params` lists parameter names in order. `required_params` identifies required parameters.
+- `param_types`, `param_defaults` and `param_docs` map parameter names to their metadata.
+
+`mk_sig` creates an `inspect.Signature` with Python parameter names. `mk_doc` creates a docstring. `OpGroup` and `mk_groups` organize operations into namespaces with attribute access. `full_docs` combines their overviews into Markdown.
 
 Docs: https://fastcore.fast.ai/apisurface.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/docments.py

@@ -1,6 +1,6 @@
 """Document parameters using comments.
 
-A *docment* documents a parameter with a trailing comment on its line in the signature, right next to the name, type, and default it describes; `docments(f)` retrieves them programmatically, so tools (docs tables, CLIs like `fastcore.script`, ...) can use them. This replaces repeating parameter names in a specially-formatted docstring, which has to be kept in sync with the signature by hand:
+A docment is a comment beside a parameter in a function signature. It keeps the parameter's description next to its name, type and default. `docments(f)` reads these comments for documentation tools and CLIs such as `fastcore.script`:
 
 ```python
 def add(
@@ -12,7 +12,7 @@ def add(
 test_eq(docments(add), {'a': 'The first operand', 'b': 'The second operand', 'return': 'The sum'})
 ```
 
-Comment lines *above* a param also work when one line isn't enough; `typing.Annotated` string metadata is an alternative to comments; numpy-style docstring sections are merged in when present; and `docments(f, full=True)` returns each param's default, type, and docment together.
+For longer descriptions, put comment lines above the parameter. `docments` also reads `typing.Annotated` string metadata and NumPy-style docstrings. Pass `full=True` to retrieve each parameter's default, type and docment together.
 
 Docs: https://fastcore.fast.ai/docments.html.md"""
 

fastcore-2.2.27/fastcore/editskill.py

@@ -0,0 +1,85 @@
+"""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`. When installed, prefer `exhash` for hash-verified editing, `rgapi` for search, and `aidialog` or `dialoghelper` for dialogs.
+
+## Places
+
+The tools edit strings in memory, files, notebook cells, and notebooks. File tools take a path. Cell tools take `path, cell_id` and edit that cell's source. `Notebook` and `NbCell` hold notebooks and cells in memory.
+
+A Solveit dialog is an `.ipynb` whose cells represent notes, runnable code, and prompt/reply pairs. Cell tools work with notebook structure, regardless of which application produced the file. `aidialog.dlgskill` and `dialoghelper` provide tools for reading and editing dialog messages.
+
+`open_doc` (in exhash) parses a file (`fname=`, or a `Path` as `src`), URL (an `https?://` str), or text (any other str) into a `Section` tree, with sections taken from Markdown headings, tree-sitter definitions in code, or md-heading cells in a notebook. A section points at a span of lines in a file, or a run of cells in a notebook. To change what a section contains, edit those lines or cells with the file and cell tools.
+
+## Naming
+
+Function names follow these conventions:
+
+- Operations on files, notebooks, cells, and messages use `verb_target`: `view_file`, `create_file`, `read_nb`, `write_nb`, `view_cell`, `validate_nb`, `view_msg`, and `view_dlg`. This includes `lnhashview_cell`. Names such as `find_msgs`, `add_msg`, `del_msgs`, and `find_cells` need no extra dialog or notebook prefix. `msg` identifies a dialog message and `cell` identifies a notebook cell. `summary_nb` returns rows for notebook cells.
+- Text-editing primitives include `insert_line`, `del_lines`, `replace_lines`, and `str_replace`. File, cell, and message versions add a prefix, as in `file_del_lines`, `cell_del_lines`, and `msg_del_lines`. After their address arguments, these versions take the same arguments as the text primitive.
+
+`str_replace` keeps the name and argument order established by Anthropic's text editor tool. `ast_replace` uses AST patterns to find edit targets. `exhash` takes commands containing hash-verified line addresses. These operations use the same file, cell, and message prefixes: `file_ast_replace`, `msg_ast_replace`, `file_exhash`, and `cell_exhash`.
+
+Converters use `x2y` names, such as `nb2dict` and `cell2xml`. In aidialog, exactly one side is `dlg`. Converter methods use `to_y`, as in `nb.to_dict()`.
+
+Plural names take multiple items: `view_cell` takes one cell, `lnhashview_cells` several, and `del_msgs` many.
+
+## Parameters
+
+One vocabulary, identical wherever it appears:
+
+- The place's address comes first (`text`; `path`; `path, cell_id`; a message `id`), the new text 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. `del_lines` accepts 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 unless `use_regex=True`.
+- `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 whatever units the place has: 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.
+- 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
+
+Editing functions take a file path, save their changes, and return a diff. Editing methods change an object in memory. Save it explicitly to write the changes.
+
+Methods omit the function's address arguments and the part of its name that identifies the object. For example, `cell_str_replace(path, cell_id, ...)` becomes `c.str_replace(...)` on an `NbCell`. `find_cells(path, pat)` becomes `nb.find_cells(pat)` on a `Notebook`.
+
+Read functions return snapshot rows containing addresses, source, and metadata. Read methods return the objects themselves. Use one style at a time per file. Save before switching to file functions, then reopen the object before returning to methods.
+
+## Addresses
+
+Edits accept line numbers, lnhash addresses, or section tokens. Get addresses while reading the target. Views accept `nums=True` or `lnhashs=True`. Searches can include addresses with `rg(lnhashs=True)`.
+
+Prefer lnhash addresses when `exhash` is installed. The editor checks the hash against current content and rejects stale addresses. Plain line numbers are unverified and can shift after an edit. Re-view after each plain-line-number edit and apply multiple edits from bottom to top. Read `exhash.skill` for address formats and verified editing.
+
+Section tokens identify sections in document outlines. In `1.6.|12|a3f2|,45|b1c3|`, `1.6.` is the section number. The rest is the lnhash range for its first and last lines. `d.at(token)` returns the section after checking its hash. `d.view(tok1, tok2)` prints the rendered text of both sections. Use the boundary range to edit the section: `file_exhash(path, ('12|a3f2|,45|b1c3|', 'c', new_text))`.
+
+Read `exhash.skill` before working through large Markdown, code, or notebook files, or documentation from a URL. It describes `open_doc` tree searches and link following, including the llms.txt workflow.
+
+When you don't know where to edit, start with a summary. `rgapi`'s `rg(summary=True)` and `nbrg`, aidialog's `summary_dlg`, and exhash's `open_doc` outlines show rows for blocks, cells, messages, or sections. Each row includes its address.
+
+For prose, config, and other text organized into paragraphs, block summaries show the whole matched paragraph and its boundary addresses. Line-mode results show fragments that can require another view for context.
+
+## 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, plus `open_doc` section outlines for Markdown, code, and notebooks; prefer it for edits where installed.
+- `rgapi.skill`: `rg`/`fd`/`ls`/`nbrg` search with lnhash output, and `rgstr` to search text already in hand.
+- `remold`: structural search and rewrite for Python source (declarative ast-grep rules, LibCST matcher transforms, symbol queries); the engine behind `ast_replace`.
+- `aidialog.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']
+
+__pyskill_params__ = {'replace_params': ('start_line', 'end_line', 'n_matches', 're_filter', 'invert_filter', 'use_regex')}

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/foundation.py

@@ -1,8 +1,10 @@
 """The `L` class and helpers for it
 
-`add_docs` (or the `docs` class decorator) attaches docstrings to a class and its methods from one dict kept separate from the code, so one-line methods stay one line; it also raises if any public method is left undocumented. `coll_repr` renders long list-likes as a length-prefixed preview like `(#2000) [0, 1, ...]`, and `flatmap(f, xs)` is a named `[y for x in xs for y in f(x)]`: a map where each input may produce zero, one, or many outputs.
+`add_docs` attaches docstrings to a class and its methods from a dictionary. `docs` is its decorator form. Both check that every public method has documentation.
 
-`L` is a drop-in replacement for a python `list`. Inspired by [NumPy](http://www.numpy.org/), it supports advanced indexing — an int, slice, collection of ints, or boolean mask — and its methods (`map`, `filter`, `sorted`, `unique`, `itemgot`, `attrgot`, and many more) return a new `L`, encouraging simple expressive chains:
+`coll_repr` shows a collection's length and a preview of its items. `flatmap(f, xs)` applies `f` to each item and concatenates the results.
+
+`L` extends Python's list operations with indexing inspired by [NumPy](http://www.numpy.org/). You can index with an integer, slice, collection of integers or boolean mask. Methods such as `map`, `filter`, `sorted`, `unique`, `itemgot` and `attrgot` return an `L`:
 
 ```python
 t = L(1,2,3)
@@ -12,9 +14,13 @@ test_eq(t[[False,True,False,True]], [2,4])
 test_eq(t.map(lambda o:o*2), [2,4,6,8])
 ```
 
-Most `L` methods are also *curryable*: called on the class instead of an instance, they return a partial awaiting an iterable, so `L(lines).map(L.map(int))` converts each nested list. The curryable methods are `map`, `filter`, `groupby`, `argwhere`, `argfirst`, `first`, `last`, `sorted`, `reduce`, `partition`, `takewhile`, `dropwhile`, and `accumulate`. The `star` adapter wraps a function to unpack its *last* argument as individual args, so it works uniformly across these methods (`map` passes each item last; `reduce` passes `(acc, item)`, so only the item is unpacked); `rstar` unpacks in reversed order.
+Call `L.map(int)` on the class to get a function that converts an iterable's items to integers. This curried form works with `map`, `filter`, `groupby`, `argwhere`, `argfirst`, `first`, `last`, `sorted`, `reduce`, `partition`, `takewhile`, `dropwhile` and `accumulate`.
+
+`star(f)` unpacks the last argument before calling `f`. In `map`, that argument is the item. In `reduce`, it is the item after the accumulator. `rstar` reverses the unpacked arguments.
+
+`L` has methods for `itertools` operations including `cycle`, `takewhile`, `dropwhile`, `accumulate`, `pairwise`, `batched`, `compress`, `permutations` and `combinations`.
 
-`L` also wraps the `itertools` verbs as methods: `cycle`, `takewhile`, `dropwhile`, `accumulate`, `pairwise`, `batched`, `compress`, `permutations`, `combinations`, plus `partition` (split into two `L`s by a predicate) and recursive `flatten` (strings kept atomic).
+`partition` returns two collections according to a predicate. `flatten` recursively flattens nested iterables, leaving strings intact.
 
 Docs: https://fastcore.fast.ai/foundation.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/meta.py

@@ -1,14 +1,18 @@
 """Metaclasses
 
-See this [blog post](https://realpython.com/python-metaclasses/) for more information about metaclasses.
+These metaclasses customize object construction:
 
-- `FixSigMeta` preserves signature introspection (i.e. tab completion in IDEs) when inheritance through a `__new__` or a metaclass `__call__` would otherwise obscure it; the other metaclasses here all inherit from it.
-- `PrePostInitMeta` runs `__pre_init__` and `__post_init__` automatically around `__init__` (without having to call them yourself).
-- `AutoInit` is a `PrePostInitMeta` mixin that calls `super().__init__` for you.
-- `NewChkMeta` makes `C(x)` return `x` unchanged when `x` is already a `C` and no other args are passed (how `L` avoids re-wrapping an `L`).
-- `BypassNewMeta` casts an object of another class (`_bypass_type`) to this class without copying it.
+- `FixSigMeta` preserves the constructor signature for introspection and tab completion. The other metaclasses inherit from it.
+- `PrePostInitMeta` calls `__pre_init__` before `__init__` and `__post_init__` afterward.
+- `AutoInit` is a `PrePostInitMeta` mixin that calls `super().__init__`.
+- `NewChkMeta` makes `C(x)` return `x` when `x` is already a `C` and there are no other arguments.
+- `BypassNewMeta` casts an object of `_bypass_type` to the new class without copying it.
 
-`use_kwargs`/`use_kwargs_dict` replace `**kwargs` in a signature with named params from an explicit list or dict, and `funcs_kwargs` lets a class accept method overrides as constructor kwargs. The one used everywhere in fastai code is `@delegates`: decorating `wrapper` with `@delegates(base)` replaces `**kwargs` in `wrapper`'s shown signature with `base`'s keyword parameters, so introspection and tab completion reveal the real options. Only params with defaults are copied over; `keep=True` retains `**kwargs`; `but=` excludes names; and on a class with no argument it delegates to the superclass:
+See this [introduction to metaclasses](https://realpython.com/python-metaclasses/) for background.
+
+`use_kwargs` and `use_kwargs_dict` replace `**kwargs` in a signature with parameters from a list or dictionary. `funcs_kwargs` lets a class accept method overrides as constructor arguments.
+
+`@delegates(base)` adds `base`'s optional parameters to a wrapper's displayed signature for introspection and tab completion. Use `keep=True` to retain `**kwargs` and `but` to exclude parameters. On a class, `@delegates()` uses the superclass constructor:
 
 ```python
 def basefn(a, b=2, c=3): ...

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/nbio.py

@@ -761,11 +761,9 @@ MAXLEN = 180 # Most characters shown per displayed line
 
 # %% ../nbs/13_nbio.ipynb #80541be8
 def prev_line(txt, maxlen=MAXLEN, pre='', sep=''):
-    "One-line preview `pre`+`sep`+`txt` capped at `maxlen`, blank-line runs shown as `¶`; a cut line carries `txt`'s size before `sep` and ends with the count of characters missing"
-    n = len(txt)
+    "One-line preview capped at `maxlen`, with blank-line runs shown as `¶` and a trailing count of omitted characters"
     txt = re.sub(r'\n(?:\s*\n)*', '¶', txt)
-    if len(pre)+len(sep)+len(txt)<=maxlen: return pre+sep+txt
-    return truncstr(f'{pre}[{humanize(n)}]{sep}{txt}', maxlen, suf=lambda n: f'…[{humanize(n)}]')
+    return truncstr(f'{pre}{sep}{txt}', maxlen, suf=lambda n: f'…[{humanize(n)}]')
 
 # %% ../nbs/13_nbio.ipynb #804670bc
 class CellRow:

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/parallel.py

@@ -1,6 +1,8 @@
 """Threading and multiprocessing functions
 
-`parallel(f, items)` maps `f` over `items` using a process pool (`threadpool=True` for threads instead), with `n_workers`, optional `progress` bar, a `pause` between starts (to stagger e.g. web requests), and `return_exceptions` to collect errors instead of raising; `n_workers=0` runs serially, which makes debugging easy. `parallel_async` is the asyncio version, using a semaphore to limit concurrency. `@threaded` makes a function run in a `Thread` (or `Process`) whose eventual return value lands in its `result` attr, and `startthread`/`startproc` start one immediately.
+`parallel(f, items)` applies `f` to each item using a process pool. Set `threadpool=True` to use threads. Set `n_workers` to control concurrency, or to 0 for serial execution when debugging. Optional arguments include a `progress` bar, a `pause` between starts, and `return_exceptions` to collect errors. `parallel_async` runs work concurrently with asyncio.
+
+`@threaded` runs a function in a background thread and returns the thread. Read its `result` attribute after it finishes. Set `process=True` to run in a process. `startthread` and `startproc` start their decorated functions immediately.
 
 Docs: https://fastcore.fast.ai/parallel.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/script.py

@@ -15,7 +15,7 @@ def main(
     print(msg.upper() if upper else msg)
 ```
 
-Copy that into a file and run it, and you get a CLI with help, defaults, and error handling, with no `if __name__ == "__main__"` or argument parsing code:
+`call_parse` provides argument parsing, help, defaults and error handling. Copy the example into a file and run it without adding an `if __name__ == "__main__"` block:
 
 ```
 $ examples/test_fastcore.py --help
@@ -31,11 +31,11 @@ options:
   --upper     Convert to uppercase? (default: False)
 ```
 
-The function is still a plain Python function too, so it can also be called normally, e.g from a REPL such as Jupyter.
+You can also call the function normally from Python, including in a Jupyter notebook.
 
 ## Annotated params
 
-For `argparse` features that docments can't express, use `typing.Annotated` type hints instead of plain types:
+Use `typing.Annotated` for `argparse` options that docments can't express:
 
 ```python
 from fastcore.script import *
@@ -47,45 +47,61 @@ def main(msg:Annotated[str, "The message"],
     print(msg.upper() if upper else msg)
 ```
 
-The first element of `Annotated` is the parameter's type, and the first string in its metadata is its help. A `dict` in the metadata passes extra arguments to argparse: its keys can be `opt`, `action`, `nargs`, `const`, `choices`, `required`, and `version`. All but `opt` go straight to `add_argument`; `opt` is a bool that overrides whether the param is a flag or positional, which is normally inferred from whether it has a default.
+The first element is the parameter's type. The first string in its metadata provides help text. Add a metadata dictionary to set `action`, `nargs`, `const`, `choices`, `required` or `version` arguments for `argparse.add_argument`.
+
+The dictionary also accepts `opt`. Set it to `True` for a flag or `False` for a positional parameter. Without `opt`, parameters with defaults become flags.
 
 ## Short flags
 
-A capital letter in a parameter name declares a short flag: the capitalized letter becomes the short spelling and the lowercased name the long one, so `Resume:int=None` gets both `-r` and `--resume`. The capital can be any letter (`sUggest:str=None` gives `-u/--suggest`), only the first capital counts, and names without capitals get a long flag only. Underscores in optional parameter names appear as hyphens (`cache_dir` becomes `--cache-dir`), while the Python argument keeps its underscore. Since the flags are lowercased, the parameter's actual name keeps its capital -- so a Python caller writes `main(Resume=3)`, which usefully advertises that it's invoking a CLI entry point. Positional (default-less) parameters have no flags, so capitals there are left alone.
+The first capital letter in an optional parameter's name declares a short flag:
+
+- `Resume:int=None` gives `-r` and `--resume`.
+- `sUggest:str=None` gives `-u` and `--suggest`.
+- Names without capitals have only a long flag.
+
+Long flags use lowercase and hyphens, such as `--cache-dir` for `cache_dir`. Python calls keep the parameter's spelling, such as `main(Resume=3)`. Positional parameters have no flags and keep their names unchanged.
 
 ## Positional params
 
-Parameters without a default are positional, and the rest are flags. A `*args` parameter is a variadic positional, taking zero or more values, and since Python makes any params after it keyword-only, they are flags. A `**kwargs` parameter is skipped: a CLI run passes nothing for it. Pass `pos` to `call_parse` (or to `anno_parser`) to keep named parameters positional even when they have a default, in which case they are optional on the command line and take the default when omitted. Command line order follows the signature, not the order of the names in `pos`. Naming a bool parameter in `pos` raises, since a flag takes no value.
+Parameters without defaults are positional. Other parameters become flags. `*args` accepts zero or more positional values. Parameters after it are flags. CLI calls ignore `**kwargs`.
+
+Pass parameter names in `pos` to `call_parse` or `anno_parser` to keep them positional even with defaults. Omitted values use those defaults. Command-line order follows the signature, regardless of the order in `pos`. A boolean flag cannot appear in `pos` because it takes no value.
 
 ## Param types
 
 A `bool` parameter is a `store_true` flag defaulting to `False`. If its default is `True` it becomes a `--no-` prefixed `store_false` flag instead, so passing the flag turns it off. Use `bool_arg` as the type when you want an explicit `--flag true|false` argument that honors its default.
 
-By default argparse repeats an option's name, upper-cased, as the placeholder for its value: `--path PATH`. That repeat says nothing useful, so help shows the annotation instead: `--path (str)`. `anno2str` gives the display name. The name describes the semantics rather than the mechanics: `Path` displays as `path`, and a union names each member once, dropping `str` when `path` is present since a path already is a string -- which is why `Path|str` is plain `path`. Enum params keep argparse's `{choice,...}` display, and positional params keep their name.
+`argparse` normally repeats an option's name as its value placeholder, such as `--path PATH`. Here help shows the type instead, such as `--path (str)`.
+
+`anno2str` formats the type name. It displays `Path` as `path`. Unions list each type once and omit `str` when `path` is present. For example, `Path|str` displays as `path`.
+
+Enums show their choices as `{choice,...}`. Positional parameters show their names.
 
 Union types such as `int|str` try each type in turn, and `enum` types such as those from `str_enum` become argparse choices.
 
 ## The CLI entry point
 
-The decorated function is always the CLI entry point, and only the entry point gets `sys.argv`: argv is parsed when the function's file is run directly (`python foo.py`, `python -m foo`, or `%run foo.py`), or when it's called with no arguments from the top-level body of a directly-run file (which is how console script wrappers invoke it). Every other call is a plain Python call that ignores argv, whether from a notebook, the REPL, another function, or another `call_parse` function.
+`call_parse` parses `sys.argv` when you run the function's file directly with `python foo.py`, `python -m foo` or `%run foo.py`. It also parses arguments on a zero-argument call from the top-level body of a directly run file. Console-script wrappers use this form.
+
+Calls from a notebook, REPL or another function are ordinary Python calls. This includes calls from another `call_parse` function.
 
-CLI calls return only `int` values (including `bool`) for console script exit codes; other return values are discarded. Plain Python calls preserve the return value. To report an error message, raise `CliError` rather than returning a string.
+CLI calls return integers, including booleans, as exit codes. They discard other return values. Python calls preserve return values. Raise `CliError` to report an error message to CLI users.
 
-Use the `nested` keyword argument to create nested parsers, where earlier parsers consume only their known args from `sys.argv` before later parsers are used. This is useful to create one command line application that executes another. For example:
+Set `nested=True` when one CLI launches another. The outer parser removes the arguments it recognizes from `sys.argv`, leaving the rest for the inner CLI:
 
 ```sh
 myrunner --keyword 1 script.py -- <script.py args>
 ```
 
-A separating `--` after the first application's args is recommended though not always required, otherwise args may be parsed in unexpected ways. For example:
+`--` is optional in some invocations. Use it to separate the applications' arguments and avoid cases such as:
 
 ```sh
 myrunner script.py -h
 ```
 
-would display `myrunner`'s help and not `script.py`'s.
+`myrunner` handles `-h` here instead of passing it to `script.py`.
 
-A function usable both from the command line and from Python can call `is_cli` to tell which way it was invoked, e.g. returning a value to Python callers but printing it when run as a CLI:
+Use `is_cli` to distinguish CLI execution from Python calls. Here the CLI prints a result that Python callers receive as a return value:
 
 ```python
 @call_parse
@@ -97,7 +113,7 @@ def sum_args(a:int=0, b:int=0):
 test_eq(sum_args(1,2), 3)  # Python call: returns the value, prints nothing
 ```
 
-A command that cannot continue raises `CliError` with a message for the user. A CLI run prints just that message to stderr and exits with status 1. A Python call gets the exception to handle as it likes, so the raise site needs no `is_cli` branch:
+Raise `CliError` when a command cannot continue. CLI execution prints its message to stderr and exits with status 1. Python callers can catch the exception:
 
 ```python
 @call_parse

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/tools.py

@@ -1,10 +1,12 @@
 """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 aidialog. (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.
+The text editors take a string and return the edited text. Invalid edits raise `ValueError`. File editors read and write a path and return a diff. Aidialog provides corresponding message editors.
 
-`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.
+Read `fastcore.editskill` for the editing toolkit's naming, parameter and workflow conventions. It exposes these tools alongside the notebook editors from `fastcore.nbio`.
 
-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:
+`line_hash`, `lnhash` and `lnhash_at` create [exhash](https://answerdotai.github.io/exhash) addresses without depending on the exhash package. Addresses use `lineno|hash|`. The hash is the low 16 bits of CRC32, formatted as four hexadecimal characters.
+
+File editors take the path first and return a unified diff. An unchanged result returns `none: No changes.` Invalid edits return `error: ...`.
 
     view_file('~/a/b.py', 3)
     create_file('~/a/b/c.py', 'content here')
@@ -12,7 +14,9 @@ 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).
+`file_str_replace`, `file_strs_replace` and `file_del_lines` support line ranges, `re_filter` and `invert_filter`. These work like ex's `g//` and `g!//` filters.
+
+For Python syntax-tree replacements, use `ast_replace` or `file_ast_replace`. They accept ast-grep `(pattern, replacement)` rules with `$VAR` metavariables and require the optional `remold` package.
 
 Docs: https://fastcore.fast.ai/tools.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/xml.py

@@ -1,6 +1,10 @@
 """Concise HTML generation and namespace-aware XML construction.
 
-`ft(tag, *children, **attrs)` builds an `FT` tree — a lightweight XML/HTML element — and `to_xml` renders it (this is the foundation [fasthtml](https://fastht.ml) builds on). The common HTML tags are predefined as `ft` partials (`Div`, `P`, `A`, ...). Attributes are passed as keywords: use `klass` and `fr` for the reserved words `class` and `for`, `_` in an attr name becomes `-`, and attrs can be got and set on the object directly. Children can also be supplied after the attrs by calling the element, e.g. `Div(id='x')(child1, child2)`:
+`ft(tag, *children, **attrs)` builds an `FT` tree for HTML generation. `to_xml` renders the tree. [FastHTML](https://fastht.ml) uses these functions to generate HTML.
+
+Common tags have constructors such as `Div`, `P` and `A`. Pass attributes as keywords, using `klass` for `class` and `fr` for `for`. Underscores in attribute names become hyphens. You can also get and set attributes on the element.
+
+To supply children after attributes, call the element: `Div(id='x')(child1, child2)`.
 
 ```python
 t = Div(P('hi', klass='a'), hx_get='/get')
@@ -8,7 +12,15 @@ test_eq(to_xml(t), '<div hx-get="/get">\n  <p class="a">hi</p>\n</div>\n')
 test_eq(to_xml(Div(id='x')('child')), '<div id="x">child</div>\n')
 ```
 
-`E(prefix='', attr_ns=None, ns=None)` creates a namespace-bound XML factory. `e = E('w', attr_ns='w', ns={'w': uri})` supports expressions such as `e.tcW(type='dxa', w=2400)`. Tags and attributes preserve case. `prefix__name` selects an attribute namespace; `attrs_` accepts literal names. Expressions compose with text and ordered collections, retain their namespace bindings, and serialize as UTF-8 with `.bytes()`. XML text is escaped and booleans become `true`/`false`; subclasses override `attr_value` for vocabularies with other rules. The existing `ft` and `to_xml` APIs keep their HTML behavior.
+`E` creates XML elements from Python calls. Its `ns` argument maps namespace prefixes to URIs. The `prefix` and `attr_ns` arguments set the default prefixes for element and attribute names.
+
+For example, `e = E('w', attr_ns='w', ns={'w': uri})` uses `w` for both defaults. Calling `e.tcW(type='dxa', w=2400)` creates a `w:tcW` element with `w:type` and `w:w` attributes.
+
+`E` preserves the case of tag and attribute names. Use `prefix__name` for an explicitly prefixed attribute, or `attrs_` for literal attribute names.
+
+Nesting an element under a different parent does not change its namespace bindings.
+
+XML serialization escapes text and writes booleans as `true` or `false`. Override `attr_value` for other conventions. `.bytes()` returns UTF-8. `ft` and `to_xml` retain their HTML behavior.
 
 Docs: https://fastcore.fast.ai/xml.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27}/fastcore/xtras.py

@@ -1,10 +1,18 @@
 """Utility functions used in the fastai library
 
-Utilities (other than extensions to `Pathlib.Path`) for dealing with IO: `maybe_open` accepts a path or an already-open file, only closing what it opened; `run` passes a command line to `subprocess.run` and returns its `stdout`, raising `IOError` on failure; `atomic_save` writes via a temp file and renames, so readers never see a partial write; `untar_dir` extracts an archive the way you'd want (a lone top-level item lands directly in `dest`); and `globtastic` is a recursive glob with file/folder include and exclude filters.
+IO utilities include:
 
-`Config` wraps a `ConfigParser` ini file with a single `DEFAULT` section: keys read as attributes, items, or `.get` with a default; `create=` writes initial contents if the file is missing; `types=` coerces values on read, resolving `Path` values relative to the config file's directory; and `Config.find(name)` searches a directory and its parents for the file.
+- `maybe_open`: accept a path or an open file, closing only files it opens.
+- `run`: run a command and return stdout; raise `IOError` on failure.
+- `atomic_save`: write a temporary file, then rename it over the destination.
+- `untar_dir`: extract an archive, creating a containing directory when needed.
+- `globtastic`: recursively find files with include and exclude filters.
 
-`dict2obj` converts a (possibly nested) dict, or list of dicts, to attribute access: dicts become `AttrDict` and lists become `L`, so `d.b.c` replaces `d['b']['c']`; `obj2dict` reverses it:
+`Config` reads and writes an ini file with one `DEFAULT` section. Access keys as attributes, items, or with `.get(key, default)`. Use `create=` to supply initial contents for a missing file.
+
+`types=` converts values on read. `Path` values resolve relative to the config file's directory. `Config.find(name)` searches a directory and its parents for the file.
+
+`dict2obj` converts nested dicts to `AttrDict` and lists to `L`, allowing attribute access such as `d.b.c`. `obj2dict` reverses the conversion:
 
 ```python
 d = dict2obj({'a':1, 'b':{'c':2, 'd':[3,4]}})
@@ -12,9 +20,22 @@ test_eq(d.b.c, 2)
 test_eq(d.b.d[1], 4)
 ```
 
-The following methods are added to the standard python library [Pathlib.Path](https://docs.python.org/3/library/pathlib.html#basic-use): `ls()` (dir contents as an `L`, with optional `file_type` MIME-prefix and `file_exts` filters); `read_json`/`write_json`, and `read_jsonl` which is safe for JSON Lines (only `\n` ends a record, unlike `splitlines`); `readlines`, `mk_write` (create parent dirs, then write), `delete`, `relpath`, and `normpath`. If `Path.BASE_PATH` is set, paths repr relative to it.
+These methods extend [Pathlib.Path](https://docs.python.org/3/library/pathlib.html#basic-use):
+
+- `ls()` lists directory contents as an `L`, optionally filtered by MIME prefix or extension.
+- `read_json`, `write_json`, and `read_jsonl` handle JSON files.
+- `readlines` reads lines; `mk_write` creates parent directories before writing.
+- `delete`, `relpath`, and `normpath` provide file deletion and path conversions.
+
+Set `Path.BASE_PATH` to display paths relative to that directory.
+
+Other utilities include:
 
-Highlights among the rest: `exec_eval` runs a code string like a notebook cell, returning the last expression's value; `fenced` wraps text in a markdown code fence guaranteed longer than any run of the fence char inside it; `str_diff` returns a unified diff, `''` when the texts match; `unqid` and `friendly_name` generate random identifiers (a valid Python name, or a memorable `adjective-noun-...` string); and `flexicache` is an `lru_cache` with pluggable eviction policies such as `time_policy` and `mtime_policy`.
+- `exec_eval`: run a code string and return its last expression, like a notebook cell.
+- `fenced`: wrap text in a Markdown fence longer than any fence character run in the body.
+- `str_diff`: return a unified diff, or `''` for identical text.
+- `unqid` and `friendly_name`: generate random Python identifiers or memorable word-based names.
+- `flexicache`: cache results with configurable expiration policies.
 
 Docs: https://fastcore.fast.ai/xtras.html.md"""
 

{fastcore-2.2.26 → fastcore-2.2.27/fastcore.egg-info}/PKG-INFO

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

fastcore-2.2.26/fastcore/editskill.py

@@ -1,67 +0,0 @@
-"""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, `aidialog`/`dialoghelper` for dialogs.
-
-## Places
-
-Each editing function works on one place: 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 places: a Solveit dialog is an .ipynb whose cells are messages (notes, runnable code, prompt/reply pairs), and `aidialog.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?").
-
-The section layer sits above both. `open_doc` (in exhash) parses a file (`fname=`, or a `Path` as `src`), URL (an `https?://` str), or text (any other str) into a `Section` tree, with sections taken from Markdown headings, tree-sitter definitions in code, or md-heading cells in a notebook. A section points at a span of lines in a file, or a run of cells in a notebook. To change what a section contains, edit those lines or cells with the file and cell tools.
-
-## Naming
-
-Two name shapes cover the toolkit, and the pivot is the verb's direct object:
-
-- An operation on a whole place takes the place as its noun: verb_place. `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 unit inside the place, and that unit names its place uniquely, no prefix is needed - the unit noun is the place 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 place already owns its noun (`insert_line`, `del_lines`, `replace_lines`, `str_replace`), so the place prefixes as a namespace and the op name survives intact: place_op, as in `file_del_lines`, `cell_del_lines`, `msg_del_lines`. The bare op names are the text-level primitives, and every place 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), place-prefixed like any other line-level op: `file_ast_replace`, `msg_ast_replace`, `file_exhash`, `cell_exhash`. Converters are named x2y (`nb2dict`, `cell2xml`; in aidialog, `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 place's address comes first (`text`; `path`; `path, cell_id`; a message `id`), the new text 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. `del_lines` accepts 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 caution.
-- `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 whatever units the place has: 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 changes 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 place word 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 plain snapshot rows carrying addresses, source, and meta; session-side reads return the objects themselves. Use one shape at a time per file: save before switching to functions, reopen after.
-
-## Addresses
-
-Edits say where with line numbers, lnhash addresses, or section tokens. 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 why taking addresses early works. 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. Section tokens make a long document navigable and editable a piece at a time. An outline row shows one, as in `1.6.|12|a3f2|,45|b1c3|`: the section number, then the lnhash addresses of its first and last lines. `d.at(token)` returns that section with its hash checked, `d.view(tok1, tok2)` prints the rendered text of each, and the same boundary pair drops straight into a range edit: `file_exhash(path, ('12|a3f2|,45|b1c3|', 'c', new_text))`. Read `exhash.skill` before working through a large Markdown, code, or notebook file, or before reading documentation from a URL: `open_doc` also searches within a tree and follows links, which is how the llms.txt docs workflow runs.
-
-When you don't yet know where to edit, locate with a summary first: `rgapi`'s `rg(summary=True)` and `nbrg`, aidialog's `summary_dlg`, and exhash's `open_doc` outlines each show one row per natural unit (block, cell, message, section), carrying the unit's address. For prose, config, and other paragraph-shaped text, blocks are usually the right unit for reading too: one summary row shows the whole matched paragraph with its boundary addresses, where a line-mode hit shows a fragment that then needs a context view. 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, plus `open_doc` section outlines for Markdown, code, and notebooks; prefer it for edits where installed.
-- `rgapi.skill`: `rg`/`fd`/`ls`/`nbrg` search with lnhash output, and `rgstr` to search text already in hand.
-- `remold`: structural search and rewrite for Python source (declarative ast-grep rules, LibCST matcher transforms, symbol queries); the engine behind `ast_replace`.
-- `aidialog.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']
-
-__pyskill_params__ = {'replace_params': ('start_line', 'end_line', 'n_matches', 're_filter', 'invert_filter', 'use_regex')}