konform¶

Multi-rule Python linter and language server: fast, configurable, and CI-ready.

Work in progress. konform is under active development. Rules, configuration keys, CLI flags, and the LSP surface may change at any time, including in backwards-incompatible ways, until a 1.0 release.

Documentation

Why konform?¶

Ruff covers most of what a Python project wants from a linter, but not everything. konform is a small, fast Rust linter for the checks that fall through the gaps. Its rules are opinionated: they encode a specific style (such as the Google Python Style Guide's module-only imports) rather than universal correctness, and the list keeps growing.

• Opinionated import rules: enforce module-only imports (KIS001) and flag needless from X import Y as Z aliases (KIS002).
• Project-specific rules: define your own regex rules (KPT) in TOML, with messages, file globs and optional replacements. No plugin code.
• Auto-fixes with a Ruff-style safe/unsafe split.
• Built-in language server that shares the CLI's engine.
• CI-ready output: GitHub, GitLab, SARIF, JUnit, Zuul and JSON.

The node kinds and condition keys above are konform's own vocabulary, not the parser's: each kind maps onto one or more parser node types inside konform (for example assign covers =, annotated and augmented assignment; function covers def and async def; yield covers yield from). Rules therefore stay valid when the underlying parser is upgraded or replaced, and parser type names (such as Ruff's StmtAssert) are rejected as unknown kinds.

Installation¶

# As an isolated tool (recommended)
uv tool install konform
pipx install konform

# Run without installing
uvx konform check src/

# Into the current environment
pip install konform

Wheels ship a pre-compiled Rust binary, so no Rust installation is needed at runtime.

Example¶

# app.py
from os.path import join

print(join("a", "b"))

$ konform check app.py
error[KIS001][*]: Import 'join' from 'os.path' is not a module.
  --> app.py:1:1
  help: Use only module imports, see: https://google.github.io/styleguide/pyguide.html#22-imports

Found 1 error.
[*] 1 fixable with the `--fix` option.

$ konform check --fix app.py

Other useful commands:

konform check --fix --unsafe-fixes src/   # also apply unsafe fixes (e.g. KIS002)
konform check --output-format github .    # annotations for GitHub Actions
konform rule --list                       # list rules
konform rule --explain KIS001             # explain a rule
konform server                            # start the language server

Configure it in pyproject.toml (or konform.toml):

[tool.konform.lint]
select = ["KIS"]

[tool.konform.lint.module-only-imports]
exceptions = ["typing", "mycompany.compat"]

See the documentation for the full rule, configuration, CLI and editor reference.

Development¶

You need a Rust toolchain (pinned in rust-toolchain.toml) and uv.

# Build and test
cargo build
cargo test
cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings

# Run the dev binary
cargo run -- check path/to/file.py

# Build the Python package (wheel with the compiled binary)
uv run maturin build --release        # wheels land in target/wheels/
uv run maturin develop                # or install into the project venv

# Regenerate the rules, CLI and env-var reference pages from the code
# (docs/rules/ and docs/reference/{cli,environment-variables}.md, checked by a test)
cargo run -- generate-docs docs

# Build and preview the documentation
uv run --only-group dev --python 3.12 zensical serve
uv run --only-group dev --python 3.12 zensical build --clean --strict

The docs source lives in docs/ (config in mkdocs.yml; the landing page is this README) and is deployed to GitHub Pages by .github/workflows/docs.yml on every push to main. Commits follow Conventional Commits; releases are cut with commitizen.

Acknowledgements¶

konform exists because Ruff doesn't (yet) cover rules like KIS001/KIS002; konform was built to fill that gap, and Ruff's design was a direct inspiration for how konform is configured, how it reports violations, and how it resolves src search roots.

konform is also built on top of several excellent open-source projects, especially:

• ruff_python_parser, ruff_python_ast, and ruff_text_size: Ruff's own Python parser and AST, published standalone on crates.io.

Thanks to all the maintainers of all used open-source projects.

License¶

MIT