rabbitinspect

A Python code performance analyzer written in Rust (via PyO3). It scans your Python source code and points out patterns that can be made faster, more memory-efficient, or more idiomatic — with optional automatic fixes.

Installation

pip install rabbitinspect

The package ships pre-compiled wheels — no Rust toolchain required.

Usage

CLI

# Check a single file
rabbitinspect file.py

# Check an entire directory
rabbitinspect src/

# Auto-fix detected issues
rabbitinspect file.py --fix

# Select specific checks only
rabbitinspect file.py --select RAB002,RAB003

# Ignore specific checks
rabbitinspect file.py --ignore RAB022,RAB101

# JSON output
rabbitinspect file.py --format json

# Disable colored output
rabbitinspect file.py --no-color

Output (ruff-style):

file.py:10:5: RAB002 Use 'is' instead of '==' for None comparison
file.py:25:8: RAB003 Use 'not x' instead of 'len(x) == 0' for emptiness check

Available commands

Suppressing checks

Inline with # noqa:

x = 42  # noqa: RAB067
try:
    pass
except:
    pass  # noqa: RAB012, RAB013

Or globally in pyproject.toml:

[tool.rabbitinspect]
select = ["RAB002", "RAB003", "RAB006"]
ignore = ["RAB022", "RAB101"]

x = 42  # noqa: RAB067
try:
    pass
except:
    pass  # noqa: RAB012, RAB013

Configuration via pyproject.toml

[tool.rabbitinspect]
select = ["RAB002", "RAB003", "RAB006"]
ignore = ["RAB022", "RAB101"]
only-categories = ["correctness", "performance"]
ignore-categories = ["style", "complexity"]

Python API

from rabbitinspect import analyze_code, apply_fixes

source = """
def foo(x):
    if x == None:
        return True
    return False
"""

findings = analyze_code(source)
for f in findings:
    print(f"{f['code']}:{f['line']}:{f['col']} {f['message']}")

# Apply fixes
fixes = [f['fix'] for f in findings if f.get('fix')]
fixed = apply_fixes(source, fixes)

Rule Categories

Rules are grouped into categories so you can enable or disable related checks together:

Use --only-category to run only checks in specific categories, or --ignore-category to skip entire categories:

# Only show correctness and performance issues
rabbitinspect src/ --only-category correctness,performance

# Skip style and complexity checks
rabbitinspect src/ --ignore-category style,complexity

Checks

correctness — Potential bugs and correctness issues

performance — Performance improvements

style — Code style and conventions

typesafety — Type annotation rules

complexity — Code complexity metrics

import — Import-related rules

unused — Unused variables and imports

Runtime profiler (2.0 preview)

Beyond static analysis, rabbitinspect ships a sampling runtime profiler written in Rust. A background thread snapshots the Python stack via sys._current_frames() (robust across CPython 3.10–3.14) and samples resident memory, with near-zero changes to your code. On stop it writes a self-contained HTML report.

# Profile a script and write an HTML report
rabbitinspect perf run myscript.py --out report.html

# Also export an interactive flamegraph for https://speedscope.app
rabbitinspect perf run myscript.py --speedscope profile.speedscope.json

# Attach to an already-running process — no code changes, no restart (Linux)
rabbitinspect perf attach --pid 12345 --duration 5 --out report.html

# ...and cut through framework/idle noise — show only your own code
rabbitinspect perf attach --pid 12345 --duration 5 --app-root /path/to/project --out report.html

# Compare two runs (before / after an optimization) — diff has a differential flamegraph
rabbitinspect perf run myscript.py --json before.json
# … make your change …
rabbitinspect perf run myscript.py --json after.json
rabbitinspect perf diff before.json after.json --out diff.html

# Other run outputs: per-function CSV, speedscope JSON
rabbitinspect perf run myscript.py --csv functions.csv --speedscope profile.json

# Sample several forked workers at once (gunicorn) and merge them
rabbitinspect perf attach --pid 12345 --also-pid 12346 --also-pid 12347 --duration 10 --out report.html

The report includes:

