Skip to main content

rgapi

rgapi is a Python API for ripgrep-style walking and search. It is meant for Python code that wants fd-style file discovery or rg-style searching without shelling out.

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:

from rgapi import fd, rg, rg_iter

fd(".", ext="py", exclude="test_*.py")
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):

from rgapi import nbrg

nbrg("read_csv", ".", cell_context=1)

For direct access to the regex, search, and walk pieces:

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

pip install rgapi

Semantics

fd and walk return slash-separated paths relative to root. They use the ignore crate, so .gitignore, .ignore, and the usual ripgrep filters apply by default. .rgignore files are also honored and take precedence over .gitignore. Hidden files are skipped unless hidden=True. Pass ignore=False to disable all ignore filtering (including .rgignore). Symlinks are not followed unless follow_links=True; same_file_system=True avoids crossing filesystem boundaries. Traversal is parallel, and result order is not guaranteed; use sorted(...) if order matters. root arguments accept str or pathlib.Path and expand ~; search_path also accepts path-like file paths. Display labels such as display_path are stringified without expansion.

fd adds fd-like filtering on top of walk: pattern is a substring match on the relative path, and include/exclude use glob syntax. glob= is accepted as an alias for include=. A basename glob such as *.py also matches recursively, so it finds src/app.py. Use ext="py" or ext=["py", "rs"] for extension filters, min_depth=/max_depth= to bound recursion, and max_filesize= to skip files above a byte limit.

path_re and skip_path_re are regex filters on slash-separated relative paths. They filter returned paths or searched files, but do not control traversal. skip_dir uses glob syntax to prune matching directory subtrees, and skip_dir_re does the same with regex.

rg and rg_iter return structured rows rather than raw CLI text. They accept the same 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 filters as fd. Each row is a SearchLine with:

kind         'match', 'before', 'after', or 'context'
path         path relative to root
line_number  1-based line number
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, a list subclass whose str() and notebook pretty display are rg-style multiline text. rg_iter yields rows lazily.

SearchLine has a structured repr, an rg-style str (the line is truncated to 120 chars with a trailing for display; repr and asdict() keep the full line), and SearchLine.asdict() returns row fields as a plain Python dict. rg(..., paths=True) returns unique matched paths, and rg(..., count=True) returns the total number of match spans. paths and count cannot both be set.

before_context, after_context, and context are like rg -B, rg -A, and rg -C. Files containing NUL bytes or invalid UTF-8 are skipped.

Search is case-sensitive by default, matching rg. Use smart_case=True for rg --smart-case behavior, or case_sensitive=False to force case-insensitive matching.

Notebooks

nbrg searches Jupyter .ipynb files cell-by-cell, so results are cells rather than raw JSON lines, and each match is identified by its cell id (the nbformat cell/message id) rather than a line number. Searching a notebook with plain rg matches the escaped JSON text (including outputs and metadata) and reports meaningless JSON line numbers; nbrg instead searches each cell's reconstructed source and reports the cell id, which is stable across edits and points at the actual unit you work with.

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

Notebooks are walked, parsed, and matched together in one parallel Rust pass, using the same regex engine as rg, so regex behaviour and the case_sensitive/smart_case flags match rg. Only cell source is searched, not outputs or metadata. nbrg accepts the same discovery filters as fd/rg (include, exclude, glob, hidden, max_depth, skip_dir, …).

nbrg returns NbResults, a list of NbCell. Each NbCell has:

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 those fields as a plain dict (with matches as SearchLine dicts). str()/pretty display is one truncated, newline-escaped line per cell, keyed by cell_id rather than a line number: path:cell_id:source for matches and path:cell_id-source for context cells. A cell with several matches appears once, with every hit collected in matches.

cell_context=N includes the N cells before and after each matching cell as kind="context" rows (deduplicated per notebook).

