rgapi 0.1.30__tar.gz → 0.2.0__tar.gz

{rgapi-0.1.30 → rgapi-0.2.0}/Cargo.lock

@@ -70,13 +70,12 @@ checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
 
 [[package]]
 name = "encoding_rs"
-version = "0.8.41"
+version = "0.8.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b5ef0006ac9ab233c38522f5ae99cae3625151de8f706cacee1cba4b8e2832a"
+checksum = "8e985e0451871ad22fb8d2b6b076e2028a502a0d3950998c2c5c0a4f9b5d9679"
 dependencies = [
  "cfg-if",
  "core_detect",
- "multiversion",
  "multiversion_no_op",
  "rustversion",
  "scopeguard",
@@ -197,27 +196,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "multiversion"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4ca4bea16ffc3f443cf7d866912118196bfef4c6a1556ca00f9f9b00bb43f7c"
-dependencies = [
- "multiversion-macros",
-]
-
-[[package]]
-name = "multiversion-macros"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d416831a7317ef4b08bee00b69cbbb9c8763da7959a7026244d6266869f9c83"
-dependencies = [
- "proc-macro2",
- "quote",
- "rustversion",
- "syn 3.0.6",
-]
-
 [[package]]
 name = "multiversion_no_op"
 version = "1.0.0"
@@ -330,7 +308,7 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rgapi"
-version = "0.1.30"
+version = "0.2.0"
 dependencies = [
  "crc32fast",
  "globset",

{rgapi-0.1.30 → rgapi-0.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rgapi"
-version = "0.1.30"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.91"
 license = "Apache-2.0"

{rgapi-0.1.30 → rgapi-0.2.0}/DEV.md

@@ -13,7 +13,7 @@ python/rgapi/     public Python wrappers over `rgapi._core`, plus the `rgapi-nbr
 tests/            pytest coverage for the Python API
 ```
 
-The public Python API lives in `python/rgapi/__init__.py`. The extension module is private as `rgapi._core`; keep crate-like functions there and put Python-facing argument policy in the wrapper when that stays concise. For example, `glob=` and `ext=` are Python wrapper conveniences over the core include glob list.
+The public Python API lives in `python/rgapi/__init__.py`. The extension module is private as `rgapi._core`; keep crate-like functions there and put Python-facing argument policy in the wrapper when that stays concise. For example, `glob=` and `ext=` are Python wrapper conveniences over the core include glob list. Every walking `_core` function takes the walk options as one dict, which PyO3 reads into `WalkOptions`. `_walk(root, **kwargs)` builds that dict. A new walk parameter adds a field to `WalkOptions` and a parameter to `_walk_args`. No `_core` signature changes.
 
 ## Commands
 
@@ -38,20 +38,20 @@ The GitHub workflow builds wheels for Python 3.10-3.13 on Linux and macOS and pu
 
 ## Design notes
 
-Python discovery and `paths=True` results contain absolute `pathlib.Path` objects. Structured search rows retain root-relative string labels with `/` separators. Traversal uses `ignore::WalkParallel`, so result order is not part of the API contract. Search results are structured rows; collected result lists use rg-style `str()` and notebook display. `SearchLine.lnhash` is computed with the same CRC-32-based line-content hash format as exhash (`lineno|hash|`, low 12 bits of CRC-32 over the line's UTF-8 bytes, encoded as two Base64url characters); `lnhashs=True` only changes row display, not `line_number` or matching behavior. Path regexes filter returned/searched paths; `skip_dir` and `skip_dir_re` prune traversal through `ignore::WalkBuilder::filter_entry`. Depth, size, filesystem, hidden, and ignore options use `ignore::WalkBuilder` settings. Discovery checks root links with `symlink_metadata` and returns an unfollowed link through a ready stream without a worker. This also supports dangling roots, which the underlying walker would reject. Other discovery roots use absolute paths without canonicalizing. Content searches retain canonical root resolution. `rg_iter` exposes the same parallel search stream that `rg` collects by default; `paths=True` and `count=True` consume that stream with different reducers. Text search skips binary files and invalid UTF-8 content.
+Python discovery and `paths=True` results contain absolute `pathlib.Path` objects. Structured search rows hold base-relative string labels with `/` separators. Traversal uses `ignore::WalkParallel`, so result order is not part of the API contract. Search results are structured rows; collected result lists use rg-style `str()` and notebook display. `SearchLine.lnhash` is computed with the same CRC-32-based line-content hash format as exhash (`lineno|hash|`, low 12 bits of CRC-32 over the line's UTF-8 bytes, encoded as two Base64url characters); `lnhashs=True` only changes row display, not `line_number` or matching behavior. Path regexes filter returned/searched paths; `skip_dir` and `skip_dir_re` prune traversal through `ignore::WalkBuilder::filter_entry`. Depth, size, filesystem, hidden, and ignore options use `ignore::WalkBuilder` settings. The `ignore` walker follows every root it is given. Discovery checks each root with `symlink_metadata`. The worker sends each unfollowed link root as a result before walking the other roots. This also supports dangling roots, which the underlying walker would reject. `ls` sets `walk_root_links`, which gives a root link to a directory to the walker. The walker then reports paths under the link. Other discovery roots use absolute paths without canonicalizing. Content searches retain canonical root resolution. `rg_iter` exposes the same parallel search stream that `rg` collects by default; `paths=True` and `count=True` consume that stream with different reducers. Text search skips binary files and invalid UTF-8 content.
 
 Streaming engine: `walk.rs` owns the generic machinery. `StreamIter<T>` is the worker-thread-plus-bounded-channel iterator (`sync_channel(8192)`, so producers block rather than buffer without limit when a consumer lags), and `spawn_walk` owns the shared scaffold: walker config, panic catching, cancel flag, and worker thread. `rg_iter` (`T = SearchLine`), `block_iter` (`T = SearchBlock`), `nb_iter` (`T = NbCell`), and `find_iter` (`T = PathBuf`, the path walk) plug entry closures into that engine. Block search reads each file once, searches it once, groups nonblank lines into blocks, maps matching lines to their blocks, and expands context by block index. Each `SearchBlock` carries numeric boundaries plus hashes for its first and last source lines. Python keeps both and chooses the displayed address without another file read.
 
+`resolve_roots` makes the roots absolute, or canonical for content searches, and drops repeats. It also computes the base that result paths and filters are relative to. A directory root is its own base. A file root, or a link root that is not followed, has its parent as its base. Several roots use the common ancestor of their bases. `spawn_walk` walks the roots one after another on its worker thread, with one `ignore` walker per root. Each walker applies the file-root rules to its own root. Entry closures receive the base, not the root. When one root is inside another, a shared set of visited paths lets each path reach the entry closure once. Python gets the same base from `_core.walk_base`.
+
 Async API: `fda`, `fda_iter`, `rga`, `rga_iter`, `nbrga`, and `nbrga_iter` wrap the corresponding private core operations. `rga(summary=True)` uses `_core.block_search_async`; ordinary `rga` uses `_core.rg_async`. Each collected core function takes a Python callback, runs on Rust threads through the generic `stream_async` helper, and delivers with one GIL attach at the end. Iterator forms use `stream_iter_async` and attach once per batch. The Python side settles an `asyncio.Future` or feeds an `asyncio.Queue` via `loop.call_soon_threadsafe`; no Python thread blocks and `asyncio.to_thread` is not involved. `AsyncHandle.cancel()` sets the same atomic flag used by the Rust iterators.
 
 Truncation is recorded on collected results: `max_results` sets `stop_reason="max_results"`, and `timeout_ms` on `rg`/`rga`/`nbrg`/`nbrga`/`fd`/`fda`/`walk`/`ls` sets `stop_reason="timeout"`. `SearchResults`, `BlockResults`, `PathResults`, and `NbResults` share this through `_Results`; `complete` means `stop_reason is None`. In block summary mode, `max_results` counts matching blocks and keeps their block context. `count=True` returns a plain int, so it rejects timeouts and block summary mode.
 
-Rust discovery returns root-relative `PathBuf` values. Glob filters operate on native paths; only regex matching uses string labels. PyO3 converts discovery roots and results with its filesystem-path support. Python joins each result to its absolute base without resolving links. `PathResults` stores that display base and completion status, including across slices. Its `__repr__` uses `Path.lstat()` for an `ls -l`-style listing capped at `MAX_REPR` rows. `str()` returns one root-relative name per line. `ls` is `fd` with shell-style defaults (one level, dirs, ignore rules off), sorted in place.
+Rust discovery returns base-relative `PathBuf` values. Glob filters operate on native paths; only regex matching uses string labels. PyO3 converts discovery roots and results with its filesystem-path support. Python joins each result to the base from `_core.walk_base` without resolving links. `PathResults` stores that display base and completion status, including across slices. Its `__repr__` uses `Path.lstat()` for an `ls -l`-style listing capped at `MAX_REPR` rows. `str()` returns one base-relative name per line. `ls` is `fd` with shell-style defaults (one level, dirs, ignore rules off) and `walk_root_links`, sorted in place.
 
 Rust callers can consume a `StreamIter` with `cancel_and_join()` to cancel, drain queued results, and wait for the walk's workers to finish. `Drop` remains nonblocking. Since filesystem calls already in progress must return before joining completes, keep `cancel_and_join()` off async executors.
 
 Notebook hierarchy uses `heading_level(source)`, `section_range(levels, idx)` and `ancestor_indices(levels, idx)`. Callers supply zero for non-heading cells. Heading detection skips blank lines and lines starting with `#|`, then checks the first remaining line against `^#{1,6} \w`. It does not search past ordinary text. Section ranges include the addressed cell and end before the next equal-or-higher heading; non-headings select themselves. Ancestors exclude the addressed cell and are returned outermost first. These are calculations over the supplied levels, without retained outline state. Rustygate uses them for its cell selectors.
 
 `cell_refs(cell)` takes an nbformat cell as a `serde_json::Value` and returns its sigil references as `CellRefs { vars, cmds, tools }`, in order of appearance, with duplicates. A prompt cell has `solveit_ai: true` in its metadata. `vars` holds each `expr` written as `` $`expr` `` in a prompt cell's source. `cmds` holds each `cmd` written as `` !`cmd` `` in a prompt cell's source. `tools` holds each name written as `` &`name` `` or `` &`[a, b]` ``. A name holds word characters and dots. `cell_refs` reads `tools` from the source of a prompt or Markdown cell. For every other cell it reads the `text/markdown` data of `display_data` and `execute_result` outputs. It never reads a prompt cell's outputs. This function is Rust-only. Rustygate uses it for the cells API's `refs=true`.
-
-This package intentionally has no CLI. Python is the interface.

{rgapi-0.1.30 → rgapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rgapi
-Version: 0.1.30
+Version: 0.2.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Requires-Dist: fastcore>=2.2.29
@@ -36,6 +36,7 @@ fd(".", ext="py", exclude="test_*.py")
 ls("src")
 for row in rg_iter("TODO", ".", include="*.py", context=2): print(row.asdict())
 rg("TODO", ".", ext="py", skip_dir=".venv", paths=True)
+rg("TODO", ["src", "tests"], ext="py")
 ```
 
 For cell-aware search of Jupyter notebooks (see [Notebooks](#notebooks)):
@@ -77,7 +78,9 @@ pip install rgapi
 
 ## File discovery
 
-`fd` and `walk` return absolute `pathlib.Path` objects. Use them directly with `.read_text()`, `.open()`, `.stat()`, or other filesystem operations. Their collected results display names relative to `root`. Pass `root` as a `str` or `Path`. The sync and async APIs expand `~` and accept `.`, `./`, and paths containing `..`.
+`fd` and `walk` return absolute `pathlib.Path` objects. Use them directly with `.read_text()`, `.open()`, `.stat()`, or other filesystem operations. Their collected results display names relative to `root`. Pass `root` as a `str` or `Path`, or as a list of them. The sync and async APIs expand `~` and accept `.`, `./`, and paths containing `..`.
+
+A list of roots, such as `rg("TODO", ["src", "tests"])`, works with every walk and search function. The roots are searched as one walk that returns one result list. `timeout_ms` and `max_results` apply to the whole walk. Result paths are relative to the common ancestor of the roots. For example, rows read `src/app.py` and `tests/test_app.py`. `PathResults` displays use the same relative paths. Filters such as `include`, `path_re` and `skip_dir` match these relative paths. A file under more than one root, such as `src/app.py` with roots `[".", "src"]`, appears once.
 
 Discovery uses the `ignore` crate with ripgrep's default filters. It reads `.gitignore`, `.ignore`, and `.rgignore` files. `.rgignore` takes precedence over `.gitignore`. Pass `ignore=False` to disable all ignore-file filtering, including `.rgignore`.
 
@@ -142,7 +145,7 @@ Use `.name`, `.suffix`, and `.relative_to(root)` for path components. `.stat()`
 
 Structured text and notebook search rows retain root-relative string labels in their `path` fields. Content searches still follow explicitly named root links. This differs from discovery's default of returning the link itself.
 
-The Rust `find` and `find_iter` APIs return native `PathBuf` values relative to the root. For an explicitly named file or unfollowed root link, the result is its basename.
+The Rust `find` and `find_iter` APIs return native `PathBuf` values relative to the root, or to the common ancestor of several roots in `WalkOptions::roots`. For an explicitly named file or unfollowed root link, the result is its basename.
 
 Rust callers can set `FindOptions::special_files` to also discover FIFOs, sockets, and device nodes, for example to reject unsupported entries during archiving. This defaults to false; normal discovery returns regular files, directories when requested, and symlinks.
 
@@ -224,6 +227,7 @@ The parser reads only each cell's `id`, `cell_type`, and `source`. It skips outp
 ```bash
 rgapi-nbrg 'read_csv' .
 rgapi-nbrg 'read_csv' . --cell-context 1
+rgapi-nbrg 'read_csv' nbs tests
 rgapi-nbrg 'read_csv' nbs --glob '*.ipynb' --max-results 20
 ```
 

{rgapi-0.1.30 → rgapi-0.2.0}/README.md

@@ -15,6 +15,7 @@ fd(".", ext="py", exclude="test_*.py")
 ls("src")
 for row in rg_iter("TODO", ".", include="*.py", context=2): print(row.asdict())
 rg("TODO", ".", ext="py", skip_dir=".venv", paths=True)
+rg("TODO", ["src", "tests"], ext="py")
 ```
 
 For cell-aware search of Jupyter notebooks (see [Notebooks](#notebooks)):
@@ -56,7 +57,9 @@ pip install rgapi
 
 ## File discovery
 
-`fd` and `walk` return absolute `pathlib.Path` objects. Use them directly with `.read_text()`, `.open()`, `.stat()`, or other filesystem operations. Their collected results display names relative to `root`. Pass `root` as a `str` or `Path`. The sync and async APIs expand `~` and accept `.`, `./`, and paths containing `..`.
+`fd` and `walk` return absolute `pathlib.Path` objects. Use them directly with `.read_text()`, `.open()`, `.stat()`, or other filesystem operations. Their collected results display names relative to `root`. Pass `root` as a `str` or `Path`, or as a list of them. The sync and async APIs expand `~` and accept `.`, `./`, and paths containing `..`.
+
+A list of roots, such as `rg("TODO", ["src", "tests"])`, works with every walk and search function. The roots are searched as one walk that returns one result list. `timeout_ms` and `max_results` apply to the whole walk. Result paths are relative to the common ancestor of the roots. For example, rows read `src/app.py` and `tests/test_app.py`. `PathResults` displays use the same relative paths. Filters such as `include`, `path_re` and `skip_dir` match these relative paths. A file under more than one root, such as `src/app.py` with roots `[".", "src"]`, appears once.
 
 Discovery uses the `ignore` crate with ripgrep's default filters. It reads `.gitignore`, `.ignore`, and `.rgignore` files. `.rgignore` takes precedence over `.gitignore`. Pass `ignore=False` to disable all ignore-file filtering, including `.rgignore`.
 
@@ -121,7 +124,7 @@ Use `.name`, `.suffix`, and `.relative_to(root)` for path components. `.stat()`
 
 Structured text and notebook search rows retain root-relative string labels in their `path` fields. Content searches still follow explicitly named root links. This differs from discovery's default of returning the link itself.
 
-The Rust `find` and `find_iter` APIs return native `PathBuf` values relative to the root. For an explicitly named file or unfollowed root link, the result is its basename.
+The Rust `find` and `find_iter` APIs return native `PathBuf` values relative to the root, or to the common ancestor of several roots in `WalkOptions::roots`. For an explicitly named file or unfollowed root link, the result is its basename.
 
 Rust callers can set `FindOptions::special_files` to also discover FIFOs, sockets, and device nodes, for example to reject unsupported entries during archiving. This defaults to false; normal discovery returns regular files, directories when requested, and symlinks.
 
@@ -203,6 +206,7 @@ The parser reads only each cell's `id`, `cell_type`, and `source`. It skips outp
 ```bash
 rgapi-nbrg 'read_csv' .
 rgapi-nbrg 'read_csv' . --cell-context 1
+rgapi-nbrg 'read_csv' nbs tests
 rgapi-nbrg 'read_csv' nbs --glob '*.ipynb' --max-results 20
 ```
 

{rgapi-0.1.30 → rgapi-0.2.0}/python/rgapi/__init__.py

@@ -3,7 +3,7 @@ from contextlib import aclosing
 from datetime import datetime
 from stat import S_ISLNK, filemode
 
-from os import fspath
+from os import PathLike, fspath
 from pathlib import Path
 from fastcore.meta import delegates
 
@@ -41,12 +41,11 @@ def _hsize(n):
         n /= 1024
     return f"{n:.0f}" if u == "B" else f"{n:.1f}{u}"
 
-def _path_base(root, follow_links=True):
-    root = Path(root).absolute()
-    return root if (follow_links or not root.is_symlink()) and root.is_dir() else root.parent
-
 class PathResults(_Results):
-    "Absolute `Path` objects with root-relative plain and `ls -l`-style displays"
+    """Absolute `Path` objects with root-relative plain and `ls -l`-style displays.
+
+    The display is an ls-style table capped at `MAX_REPR` names. `str(res)` gives one root-relative name per line, and `list(res)`
+    the absolute Paths. Slices keep the display root and completion status."""
     def __init__(self, paths=(), root=".", show_target=False):
         self.root,self.show_target = Path(root).absolute(),show_target
         super().__init__(self.root/p for p in paths)
@@ -94,7 +93,7 @@ def _context(context, before_context, after_context):
 
 
 def walk(
-    root:str|Path=".", # Directory or file to walk (expands `~`)
+    root:str|Path|list=".", # Directory or file to walk, or a list of them (expands `~`)
     hidden:bool=False, # Include hidden files and directories
     ignore:bool=True, # Respect `.gitignore` and other ignore files
     max_depth:int|None=None, # Maximum directory depth to descend
@@ -111,10 +110,9 @@ def walk(
     timeout_ms:int|None=None, # Cancel the walk after this long and return partial results
 ) -> PathResults:
     "Walk a directory and return absolute file and/or directory Paths."
-    rt = Path(root).expanduser().absolute()
-    paths, timed_out = _core.walk(rt, hidden, ignore, max_depth, min_depth, max_filesize, follow_links,
-        same_file_system, path_re, skip_path_re, _listify(skip_dir), skip_dir_re, files, dirs, timeout_ms)
-    return _mk_results(PathResults, paths, False, timed_out, root=_path_base(rt, follow_links))
+    return _find(root, None, files, dirs, timeout_ms, hidden=hidden, ignore=ignore, max_depth=max_depth, min_depth=min_depth,
+        max_filesize=max_filesize, follow_links=follow_links, same_file_system=same_file_system, path_re=path_re, skip_path_re=skip_path_re,
+        skip_dir=skip_dir, skip_dir_re=skip_dir_re)
 
 
 def _walk_args(
@@ -134,14 +132,26 @@ def _walk_args(
     skip_dir:str|list|None=None, # Directory glob or globs to prune
     skip_dir_re:str|None=None, # Directory regex used to prune traversal
 ):
-    "Walk/filter positional tail for `_core` calls; delegators pass their `**kwargs` here whole"
+    "`_core` walk options from the shared walk parameters. Delegators pass their `**kwargs` here whole."
     include, exclude, exts = _filters(glob, include, exclude, ext)
-    return (include, exclude, exts, hidden, ignore, max_depth, min_depth, max_filesize,
-        follow_links, same_file_system, path_re, skip_path_re, _listify(skip_dir), skip_dir_re)
+    return dict(includes=include, excludes=exclude, exts=exts, hidden=hidden, ignore=ignore, max_depth=max_depth, min_depth=min_depth,
+        max_filesize=max_filesize, follow_links=follow_links, same_file_system=same_file_system, path_re=path_re, skip_path_re=skip_path_re,
+        skip_dirs=_listify(skip_dir), skip_dir_re=skip_dir_re)
+
+def _walk(root, **kwargs):
+    "`_core` walk options for `root`, which is one path or an iterable of paths, and the shared walk parameters"
+    roots = [root] if isinstance(root, (str, PathLike)) else root
+    return dict(roots=[Path(r).expanduser() for r in roots], **_walk_args(**kwargs))
+
+def _find(root, pattern=None, files=True, dirs=False, timeout_ms=None, show_target=False, root_links=False, **kwargs):
+    "Collected `_core.find` results as `PathResults`. `root_links` walks a root link to a directory, as `ls` does."
+    w = _walk(root, **kwargs)
+    paths, timed_out = _core.find(w, pattern, files, dirs, timeout_ms, root_links)
+    return _mk_results(PathResults, paths, False, timed_out, root=_core.walk_base(w, False, root_links), show_target=show_target)
 
 @delegates(_walk_args)
 def fd(
-    root:str|Path=".", # Directory or file to walk (expands `~`)
+    root:str|Path|list=".", # Directory or file to walk, or a list of them (expands `~`)
     pattern:str|None=None, # Smart-case regex matched against each basename
     files:bool=True, # Include files in results
     dirs:bool=False, # Include directories in results
@@ -150,28 +160,26 @@ def fd(
     **kwargs
 ) -> PathResults:
     "Find absolute Paths with fd-style filters and gitignore support."
-    rt = Path(root).expanduser().absolute()
-    paths, timed_out = _core.find(rt, pattern, *_walk_args(**kwargs), files, dirs, timeout_ms)
-    return _mk_results(PathResults, paths, False, timed_out, root=_path_base(rt, kwargs.get('follow_links', False)), show_target=show_target)
+    return _find(root, pattern, files, dirs, timeout_ms, show_target, **kwargs)
 
 
 @delegates(_walk_args)
 def fd_iter(
-    root:str|Path=".", # Directory or file to walk (expands `~`)
+    root:str|Path|list=".", # Directory or file to walk, or a list of them (expands `~`)
     pattern:str|None=None, # Smart-case regex matched against each basename
     files:bool=True, # Include files in results
     dirs:bool=False, # Include directories in results
     **kwargs
 ):
     "Walk lazily, yielding absolute Paths; early exit stops the walk."
-    rt = Path(root).expanduser().absolute()
-    base = _path_base(rt, kwargs.get('follow_links', False))
-    return (base/p for p in _core.find_iter(rt, pattern, *_walk_args(**kwargs), files, dirs))
+    w = _walk(root, **kwargs)
+    base = _core.walk_base(w, False, False)
+    return (base/p for p in _core.find_iter(w, pattern, files, dirs))
 
 
 @delegates(fd)
 def ls(
-    root:str|Path=".", # Directory or file to list (expands `~`)
+    root:str|Path|list=".", # Directory or file to list, or a list of them (expands `~`)
     pattern:str|None=None, # Smart-case regex matched against each basename
     hidden:bool=False, # Include hidden files and directories, like `ls -a`
     dirs:bool=True, # Include directories in results
@@ -179,8 +187,8 @@ def ls(
     ignore:bool=False, # Respect `.gitignore` and other ignore files
     **kwargs
 ) -> PathResults:
-    "List a directory like `ls`: one level, directories included, ignore rules off, sorted by name."
-    res = fd(root, pattern, hidden=hidden, dirs=dirs, max_depth=max_depth, ignore=ignore, **kwargs)
+    "List a directory like `ls`: one level, directories included, ignore rules off, sorted by name. A root link to a directory lists that directory, with paths under the link."
+    res = _find(root, pattern, dirs=dirs, root_links=True, hidden=hidden, max_depth=max_depth, ignore=ignore, **kwargs)
     res.sort()
     return res
 
@@ -203,22 +211,23 @@ async def _acall(fn, *args):
 
 @delegates(fd)
 async def fda(
-    root:str|Path=".", # Directory or file to walk (expands `~`)
+    root:str|Path|list=".", # Directory or file to walk, or a list of them (expands `~`)
     pattern:str|None=None, # Smart-case regex matched against each basename
     files:bool=True, # Include files in results
     dirs:bool=False, # Include directories in results
     timeout_ms:int|None=None, # Cancel the walk after this long and return partial results
+    show_target:bool=False, # Append `-> target` to symlink rows in the display
     **kwargs
 ) -> PathResults:
     "Async `fd`: find paths on Rust threads without blocking the event loop."
-    rt = Path(root).expanduser().absolute()
-    paths, timed_out = await _acall(_core.find_async, rt, pattern, *_walk_args(**kwargs), files, dirs, timeout_ms)
-    return _mk_results(PathResults, paths, False, timed_out, root=_path_base(rt, kwargs.get('follow_links', False)))
+    w = _walk(root, **kwargs)
+    paths, timed_out = await _acall(_core.find_async, w, pattern, files, dirs, timeout_ms)
+    return _mk_results(PathResults, paths, False, timed_out, root=_core.walk_base(w, False, False), show_target=show_target)
 
 
 @delegates(_walk_args)
 async def fda_iter(
-    root:str|Path=".", # Directory or file to walk (expands `~`)
+    root:str|Path|list=".", # Directory or file to walk, or a list of them (expands `~`)
     pattern:str|None=None, # Smart-case regex matched against each basename
     files:bool=True, # Include files in results
     dirs:bool=False, # Include directories in results
@@ -226,10 +235,9 @@ async def fda_iter(
     **kwargs
 ):
     "Async `fd_iter`: yield absolute Paths; early exit stops the walk."
-    rt = Path(root).expanduser().absolute()
-    base = _path_base(rt, kwargs.get('follow_links', False))
-    async with aclosing(_abatches(_core.find_iter_async, batch_max, rt, pattern,
-        *_walk_args(**kwargs), files, dirs)) as batches:
+    w = _walk(root, **kwargs)
+    base = _core.walk_base(w, False, False)
+    async with aclosing(_abatches(_core.find_iter_async, batch_max, w, pattern, files, dirs)) as batches:
         async for paths in batches:
             for p in paths: yield base/p
 
@@ -258,7 +266,7 @@ def _mk_results(cls, items, capped, timed_out, **kwargs):
     return res
 
 
-def _paths_reduce(rows, root, max_results, timed_out=False):
+def _paths_reduce(rows, w, max_results, timed_out=False):
     "Unique matched paths as `PathResults` from rows with `kind`/`path`, capped at `max_results`"
     seen,res,capped = set(),[],False
     for row in rows:
@@ -268,20 +276,20 @@ def _paths_reduce(rows, root, max_results, timed_out=False):
             break
         seen.add(row.path)
         res.append(row.path)
-    return _mk_results(PathResults, res, capped, timed_out, root=_path_base(Path(root).resolve()))
+    return _mk_results(PathResults, res, capped, timed_out, root=_core.walk_base(w, True, False))
 
-def _rg_post(rows, paths, count, max_results, timed_out, root):
+def _rg_post(rows, paths, count, max_results, timed_out, w):
     "Reduce collected rows to the requested `rg`/`rga` result form"
     if count: return sum(len(r.matches) for r in rows if r.kind == "match")
     if not paths: return _mk_results(SearchResults, *_cap_rows(rows, max_results), timed_out)
-    return _paths_reduce(rows, root, max_results, timed_out)
+    return _paths_reduce(rows, w, max_results, timed_out)
 
 
 
 @delegates(_walk_args)
 def rg(
     pattern:str, # Regex pattern to search for
-    root:str|Path=".", # Directory or file to search (expands `~`)
+    root:str|Path|list=".", # Directory or file to search, or a list of them (expands `~`)
     case_sensitive:bool|None=None, # True/False forces case; None allows `smart_case`
     smart_case:bool=False, # Match `rg --smart-case` behavior
     before_context:int=0, # Lines of context before each match, like `rg -B`
@@ -296,28 +304,34 @@ def rg(
     maxlen:int=MAXLEN, # Maximum source characters per displayed block
     **kwargs
 ):
-    "Search files and return `SearchResults`, matched paths, or a count; `lnhashs=True` shows exhash-style addresses."
+    """Search files and return `SearchResults`, matched paths, or a count; `lnhashs=True` shows exhash-style addresses.
+
+    `summary=True` returns one `SearchBlock` per block of lines separated by blank or whitespace-only lines, however many matches
+    it holds, and `context` then counts blocks. Summary mode can't combine with `paths` or `count`, and with `lnhashs=True` shows
+    each block's boundary addresses. `^` and `$` anchor each line, and a line ends at LF or CRLF. Patterns containing a newline or
+    carriage return are rejected. Row `path` fields are labels relative to the root, or to the common ancestor of several roots.
+    Each row has `asdict()`. A symlink named as `root` is followed."""
     assert not (paths and count), "paths and count are mutually exclusive"
     assert not (count and max_results), "count and max_results are mutually exclusive"
     assert not (count and timeout_ms is not None), "count and timeout_ms are mutually exclusive"
     assert not (summary and count), "summary and count are mutually exclusive"
     assert not (summary and paths), "summary and paths are mutually exclusive"
     before_context, after_context = _context(context, before_context, after_context)
-    rt = _fs_path(root)
-    args = (pattern, rt, *_walk_args(**kwargs), case_sensitive, smart_case, before_context, after_context)
+    w = _walk(root, **kwargs)
+    args = (w, pattern, case_sensitive, smart_case, before_context, after_context)
     if summary:
         rows,timed_out = _core.block_search(*args, timeout_ms)
         return _block_post(rows, max_results, before_context, after_context, timed_out, maxlen, lnhashs)
     if count: return sum(len(row.matches) for row in _core.rg_iter(*args, False) if row.kind == "match")
-    if paths and timeout_ms is None: return _paths_reduce(_core.rg_iter(*args, False), rt, max_results)
+    if paths and timeout_ms is None: return _paths_reduce(_core.rg_iter(*args, False), w, max_results)
     rows, timed_out = _core.rg(*args, lnhashs, timeout_ms)
-    return _rg_post(rows, paths, False, max_results, timed_out, rt)
+    return _rg_post(rows, paths, False, max_results, timed_out, w)
 
 
 @delegates(_walk_args)
 def rg_iter(
     pattern:str, # Regex pattern to search for
-    root:str|Path=".", # Directory or file to search (expands `~`)
+    root:str|Path|list=".", # Directory or file to search, or a list of them (expands `~`)
     case_sensitive:bool|None=None, # True/False forces case; None allows `smart_case`
     smart_case:bool=False, # Match `rg --smart-case` behavior
     before_context:int=0, # Lines of context before each match, like `rg -B`
@@ -328,14 +342,13 @@ def rg_iter(
 ) -> RgIter:
     "Search files lazily, yielding `SearchLine` rows; `lnhashs=True` shows exhash-style addresses."
     before_context, after_context = _context(context, before_context, after_context)
-    return _core.rg_iter(pattern, _fs_path(root), *_walk_args(**kwargs),
-        case_sensitive, smart_case, before_context, after_context, lnhashs)
+    return _core.rg_iter(_walk(root, **kwargs), pattern, case_sensitive, smart_case, before_context, after_context, lnhashs)
 
 
 @delegates(_walk_args)
 async def rga(
     pattern:str, # Regex pattern to search for
-    root:str|Path=".", # Directory or file to search (expands `~`)
+    root:str|Path|list=".", # Directory or file to search, or a list of them (expands `~`)
     case_sensitive:bool|None=None, # True/False forces case; None allows `smart_case`
     smart_case:bool=False, # Match `rg --smart-case` behavior
     before_context:int=0, # Lines of context before each match, like `rg -B`
@@ -357,13 +370,13 @@ async def rga(
     assert not (summary and count), "summary and count are mutually exclusive"
     assert not (summary and paths), "summary and paths are mutually exclusive"
     before_context, after_context = _context(context, before_context, after_context)
-    rt = _fs_path(root)
-    args = (pattern, rt, *_walk_args(**kwargs), case_sensitive, smart_case, before_context, after_context)
+    w = _walk(root, **kwargs)
+    args = (w, pattern, case_sensitive, smart_case, before_context, after_context)
     if summary:
         rows,timed_out = await _acall(_core.block_search_async, *args, timeout_ms)
         return _block_post(rows, max_results, before_context, after_context, timed_out, maxlen, lnhashs)
     rows, timed_out = await _acall(_core.rg_async, *args, lnhashs, timeout_ms)
-    return _rg_post(rows, paths, count, max_results, timed_out, rt)
+    return _rg_post(rows, paths, count, max_results, timed_out, w)
 
 
 
@@ -387,7 +400,7 @@ async def _abatches(fn, *args):
 @delegates(_walk_args)
 async def rga_iter(
     pattern:str, # Regex pattern to search for
-    root:str|Path=".", # Directory or file to search (expands `~`)
+    root:str|Path|list=".", # Directory or file to search, or a list of them (expands `~`)
     case_sensitive:bool|None=None, # True/False forces case; None allows `smart_case`
     smart_case:bool=False, # Match `rg --smart-case` behavior
     before_context:int=0, # Lines of context before each match, like `rg -B`
@@ -399,7 +412,7 @@ async def rga_iter(
 ):
     "Async `rg_iter`: yield `SearchLine` rows as they are found; early exit cancels the search."
     before_context, after_context = _context(context, before_context, after_context)
-    async with aclosing(_abatches(_core.rg_iter_async, batch_max, pattern, _fs_path(root), *_walk_args(**kwargs),
+    async with aclosing(_abatches(_core.rg_iter_async, batch_max, _walk(root, **kwargs), pattern,
         case_sensitive, smart_case, before_context, after_context, lnhashs)) as batches:
         async for rows in batches:
             for row in rows: yield row

{rgapi-0.1.30 → rgapi-0.2.0}/python/rgapi/_cli.py

@@ -4,10 +4,10 @@ from fastcore.script import call_parse
 from . import nbrg
 
 
-@call_parse(pos=['root'])
+@call_parse
 def nbrg_cli(
     pattern:str, # Regex pattern to search for
-    root:str='.', # File or directory to search
+    *roots:str, # Files or directories to search (default `.`)
     cell_context:int=0, # Neighbouring cells to include before and after matches
     multiline:bool=False, # Allow matches across lines within a cell?
     smart_case:bool=False, # Use case-sensitive matching when the pattern contains uppercase?
@@ -23,6 +23,6 @@ def nbrg_cli(
     timeout_ms:int=None, # Stop searching after this many milliseconds
 ):
     "Search notebook cell sources and report stable cell IDs."
-    print(nbrg(pattern, root, cell_context=cell_context, multiline=multiline, smart_case=smart_case,
+    print(nbrg(pattern, roots or '.', cell_context=cell_context, multiline=multiline, smart_case=smart_case,
         case_sensitive=True if case else None, paths=paths, count=count, max_results=max_results, maxlen=maxlen,
         glob=glob, exclude=exclude, hidden=hidden, max_depth=max_depth, timeout_ms=timeout_ms))

{rgapi-0.1.30 → rgapi-0.2.0}/python/rgapi/block.py

@@ -4,7 +4,12 @@ from . import MAXLEN, _Results, _mk_results, _preview
 
 
 class SearchBlock:
-    "A blank-line-delimited source block containing a match, or context for one."
+    """A blank-line-delimited source block containing a match, or context for one.
+
+    Fields: `path`, `block_index`, `start_line`, `end_line`, `start_lnhash`, `end_lnhash`, `kind` (match or context), the full
+    `source`, and `matches` as matching `SearchLine`s. The display is `path:start-end:source`, with `-` in place of the last colon
+    on context rows. Hashed locations are `start_lnhash,end_lnhash`, or one hash for a single line. Newline runs display as ¶,
+    keeping indentation. `maxlen` limits the displayed source, not the stored `source`."""
     def __init__(self, path, block_index, start_line, end_line, start_lnhash, end_lnhash, kind, source, matches, maxlen=MAXLEN, display_lnhash=False):
         self.path,self.block_index,self.start_line,self.end_line = path,block_index,start_line,end_line
         self.start_lnhash,self.end_lnhash,self.display_lnhash = start_lnhash,end_lnhash,display_lnhash