gerenuk

Symbol-level Python code intelligence, powered by ty-find.

tyf answers questions about one symbol at a time. gerenuk asks those questions for every symbol in a file and reports what stands out:

$ gerenuk audit sample_pkg/service.py
warn  sample_pkg/service.py:43  func `legacy_export` has no references
note  sample_pkg/service.py:34  method `ShelterService.seniors` is referenced only from tests (1)

1 file(s), 7 symbol(s) checked — 1 warn, 1 note

Grep tells you whether a name appears. gerenuk asks ty's type checker whether it is actually referenced — so docstrings, comments and same-named symbols in other modules do not count.

📖 Documentation · 🤖 llms.txt

Install

Prerequisite: ty-find and ty.

uv add --dev ty ty-find gerenuk

If ty is not on PATH, tyf falls back to uvx ty, so having uv is enough.

Verify the setup:

gerenuk doctor

Usage

gerenuk audit pkg/module.py            # human output
gerenuk audit --format json pkg/*.py   # machine-readable
gerenuk audit --workspace ../other pkg/module.py
Severity Rule
warn The symbol has no references anywhere
note Every reference lives in a test file

Only callable symbols are audited; _private and dunder names are skipped.

Exit code Meaning
0 Nothing flagged
1 Findings reported
2 The run could not complete (tyf missing, bad workspace, …)

The split between 1 and 2 is what makes it usable in CI: a failing check and a broken setup are different problems.

changed-symbols

Maps the working tree's diff to the Python symbols it changed — the first stage of impact-based test selection. It needs only git; no tyf, no ty, no Python environment.

$ gerenuk changed-symbols
base main (merge-base 5ddda1f)

changed symbols (2)
  modified  method    mypkg.pipelines.enrich:Enricher.run  src/mypkg/pipelines/enrich.py
  added     function  mypkg.utils:parse_date               src/mypkg/utils.py

module-level changes (1)
  mypkg.pipelines.enrich

--base defaults to the first of origin/main, main, master that exists; the diff runs from merge-base(HEAD, base) to the working tree, staged and unstaged alike. --format json emits the same data for scripting. Registry decorators can be filtered out via [tool.gerenuk] ignore-decorators in pyproject.toml. See the documentation.

Caveat

gerenuk reports static references. Dynamic dispatch, plugin registries, getattr lookups and __all__ re-exports are invisible to it. Findings are leads to confirm with tyf refs <symbol>, not a delete list.

Usage with Claude Code

Add this to your project's CLAUDE.md:

### Dead-symbol checks — `gerenuk`

This project has `gerenuk` — a symbol-level auditor built on `tyf` (ty-find).
Run it before deleting Python code, and after a refactor.

- `gerenuk audit pkg/module.py` — flag symbols nothing references, and symbols
  only tests reach
- `gerenuk audit --format json pkg/*.py` — same, machine-readable
- `gerenuk doctor` — check that `tyf` and the workspace resolve

Exit codes: `0` clean, `1` findings reported, `2` the run could not complete.

Findings are signals, not verdicts: dynamic dispatch, plugin registries, and
`__all__` re-exports can hide a real usage. Confirm with `tyf refs <symbol>`
before deleting anything.

Development

make review        # fmt + clippy + rust tests + fixture pytest + audit + deny
make review-quick  # skip the network checks
make docs          # build the mdBook site and llms.txt into docs/book/html

The test suite is hermetic: tests/common/mod.rs stubs tyf with a shell script and points GERENUK_TYF at it, so neither tyf nor ty is needed to run cargo test. See docs/dev/ARCHITECTURE.md.

License

MIT

Project links

Data verified by PyPI on Aug 29, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for mojzis from gravatar.com mojzis

Credits

Author: mojzis

GitHub Statistics

Data verified by PyPI on Aug 29, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

dev

Tags

python lsp symbols static-analysis rust

Classifiers

Report project as malware

Download files

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

Source Distribution

gerenuk-0.1.0.tar.gz (892.2 kB view details)

Uploaded Source

Built Distributions

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

gerenuk-0.1.0-py3-none-win_amd64.whl (995.5 kB view details)

Uploaded Python 3Windows x86-64

gerenuk-0.1.0-py3-none-manylinux_2_28_x86_64.whl (1.1 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

gerenuk-0.1.0-py3-none-macosx_11_0_arm64.whl (971.8 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file gerenuk-0.1.0.tar.gz.

File metadata

  • Download URL: gerenuk-0.1.0.tar.gz
  • Upload date:
  • Size: 892.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gerenuk-0.1.0.tar.gz
Algorithm Hash digest
SHA256 b238191546de4a4b38ab1e78729a05ff68db774f49693865a7d34762722d2ebd
MD5 d97cd43034ae636fd313355514c64b2e
BLAKE2b-256 eae3b97d33513251f5c5c8eddefa98c8ff04670def99d0fd0fc1399071642e57

See more details on using hashes here.

Provenance

The following attestation bundles were made for gerenuk-0.1.0.tar.gz:

Publisher: release.yml on mojzis/gerenuk

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

File details

Details for the file gerenuk-0.1.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: gerenuk-0.1.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 995.5 kB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gerenuk-0.1.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 411a100d4a9081925eced2aaacd02b04e1e0ff2240501b5a2401241a5fe00451
MD5 5005caa30ad8634c1b592d2e352ed6a0
BLAKE2b-256 01adca9e63b787f78058602e49ac8dbb383db1cc79e0425bfc71c37a66ea553a

See more details on using hashes here.

Provenance

The following attestation bundles were made for gerenuk-0.1.0-py3-none-win_amd64.whl:

Publisher: release.yml on mojzis/gerenuk

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

File details

Details for the file gerenuk-0.1.0-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for gerenuk-0.1.0-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f4d5137ef77a7e80474b3a96ac81465da1e4fde200ff7f6ddf1965b10c8a934b
MD5 c3e9c9323ac78d38bca04f5867aea28f
BLAKE2b-256 319e6bd102a75aaf2ffc4d0e913f65f89290441e119284d8989a5c73296bc374

See more details on using hashes here.

Provenance

The following attestation bundles were made for gerenuk-0.1.0-py3-none-manylinux_2_28_x86_64.whl:

Publisher: release.yml on mojzis/gerenuk

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

File details

Details for the file gerenuk-0.1.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gerenuk-0.1.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 065566d9f56c646b8342bb1bbb1cd5c07376160ae7ddf05c854ee273ce22b684
MD5 30efb07880824a419cea51b4c52c2061
BLAKE2b-256 7afbebc5832b9047bb30225f0f49fab1b720087a292a2027dc0fa7fa34f785f0

See more details on using hashes here.

Provenance

The following attestation bundles were made for gerenuk-0.1.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on mojzis/gerenuk

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

Release history Release notifications | RSS feed

0.3.1

4 files

0.3.0

4 files

0.2.0

4 files

This release

0.1.0 This release

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page