Notebook walking, parsing, and matching all happen in parallel in Rust, in the same pass as the file walk. Parsing uses a lean model that reads only each cell's id, cell_type, and source and skips outputs and metadata, so large embedded outputs (images, plots) are never materialized. search_nb(pattern, path, ...) searches a single notebook file the same way.

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rgapi-0.1.11.tar.gz (27.7 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

rgapi-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

rgapi-0.1.11-cp313-cp313-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

rgapi-0.1.11-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

rgapi-0.1.11-cp312-cp312-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

rgapi-0.1.11-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

rgapi-0.1.11-cp311-cp311-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

rgapi-0.1.11-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

rgapi-0.1.11-cp310-cp310-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file rgapi-0.1.11.tar.gz.

File metadata

  • Download URL: rgapi-0.1.11.tar.gz
  • Upload date:
  • Size: 27.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for rgapi-0.1.11.tar.gz
Algorithm Hash digest
SHA256 5863824cef614d4955c1e92a66f75a873f7da48aa6afbf5aeffaa75f450e5231
MD5 71364fa8e5b28ea54313b6a7d6b5d7fc
BLAKE2b-256 55bb6d98b1bb3f1ad5dfccbb92867ebede61e19ef56640ec22978c14dc2c2b6b

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11.tar.gz:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 78314c24509a75677351de5e5310a4e937a47b807f02c9e69697090872b65ec6
MD5 f9c36d55543eb587db0ba74a2a47ba98
BLAKE2b-256 38c7a0ebf25c605ce7cb8d96514e7d0e2495874bbc07fea30a7db35fcf23699b

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8519da2d0ead86a5a4004b2aed6d7492b59f1599cf5c898a84a9ac50499ae18f
MD5 ba37de2de19438dd1bbd71809f42845b
BLAKE2b-256 a602ccd260e285c3b49ca61d5aba528034bfd53004e3aa6829865cb1c332f59c

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 38987db1ba8ba70dd106a70526c75e15296c28aa600fef0a58eca13a5469fe98
MD5 a03f75241b814ba9605a4d41c007ff16
BLAKE2b-256 00998607e34fc65ce1d3defb416ecae208c2e8abf20f61fb77f3c0a576a4cd51

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 acdaa6477566c3572f5c0d352f4d7fba9f7ee4526f4c1a846039ac40ad01a6e9
MD5 c3786051a8b621b54bcef13a5a066db7
BLAKE2b-256 a77f65e86ad25eb90e5ba149b5828f5a18e0978e264eefb0dbfb8f68ed4f30f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ffba8d7eab792c2dd67dd3678a3eb8d02be7361c7769aaa84301e9fbabfb3ffc
MD5 2d3ae924ffc58aa1e3e6c7d5fc4f6c4c
BLAKE2b-256 bd99215b25cd017a0b30a5d7c9d3803089d8b55120427a6fe00c7f9cad7f066c

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 78b8abad88e94b3d83bbcbe808944462cfd63e84b76ef30907b40715d6ce8c05
MD5 06ce3894fd36f627364efcbb6dcdc852
BLAKE2b-256 fa8082dbaa5188853ac2251180c6af6dd8c10425af1c9e7bc360a8fd1ddb18a4

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 93d3192321f11f9fbb42846b7e620bfc7b6ec2a2a9b94decbfbab6018e2a160d
MD5 21b43199eb9bebb727d5f1586395d04c
BLAKE2b-256 57759eccadbdb96912f646b4acd7f40e9a3bcf6a3969cc36b034f34b3fe6c9c2

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rgapi-0.1.11-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rgapi-0.1.11-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c092e7ac425beb9806e454769ee8aae189c84f6c23e0f00679a2f7aeb2a80068
MD5 10ce2c8c27322ca588106c6f1ec3d523
BLAKE2b-256 051c6f1b4d05dddd89b056fb071afbc475626b5a585e7adeacedb1a2e6820651

See more details on using hashes here.

Provenance

The following attestation bundles were made for rgapi-0.1.11-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/rgapi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page