Skip to content

noqaexplain

Features

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

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

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:

  • 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.