[Eljees]

Closes #821.

A diagnostic about the module as a whole comes back pointing at a line that does not exist:

$ ruff check --isolated --select D100,F401 t.py
t.py:1:1: D100 Missing docstring in public module
t.py:1:8: F401 [*] `math` imported but unused
t.py:2:8: F401 [*] `random` imported but unused

$ nbqa --nbqa-shell ruff t.ipynb --isolated --select D100,F401
t.ipynb:cell_1:0:1: D100 Missing docstring in public module
t.ipynb:cell_1:1:8: F401 [*] `math` imported but unused
t.ipynb:cell_1:2:8: F401 [*] `random` imported but unused

F401 is 1-indexed and D100 is 0-indexed, in the same output. flake8 behaves the same way. On the equivalent plain .py file both are at line 1, so the 0 does not come from the tool.

Cause

Every cell in the temporary Python file starts with the # %%NBQA-CELL-SEP... comment nbQA inserts itself, and _get_line_numbers_for_mapping maps that line to cell line 0. A module-level message is reported by the tool on line 1 of the file -- that is, on the separator -- so it is mapped back to cell_1:0.

This maps the separator line to the first line the user actually wrote.

Existing expectations

Four pydocstyle expectations recorded cell_1:0 at module level -- one in tests/tools/test_pydocstyle.py and three in tests/test_jupytext.py. They froze exactly the behaviour this issue is about, so they are updated to cell_1:1 in the same commit. Flagging it explicitly rather than burying it in the diff: if you would rather keep the old numbering, this PR is the wrong change and I will close it.

Tests

In tests/test_map_python_line_to_nb_lines.py: a unit test on _get_line_numbers_for_mapping and an end-to-end check through pylint --disable=all --enable=C0114. Both fail on main.

Test suite

3 failed, 118 passed, 3 skipped on this branch. The same three tests/tools/test_ruff_works.py failures are present on main (newer ruff output format) and are unrelated to this change.

[Eljees]

A note on the red marks here, because they say something other than what they look like.

Neither this branch nor #907 has ever been tested. Both runs on the previous head were recorded as failures without starting a single job:

run 31778653328  tox    created 2026-08-14 07:06:12Z   updated 2026-09-13 07:06:44Z   conclusion failure   jobs 0
run 31778653242  docs   created 2026-08-14 07:06:12Z   updated 2026-09-13 07:06:44Z   conclusion failure   jobs 0

Thirty days and thirty-two seconds apart, which is what happens to a fork run left in action_required: the approval window closes and the run is written down as a failure although nothing ran.

I have refreshed both branches onto current main. Each now has a fresh tox and docs run waiting on "Approve and run workflows", so one press gives both pull requests a real result.

One thing to expect when they do run: tox is currently red on main itself. On #904 it fails three cases in tests/tools/test_ruff_works.py with output-text mismatches, which reads as ruff version drift rather than anything in these two branches.

#906 moves a cell's first line from 0 to 1 in reported positions; #907 keeps the tool's exit code when a notebook comes back unchanged. Both are small and independent of each other.