noqaexplain

Comply or explain - justify every ignored linting rule.

✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal

---

Features

noqaexplain is a linter which enforces justifying every ignored linting rule supporting multiple formats/linters:

• Python -ruff and flake8 # noqa, coveragepy # pragma: no cover
• JavaScript/TypeScript - eslint
• Rust - clippy
• Dockerfiles - hadolint
• YAML - yamllint
• Shell - shellcheck

Important

You can expand this list with any language and linter by using extend_suffix_mapping and/or extend_name_mapping! Feel free to open a request to add support for more linters.

Table of contents

• Quick start
  • Installation
  • Usage
• Advanced
  • Configuration
  • Run as a pre-commit hook
  • Rules

Quick start

Installation

Tip

You can use your favorite package manager like uv, hatch or pdm instead of pip.

> pip install noqaexplain

Usage

To check against all files (the ones with defined mappings from file extension to error disable comment format), run:

> noqaxplain check

You can pass additional arguments to noqaexplain check, like files to check:

> noqaexplain check path/to/file.py maybe.rs other.yml formats.js

If a certain file has a line with disabled check without an explanation, the tool will report it:

path/to/file.py:10:5: ENQ0 Missing explanation (enoqa) for disabled linting rule

to fix it, just add an explanation after the disable comment prefixed by enq:, e.g.:

import some_library
# enq: Disabled private access check as there is no other workaround currently.
# noqa: SLF001
some_library._private_function()

Advanced

Configuration

You can configure pynudger in pyproject.toml (or .noqaexplain.toml in the root of your project, just remove the [tool.noqaexplain] section), for example:

[tool.noqexplain]
# include rules by their code
include_codes = [0] # default: all rules included
# exclude rules by their code (takes precedence over include)
exclude_codes = [1] # default: no rules excluded
# whether to exit after first error or all errors
end_mode = "first" # default: "all"

# Extends Python noqas mappings
# Now every # my_noqa_header: will be treated as a noqa comment
# and checked for explanations.
extend_suffix_mapping = {".py" = ["# my_noqa_header:"]}
# Target any MySuperFile.md file(s) and look for explanations
extend_name_mapping = {"MySuperFile.md" = ["# my_noqa_header:"]}

Tip

Rule-specific configuration can be found in the section below.

Run as a pre-commit hook

noqaexplain can be used as a pre-commit hook, to add as a plugin:

repos:
-   repo: "https://github.com/open-nudge/noqaexplain"
    rev: ...  # select the tag or revision you want, or run `pre-commit autoupdate`
    hooks:
    -   id: "noqaexplain"

Rules

Tip

Run noqaexplain rules to see the list of available rules.

noqaexplain provides the following rules:

Name	Description
NQE0	Ensures that all disabled linting rules have an associated explanation one line above them
NQE1	Ensures that all disabled linting rules have an associated explanation of at least

and the following configurable options (in pyproject.toml or .noqaexplain.toml):

Option	Description	Affected rules	Default
extend_suffix_mapping	Additional file suffix to noqa comment(s) format mappings (dict of lists)	All	{}
extend_name_mapping	Additional file name to noqas comment(s) format mappings (dict of lists)	All	{}
suffix_mapping	File suffix to noqa comment format(s) mappings (dict of lists, overrides default!)	All	{}
name_mapping	File name to noqa comment format(s) mappings (dict of lists, overrides default!)	All	{}
min_explain_length	Minimum length of explanation for disabled linting rules	NQE1	10
explain_noqa_pattern	String identifying explanation for disabled linting rule	NQE0	"enq:"

Contribute

We welcome your contributions! Start here:

• Code of Conduct
• Contributing Guide
• Roadmap
• Changelog
• Report security vulnerabilities
• Open an Issue

Legal

• This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
• This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.