rgapi 0.1.23__tar.gz → 0.1.25__tar.gz

{rgapi-0.1.23 → rgapi-0.1.25}/.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
       - uses: actions/checkout@v7
       - uses: PyO3/maturin-action@v1
         with:
-          args: --release --out dist -i python3.10 -i python3.11 -i python3.12 -i python3.13
+          args: --profile dist --out dist -i python3.10 -i python3.11 -i python3.12 -i python3.13
           manylinux: auto
       - uses: actions/upload-artifact@v7
         with:

{rgapi-0.1.23 → rgapi-0.1.25}/Cargo.lock

@@ -28,6 +28,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "core_detect"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48"
+
 [[package]]
 name = "crc32fast"
 version = "1.5.1"
@@ -39,9 +45,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-deque"
-version = "0.8.7"
+version = "0.8.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+checksum = "622f3fc73690be383c7214310406f28a90e6edeadc3cea882f9d71e495b9711a"
 dependencies = [
  "crossbeam-epoch",
  "crossbeam-utils",
@@ -49,26 +55,32 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.20"
+version = "0.9.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d"
 dependencies = [
  "crossbeam-utils",
 ]
 
 [[package]]
 name = "crossbeam-utils"
-version = "0.8.22"
+version = "0.8.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
 
 [[package]]
 name = "encoding_rs"
-version = "0.8.35"
+version = "0.8.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+checksum = "2a7a45518d2863d18aa47f4a0cf9faec2aa4304cc09df5e41299f276b3ad135e"
 dependencies = [
  "cfg-if",
+ "core_detect",
+ "multiversion",
+ "multiversion_no_op",
+ "rustversion",
+ "scopeguard",
+ "simdutf8",
 ]
 
 [[package]]
@@ -185,6 +197,34 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "multiversion"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7edb7f0ff51249dfda9ab96b5823695e15a052dc15074c9dbf3d118afaf2c201"
+dependencies = [
+ "multiversion-macros",
+ "target-features",
+]
+
+[[package]]
+name = "multiversion-macros"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b093064383341eb3271f42e381cb8f10a01459478446953953c75d24bd339fc0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "target-features",
+]
+
+[[package]]
+name = "multiversion_no_op"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d"
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -291,7 +331,7 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rgapi"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "crc32fast",
  "globset",
@@ -304,6 +344,12 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -313,6 +359,12 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
 [[package]]
 name = "serde"
 version = "1.0.229"
@@ -340,7 +392,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.4",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -356,6 +408,12 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
 [[package]]
 name = "syn"
 version = "2.0.119"
@@ -369,15 +427,21 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.4"
+version = "3.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
 dependencies = [
  "proc-macro2",
  "quote",
  "unicode-ident",
 ]
 
+[[package]]
+name = "target-features"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c1bbb9f3c5c463a01705937a24fdabc5047929ac764b2d5b9cf681c1f5041ed5"
+
 [[package]]
 name = "target-lexicon"
 version = "0.13.5"

{rgapi-0.1.23 → rgapi-0.1.25}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rgapi"
-version = "0.1.23"
+version = "0.1.25"
 edition = "2024"
 rust-version = "1.91"
 license = "Apache-2.0"
@@ -33,4 +33,18 @@ extension-module = ["python", "pyo3/extension-module"]
 too_many_arguments = "allow"
 
 [profile.release]
+lto = false
+codegen-units = 16
+
+[profile.release.package.rgapi]
+incremental = true
+
+[profile.dist]
+inherits = "release"
+lto = true
+incremental = false
+codegen-units = 1
 strip = true
+
+[profile.dist.package.rgapi]
+incremental = false

{rgapi-0.1.23 → rgapi-0.1.25}/DEV.md

@@ -9,7 +9,7 @@ src/walk.rs       ignore/globset/grep-regex-backed path walking and filtering
 src/search.rs     grep-regex/grep-searcher-backed searching
 src/block.rs      blank-line-delimited block grouping, matching, and block context
 src/python.rs     PyO3 classes and private core functions
-python/rgapi/     public Python wrappers over `rgapi._core`
+python/rgapi/     public Python wrappers over `rgapi._core`, plus the `rgapi-nbrg` CLI
 tests/            pytest coverage for the Python API
 ```
 
@@ -40,8 +40,7 @@ The GitHub workflow builds wheels for Python 3.10-3.13 on Linux and macOS and pu
 
 Paths in `fd`, `walk`, `rg`, and `rg_iter` results are relative to the requested root and use `/` 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 16 bits of CRC-32 over the line's UTF-8 bytes); `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, symlink, filesystem, hidden, and ignore options are direct `ignore::WalkBuilder` settings. `rg_iter` exposes the same parallel search stream that `rg` collects by default; `paths=True` and `count=True` consume that stream with different reducers. Binary files and invalid UTF-8 are skipped for now.
 
