Flake8 Noqa Comment Validation

1.5.0 · active · verified Sat Apr 11

flake8-noqa is a plugin for Flake8 that validates `# noqa` comments in Python code. It ensures that these comments are correctly formatted, are not redundant (i.e., they suppress an actual reported error), and that any specified error codes in `# noqa:` comments correspond to violations found on that line. The current version is 1.5.0, and it's released as needed in conjunction with Flake8 updates.

Warnings

gotcha Incorrect formatting of `# noqa` comments can lead to them being ignored entirely or interpreted as a blanket `# noqa` (ignoring all errors on the line) even if specific codes were intended. Common mistakes include `# noqa F841`, `# noqa : F841`, or extra spaces.
Fix: Ensure `# noqa` comments are strictly formatted as `# noqa: CODE` (e.g., `# noqa: F841`) to apply to specific errors, or simply `# noqa` to ignore all errors on a line. The plugin helps catch these issues.
gotcha Errors reported by `flake8-noqa` (e.g., about malformed or unnecessary `# noqa` comments) cannot be suppressed using another `# noqa` comment. Trying to do so will not work.
Fix: To ignore errors reported by `flake8-noqa` itself, you must use Flake8's standard configuration options such as `ignore`, `extend-ignore`, or `per-file-ignores` in your `setup.cfg`, `tox.ini`, or `.flake8` file.
gotcha Some other Flake8 plugins might perform their own processing of `# noqa` comments and stop reporting violations to Flake8. This can prevent `flake8-noqa` from accurately detecting whether a `# noqa` comment is necessary or correctly matches an existing violation.
Fix: The recommended approach is to configure such problematic plugins to *not* respect `# noqa` comments, allowing Flake8 (and by extension `flake8-noqa`) to handle all `# noqa` processing uniformly. If the plugin lacks such an option, consider reporting an issue to its maintainers.
gotcha Using file-level `# flake8: noqa: CODE` (e.g., `# flake8: noqa: E712`) is often misunderstood. Flake8 will ignore *all* errors in the file, not just the specified ones, leading to potential overlooked issues.
Fix: To ignore specific errors across a file, use Flake8's `per-file-ignores` configuration. To ignore all errors in a file, use `# flake8: noqa` without specifying any codes, or preferably, use Flake8's `--exclude` option in your configuration.

Install

pip install flake8-noqa Install plugin

Quickstart

To use flake8-noqa, simply install it alongside Flake8. The plugin automatically integrates. After creating a Python file (e.g., `example.py`) with some code, including a correctly formatted `# noqa: F841` comment and an intentionally malformed one (`# noqa F842`), run `flake8` from your terminal. The plugin will report issues with the malformed `# noqa` comment and other linting errors.

import os

def unused_function(): # noqa: F841
    pass

def another_unused_function(): # noqa F842
    # This noqa is intentionally malformed to trigger flake8-noqa
    pass

def missing_docstring():
    # This will trigger a D103 error (if pydocstyle is enabled)
    pass

view raw JSON →