• Top functions by self/total time, an interactive flamegraph (click to zoom), and a memory-over-time chart.
• Flame chart (time order) + call timings: each call shown separately along a time axis (a function called twice appears twice); hover for the call's duration. The table gives calls / total / avg / max ms per function.
• Per-line breakdown: click a function in the report to expand its self-time line by line, with the source text — pinpoints which statement spent the time.
• Per-function memory (perf run --memory): live allocations attributed to functions via tracemalloc.
• On-CPU vs off-CPU split (attach mode): how much self time was real CPU work vs waiting on sleep / I/O / locks.
• Per-endpoint flamegraphs: a flamegraph per route, from the samples taken while that endpoint was serving (web middleware installed).
• Request timeline + per-endpoint p50/p95/p99.
• Database section: slowest queries with the app line that issued each query, and N+1 detection (repeated query shapes within one request).
• Hotspots with lint findings: the hottest functions cross-referenced against rabbitinspect's own static rules — the static perf rules pointed straight at the code that dominates runtime.
• Report UX: a sticky section nav (jump links + back-to-top), sortable function tables (click a column header), a function search box (/ to focus, Esc to clear), a "my code" toggle that hides stdlib/dependency rows, a dark-mode toggle, a run metadata sub-header (Python version, platform, timestamp, sampling interval), and a one-click functions.csv download.

Exact per-line timing (@line_profile)

The sampler can't see lines that run in microseconds. For a function you can edit, @line_profile times every line exactly via tracing (high overhead — opt-in):

from rabbitinspect.perf import line_profile, line_profile_html

@line_profile
def handler(req):
    rows = db.query(...)        # time on this line includes the call it makes
    return render(rows)

handler(req)
open('lines.html', 'w').write(line_profile_html(handler))

Dump a running process on demand

Profile a long-running server and grab a report whenever you want — no stop, no restart:

from rabbitinspect.perf import install_dump_handler
install_dump_handler(out='dump.html')   # writes dump.html on SIGUSR1

kill -USR1 <pid>     # → dump.html

Async (asyncio)

The CPU sampler only sees threads that are running Python, so await-ing coroutines are invisible to it. profile_asyncio samples the event loop's tasks directly — its flamegraph shows where coroutines are parked on await.

from rabbitinspect.perf import profile_asyncio

async def main():
    await do_async_work()

result = profile_asyncio(main)        # runs main() and samples awaiting tasks
open('async.html', 'w').write(result.to_html())

Web frameworks

Drop-in middleware records one span per request (method, route, status, duration). Both are no-ops when the profiler is off, so they are safe to leave installed.

# Django (wsgi.py)
from rabbitinspect.perf_web import WSGIProfilerMiddleware
application = WSGIProfilerMiddleware(application)

# FastAPI / Starlette
from rabbitinspect.perf_web import ASGIProfilerMiddleware
app.add_middleware(ASGIProfilerMiddleware)

# Auto-capture a report for any request slower than 1s:
application = WSGIProfilerMiddleware(application, slow_request_ms=1000, dump_dir='slow/')

For forked workers (gunicorn/uvicorn), call enable_fork_profiling() in the parent so each worker gets its own live sampler (OS threads don't survive fork()). It stops the sampler around each fork() so the fork is single-threaded (no deadlock hazard).

Database queries

from rabbitinspect.perf_db import instrument_sqlalchemy, instrument_django, query_timer

instrument_sqlalchemy(engine)   # SQLAlchemy
instrument_django()             # Django (call once at startup)

with query_timer('SELECT ...'):  # generic
    cursor.execute('SELECT ...')

Each query is tagged with the application line that issued it (file:line), so the slowest queries and N+1 groups point straight at your code.

Timings are statistical (sampling), not exact per-call. Attach mode is Linux-only and supports CPython 3.13+ (validated on 3.13 and 3.14; 3.11/3.12 predate CPython's remote-debug offsets). Per-function memory attribution is on the roadmap.

Performance rationale

Why Rust?

Parsing and analyzing Python source is a CPU-bound operation. Rust's zero-cost abstractions and lack of a garbage collector make it ideal for this kind of static analysis. The core engine uses rustpython-parser to build a full AST and walks it with pattern matching — all without any Python overhead at analysis time.

Specific improvements

Development

# Setup
git clone https://github.com/rroblf01/rabbitinspect
cd rabbitinspect

# Build the Rust extension (requires Rust toolchain)
cargo build --release
cp target/release/librabbitinspect.so python/rabbitinspect/_core.cpython-314-x86_64-linux-gnu.so

# Run tests
uv run pytest tests/

# Build distributable wheels
uv run maturin build

License

MIT