0.5.1a0 on PyPI, experimental alpha

RefacTrail

The Python refactorizer: lint, format and refactor with verified fixes and independent Python and Rust engines.

GitHubPyPIVS Code

pip install refactrail
refactrail lint src --select E4,E7,F
Ruff's default rules: unused imports, undefined names and more
refactrail lint src --select E4,E7,F --fix
verified safe fixes, byte-identical to Ruff on the stdlib
refactrail format src --diff
the independent formatter, as a preview
refactrail check src
naming, docstrings, annotations and function size

What it does

Ruff-compatible codes

Ruff's default rule set (E4, E7, E9, F) with the same numbers, so existing # noqa comments carry over; 19,827 of 19,830 findings agree on a 6,988-file corpus.

Verified safe fixes

lint --fix removes unused imports and fixes F541, F632, E703, E713 and E714; every pass is checked against the expected syntax tree.

Two identical engines

A pure-Python engine and a Rust engine with its own parser give identical findings; the engine changes only speed.

Refactoring rules

Verb-first function names, docstrings with Args and Returns, annotations and function-size limits, with bounded fixes.

CI ready

Text, JSON, SARIF and GitHub annotations; documented exit codes; a pre-commit hook and VS Code extension.

Safe writes

Files change only after the new text compiles and passes its check, atomically, with line endings and BOM kept.

Who it is for

Developers

catch unused imports and undefined names, then fix them safely.

Teams

enforce naming, docstrings and function size in CI with SARIF output.

Data scientists

clean notebooks and scripts before sharing them.

Students

learn readable Python with clear, located findings.

Questions

Is RefacTrail compatible with Ruff?

It implements Ruff's default rule set with the same codes and # noqa comments; on a 6,988-file corpus 19,827 of Ruff's 19,830 findings match. Ruff is still faster.

How do I remove unused imports automatically?

Run refactrail lint src --select F401 --fix; preview with --diff. Imports in __init__.py, stubs and ImportError guards are left alone.

Does it need Rust installed?

No. Wheels include the native engine for common platforms, with a pure-Python fallback.

Does it run my code?

No. Analysis never imports or executes the code it checks.

Is it free?

Yes, MIT-licensed and on PyPI.

One family of tools

FuncLoom

the functionizer: scripts and notebooks to functions and packages

RefacTrail

the refactorizer: linter, formatter and verified refactoring

FlowBlueprint

the architect: code to architecture diagrams