drefs 0.1.0

A hyper-fast Python docstring cross-reference checker

drefs

An extremely fast Python docstring cross-reference checker, written in Rust.

Validating cross-references in tinygrad (697 Python files). ~460x faster.

Usage

uvx drefs .

src/my_pkg/models.py:12:5: DREF001 Unresolved reference `my_pkg.old_module.Foo`
src/my_pkg/views.py:45:9: DREF001 Unresolved reference `Nonexistent`
Found 2 errors.

That's it.

Supported syntax

• MkDocs: [text][pkg.mod.Class], [pkg.mod.Class][]
• Sphinx: :class:`pkg.mod.Class`
• Rust-style: [Symbol], [`Symbol`], [pkg.mod.Class]

[User] resolves via the current file's imports. [pkg.models.User] resolves directly. Escape with \[not a ref\].

drefs understands __init__.py re-exports, inheritance chains, and self.x attributes.

Configuration

Optional. Add to pyproject.toml:

[tool.drefs]
src = ["src"]                  # auto-detected if omitted
style = "auto"                 # "mkdocs" | "sphinx" | "auto"
inventories = [                # validate against external symbols
    "https://docs.python.org/3/objects.inv",
]

Editor support

PyCharm / IntelliJ

• Ctrl+Click on each segment of a dotted path
• Syntax highlighting on cross-references
• Red squiggles on broken references

Install from editors/pycharm/build/distributions/drefs-pycharm-*.zip via Settings > Plugins > Install from Disk.

Contributing

See CONTRIBUTING.md.

License

MIT