-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 = String`, 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.
+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 = String`, 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.
 
 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.
 
@@ -49,4 +48,6 @@ Truncation is recorded on collected results: `max_results` sets `stop_reason="ma
 
 Path results are `FileEntry` rows: a `str` subclass carrying the walk root, so paths stay plain strings for compatibility while stat info loads lazily (one cached `os.lstat` per entry, read only on attribute access). The wrapping happens at result construction on the Python side; Rust still streams plain strings. `PathResults.__repr__` shows an `ls -l`-style listing capped at `MAX_REPR` rows, so a huge result never stats everything, while `str()` stays one plain path per line. `ls` is `fd` with shell-style defaults (one level, dirs, ignore rules off), re-sorted with `stop_reason` preserved.
 
+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.
+
 This package intentionally has no CLI. Python is the interface.

rgapi-0.1.25/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: rgapi
+Version: 0.1.25
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: fastcore>=1.14.6
+Requires-Dist: fastship>=0.0.12 ; extra == 'dev'
+Requires-Dist: maturin>=1.0,<2.0 ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Python API for ripgrep-style file walking and searching
+Home-Page: https://github.com/AnswerDotAI/rgapi
+Author-email: Jeremy Howard <j@fast.ai>
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/AnswerDotAI/rgapi
+Project-URL: Issues, https://github.com/AnswerDotAI/rgapi/issues
+Project-URL: Repository, https://github.com/AnswerDotAI/rgapi
+
+# rgapi
+
+`rgapi` provides `fd`-style file discovery and `rg`-style text search from Python without starting a shell command.
+
+It uses the same `ignore`, `grep-regex`, and `grep-searcher` crates that ripgrep uses for walking, regex matching, and file scanning. Walking and searching run in parallel by default. Most expensive work stays in Rust.
+
+## Overview
+
+For common file discovery and search:
+
+```python
+from rgapi import fd, ls, rg, rg_iter
+
+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)
+```
+
+For cell-aware search of Jupyter notebooks (see [Notebooks](#notebooks)):
+
+```python
+from rgapi import nbrg
+
+nbrg("read_csv", ".", cell_context=1)
+```
+
+Walk and search functions have async versions. Streaming versions yield results as the search finds them. See [Async](#async):
+
+```python
+from rgapi import fda, rga, rga_iter, nbrga, nbrga_iter
+
+await rga("TODO", ".", ext="py", timeout_ms=200)
+async for row in rga_iter("TODO", "."): print(row)
+```
+
+Use the lower-level functions to compile a regex, search text or a single file, or walk a directory:
+
+```python
+from rgapi import compile, search_path, search_text, walk
+
+matcher = compile("TODO")
+matcher.is_match("TODO")
+matcher.finditer("TODO TODO")
+
+walk(".")
+search_text(matcher, "alpha\nTODO\nomega\n", path="memory.txt", context=1)
+search_path(matcher, "src/lib.rs", display_path="src/lib.rs")
+```
+
+## Install
+
+```bash
+pip install rgapi
+```
+
+## File discovery
+
+`fd` and `walk` return slash-separated paths relative to `root`. Pass `root` as a `str` or `pathlib.Path`. The sync and async APIs expand `~` and accept `.`, `./`, and paths containing `..`.
+
+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`.
+
+Hidden files are skipped unless `hidden=True`. Symlinks are followed only with `follow_links=True`. Use `same_file_system=True` to avoid crossing filesystem boundaries.
+
+Traversal runs in parallel without guaranteed result order. Use `sorted(...)` when order matters.
+
+`fd` adds filename filters to `walk`. Its `pattern` is a smart-case regex matched against each basename. Lowercase patterns match case-insensitively. A pattern containing uppercase letters is case-sensitive. Use `path_re` to match the slash-separated relative path instead.
+
+`include` and `exclude` use glob syntax. `glob=` is an alias for `include=`. A basename glob such as `*.py` also matches nested paths such as `src/app.py`.
+
+Filter extensions with `ext="py"` or `ext=["py", "rs"]`. Extension and glob filters must both match. For example, `include="src/*", ext="py"` requires `src/*` and `*.py`, like combining `rg -g` with `-t`.
+
+Set `min_depth` and `max_depth` to bound recursion. `max_filesize` skips files above a byte limit.
+
+`ls` follows the shell command's listing conventions. It uses `fd` with `max_depth=1`, includes directories, disables ignore rules, and sorts by name. Set `hidden=True` for `ls -a` behaviour. All `fd` filters remain available.
+
+`fd_iter` yields `FileEntry` paths as the walk finds them. It accepts every `fd` filter. Stopping iteration ends the walk. It does not accept `timeout_ms`.
+
+`path_re` and `skip_path_re` filter slash-separated relative paths using regexes. They select returned paths or searched files without changing traversal. To skip entire subtrees, use `skip_dir` with a glob or `skip_dir_re` with a regex.
+
+## Text search
+
+`rg` and `rg_iter` return structured `SearchLine` rows. They accept the same filters as `fd`: `include`, `exclude`, `glob`, `ext`, `path_re`, `skip_path_re`, `skip_dir`, `skip_dir_re`, `min_depth`, `max_depth`, `max_filesize`, `follow_links`, and `same_file_system`.
+
+Search is case-sensitive by default, matching `rg`. Use `smart_case=True` for `rg --smart-case` behaviour. Use `case_sensitive=False` to force case-insensitive matching.
+
+Each `SearchLine` has these fields:
+
+```text
+kind         'match', 'before', 'after', or 'context'
+path         path relative to root
+line_number  1-based line number
+lnhash       exhash-style `lineno|hash|` address for the line
+line         line text without the trailing newline
+matches      list of (start, end) byte offsets for match rows
+```
+
+`rg`, `search_text`, and `search_path` return `SearchResults` by default. This list subclass displays as rg-style multiline text in `str()` and notebook pretty output. `rg_iter` yields rows lazily.
+
+`SearchLine` has a structured `repr` and an rg-style `str`. The string display truncates `line` to 180 characters with a trailing `…`. `repr` and `asdict()` retain the full line. `SearchLine.asdict()` returns the fields as a plain Python dictionary.
+
+Pass `lnhashs=True` to `rg` or `rg_iter` to display hash addresses instead of line numbers. The `line_number` field remains available.
+
+For other result forms, use `rg(..., paths=True)` to return unique matched paths or `rg(..., count=True)` to count match spans. `paths` and `count` cannot both be set.
+
+### Path results
+
+`fd`, `walk`, and `ls` return `PathResults`. So do `rg` and `nbrg` with `paths=True`. This is a list of `FileEntry` rows.
+
+A `FileEntry` is a `str` subclass containing a relative path. Its `stat` property calls `os.lstat` on first access and caches the result. It returns `None` if the path has vanished. `size`, `mtime`, and `is_dir` use the cached stat result. The object also supports ordinary string operations.
+
+`PathResults` displays as an `ls -l`-style listing of at most `rgapi.MAX_REPR` rows. A final `… N more` line reports omitted rows. Only displayed rows need stat calls. `str()` returns one plain path per line. `list(res)` also displays plain paths.
+
+### Limits and timeouts
+
+Set `timeout_ms` on `rg`, `fd`, `walk`, or `ls` to stop at a deadline and return the results collected so far. Their async versions accept it too. Results report why the operation stopped:
+
+- `stop_reason=None` means the result is complete.
+- `stop_reason="max_results"` means `max_results` truncated the result.
+- `stop_reason="timeout"` means the deadline was reached.
+
+`complete` is true exactly when `stop_reason` is `None`. `count=True` returns a plain integer without a completion flag. It cannot be combined with `timeout_ms`.
+
+### Context lines
+
+`before_context`, `after_context`, and `context` correspond to `rg -B`, `rg -A`, and `rg -C`. Files containing NUL bytes or invalid UTF-8 are skipped.
+
+### Block summaries
+
+`rg(..., summary=True)` returns one row per blank-line-delimited block instead of one row per matching line. Empty and whitespace-only lines delimit blocks. A block containing several matching lines appears once and keeps every matching `SearchLine` in `matches`.
+
+```python
+rg("TODO", ".", summary=True, context=1, maxlen=120)
+```
+
+The result is `BlockResults`, a list of `SearchBlock` objects. Each block has `path`, `block_index`, `start_line`, `end_line`, `start_lnhash`, `end_lnhash`, `kind`, full `source`, and `matches`.
+
+Matches display as `path:start-end:source`. Context displays as `path:start-end-source`. With `lnhashs=True`, the range uses copyable boundary addresses such as `path:4|a3f2|,6|b1c3|:source`. Newline runs display as `¶`. `maxlen` limits the displayed text without changing `source` or `asdict()`.
+
+In summary mode, `before_context`, `after_context`, and `context` count neighbouring blocks. `max_results` counts matching blocks and retains their context. `summary=True` cannot be combined with `paths` or `count`. It can be combined with `lnhash` for copyable block boundaries.
+
+## Notebooks
+
+`nbrg` searches cell source in Jupyter `.ipynb` files and returns matching cells. Each result identifies the cell by its nbformat cell/message id, which stays stable across edits.
+
+Plain `rg` searches escaped notebook JSON, including outputs and metadata. Its line numbers refer to that JSON file. `nbrg` searches the reconstructed cell source and identifies the cell you would edit.
+
+```python
+from rgapi import nbrg
+
+nbrg("read_csv", ".")                  # cells whose source matches, across all notebooks under "."
+nbrg("read_csv", ".", cell_context=1)  # also include neighbouring cells as context
+```
+
+Notebook discovery, parsing, and matching run together in one parallel Rust pass. Matching uses `rg`'s regex engine with the same `case_sensitive` and `smart_case` behaviour. `nbrg` accepts the discovery filters from `fd` and `rg`, including `include`, `exclude`, `glob`, `hidden`, `max_depth`, and `skip_dir`.
+
+`nbrg` returns `NbResults`, a list of `NbCell`. Each `NbCell` has:
+
+```text
+path         notebook path relative to root
+cell_index   0-based position of the cell in the notebook
+cell_id      nbformat cell id (falls back to the cell index for notebooks without ids)
+cell_type    'code', 'markdown', or 'raw'
+kind         'match' or 'context'
+source       full cell source
+matches      list of SearchLine rows for the matched lines within the cell
+```
+
+`NbCell.asdict()` returns these fields as a plain dictionary. Its `matches` field contains `SearchLine` dictionaries.
+
+`str()` and pretty display show one line per cell. Matches use `path:cell_id:source`. Context uses `path:cell_id-source`. Newline runs display as `¶`.
+
+A matching cell's display starts at its first matched line. Earlier lines are replaced by `…[Ln]`, where `n` is the matched line's one-based number within the cell. A leading `#|` directive is retained, as in `#| export…[L4]needle here`.
+
+`maxlen` limits displayed source and defaults to 120. The full source remains in `source` and `asdict()`. Each cell appears once even when it has multiple matches. All hits remain in `matches`.
+
+`cell_context=N` includes the `N` cells before and after each match as `kind="context"` rows. Context cells are deduplicated within each notebook.
+
+`nbrg_iter` yields `NbCell` rows as notebooks are parsed. For collected results, `nbrg` accepts these limits and result options:
+
+- `max_results` returns at most that many cells after sorting by path and cell index.
+- `count=True` returns the number of matching cells.
+- `timeout_ms` applies a deadline with the same `stop_reason` values as `rg`.
+
+The parser reads only each cell's `id`, `cell_type`, and `source`. It skips outputs and metadata without loading embedded images or plots. `search_nb(pattern, path, ...)` searches a single notebook file in the same way.
+
+`rgapi-nbrg` exposes notebook search without requiring a Python kernel:
+
+```bash
+rgapi-nbrg 'read_csv' .
+rgapi-nbrg 'read_csv' . --cell-context 1
+rgapi-nbrg 'read_csv' nbs --glob '*.ipynb' --max-results 20
+```
+
+Run `rgapi-nbrg --help` for its discovery, matching, and output options.
+
+## Async
+
+`fda`, `rga`, and `nbrga` are async versions of `fd`, `rg`, and `nbrg`. The async generators `fda_iter`, `rga_iter`, and `nbrga_iter` yield rows as the search finds them. Async functions accept the same arguments and return the same types as their synchronous equivalents.
+
+```python
+from rgapi import fda, rga, rga_iter
+
+await fda(".", ext="py")
+res = await rga("TODO", ".", timeout_ms=200)
+if not res.complete: print(f"partial results: {res.stop_reason}")
+async for row in rga_iter("TODO", "."): ...
+```
+
+Walking and searching use Rust threads, without `asyncio.to_thread` or the event loop's executor. A callback uses `loop.call_soon_threadsafe` to complete the awaited future or supply results to the generator's queue. The event loop remains unblocked, with normal `contextvars` behaviour.
+
+Cancellation stops the Rust workers within about one row. This includes timeouts from `asyncio.wait_for` or `asyncio.timeout`. It also includes task cancellation, such as starlette cancelling a disconnected client's request.
+
+Wrap an async iterator in `contextlib.aclosing` when leaving its loop early. `break` alone delays generator finalization until garbage collection. The context manager provides prompt cleanup:
+
+```python
+async with aclosing(rga_iter("TODO", ".")) as it:
+    async for row in it:
+        if enough(row): break
+```
+
+Use streaming results for incremental display, such as sending batches to a browser as they arrive. Collected results with `timeout_ms` return what was found before the deadline. Use `asyncio.wait_for` when a timeout should raise instead.
+
+
+## Benchmarks
+
+`tools/bench.py` compares the `rg` CLI with in-process `rgapi`. Run it against a release build. One run on this machine, using best time from seven repeats:
+
+| fixture | rg | rgapi |
+| --- | ---: | ---: |
+| 6 x 2 MB files, 2 matches | 6.54 ms | 1.44 ms |
+| 800 x 1.5 KB files, 2 matches | 13.90 ms | 10.94 ms |
+| tiny dir, repeated 30x | 5.92 ms | 2.14 ms |
+