nocomment-linter

nocomment-linter bans comments in Python code and is designed for coding agents: compact, stable, one-line-per-violation output, safe autofix.

What it does

• checks only *.py files (never .pyi);
• reports regular Python comments; #!, coding cookies, # noqa, # type: ignore, # pragma: no cover, # fmt: off/on, # ruff: noqa, # pyright: ignore are preserved (tooling comments);
• optionally bans and removes docstrings (module, class, function, async function) — detected via AST, exactly what Python treats as a docstring;
• --fix removes violations in place and never writes a file that would not compile;
• configured through pyproject.toml; no .gitignore support.

Installation

pip install nocomment-linter

uv add nocomment-linter --dev

Requires Python 3.11+. For the flake8 plugin, flake8 itself must also be installed (pip install flake8).

From source (development):

uv sync

Check

nocomment-linter .
nocomment-linter src tests

Autofix

nocomment-linter --fix .

Exit codes: 0 — no violations (with --fix: everything fixed), 1 — violations found or unfixable violations remain, 2 — execution error (file read, configuration, tokenizing or parsing).

Configuration

[tool.nocomment-linter]
check-docstrings = false
exclude = [
    "migrations/**",
    "generated/**",
]

• check-docstrings (default false): true also enables the DOC001-DOC004 docstring rules.
• exclude: glob patterns (fnmatch semantics) relative to the directory containing pyproject.toml. A pattern containing / is matched against the whole relative path (migrations/**); a pattern without / matches any path component, so generated excludes the generated/ directory.
• The config is the first pyproject.toml with a [tool.nocomment-linter] section found walking up from the first PATH argument, then from the current directory; with no configuration anywhere, defaults apply.

Always skipped directories: .vscode/, .idea/, .git/, .venv/, venv/, __pycache__/, .mypy_cache/, .pytest_cache/, .ruff_cache/, build/, dist/.

Rule codes

Flake8 plugin

Installed from PyPI, the package also registers a flake8 extension, so the same checks run inside flake8 (comments on by default; docstrings only with --nocomment-check-docstrings):

flake8 src tests
flake8 --nocomment-check-docstrings src tests

Code mapping (flake8 requires its own code prefix): CMT001 → NOC001, CMT002 → NOC002, DOC001 → NOC101, DOC002 → NOC102, DOC003 → NOC103, DOC004 → NOC104. Per-line # noqa: NOC001 works as usual; the plugin has no autofix — use nocomment-linter --fix for that.

Output format

One self-sufficient line per violation:

<path>:<start-line>:<start-column>-<end-line>:<end-column> <RULE> <FIX> "<content>"

Coordinates are 1-based; the range is half-open: start points at the first character of the violation, end points one past its last character. <FIX> is delete-line (whole physical line) or delete-range (the violation span). <content> is the exact source text, escaped (\n, \t, \", \\).

src/foo.py:10:5-10:23 CMT001 delete-line "# explanation"
src/foo.py:17:20-17:31 CMT002 delete-range "# legacy"
SUMMARY violations=2 files=1

With no violations:

OK violations=0 files=27

After --fix (all violations fixed):

FIXED violations=4 files=2

files counts the files successfully checked; files with read/parse errors are reported as <path>: error: <message> lines and make the run exit 2. Unfixable violations (autofix would break the file) are printed as ordinary violation lines, the file is left untouched, and the run exits 1.