Rattle

Rattle is a Python linting framework built on LibCST with support for autofixes, custom in-repo lint rules, and hierarchical configuration.

Rattle is a fork of Fixit.

Features

• 48 built-in lint rules
• Autofix support when a rule can safely rewrite code
• Local custom rules that can live inside your repository
• Hierarchical pyproject.toml configuration
• Pre-commit integration for CI and local workflows
• LSP support

Install

From PyPI

uv tool install rattle-lint

pip install rattle-lint

With editor/LSP support

uv tool install "rattle-lint[lsp]"

pip install "rattle-lint[lsp]"

Agent Skill

The official AI agent skill can be installed from this repo.

npx skills add https://github.com/zigai/rattle/tree/main/src/rattle/.agents/skills/create-rattle-lint-rules

or

uvx library-skills

Basic Usage

Rattle enables no rules by default. A practical baseline for a typical typed Python project is:

[tool.rattle]
root = true
enable = [
    "blank-line-after-control-block",
    "blank-line-after-terminal-control-block",
    "blank-line-before-branch",
    "blank-line-before-unrelated-block",
    "no-suite-leading-trailing-blank-lines",
    "module-all-at-bottom",
    "no-underscore-all-exports",
    "forbidden-call",
    "no-relative-imports",
    "no-underscore-import-aliases",
    "no-unsafe-tempfile-factories",
    "no-annotated-self",
    "no-exception-message-variables",
    "no-str-exception-translation",
    "no-underscore-class",
    "public-method-order",
    "no-bare-object-annotations",
    "no-named-tuple",
    "no-static-if-condition",
    "sorted-attributes",
    "use-callable-ellipsis",
]

[tool.rattle.options."forbidden-call"]
forbidden_calls = ["typing.cast"]

Adjust the list to match the project, then lint the repository:

rattle lint .

Apply available autofixes:

rattle fix .

Explain rule metadata, examples, and settings:

rattle explain no-bare-object-annotations
rattle explain --json no-bare-object-annotations

License

MIT