Keep add_imports below a prefixed module docstring

[Eljees]

Closes #1893.

add_imports inserts the import above the module docstring when that docstring carries a string prefix:

>>> import isort
>>> src = 'r\"\"\"module docstring\n\"\"\"\nfrom __future__ import annotations\n'
>>> print(isort.code(src, add_imports=["from __future__ import annotations"]))
from __future__ import annotations

r"""module docstring
"""
from __future__ import annotations

The import is both moved above the docstring and duplicated, because the file already contained it. Reported by @Skylion007 in 2022 and hit again by @sodul in 2024.

Cause

The guard in isort/core.py that stops the insertion tests the raw line:

and not line.lstrip().startswith(COMMENT_INDICATORS)

It only recognises a docstring that begins with a quote. r"""... begins with a letter, so the guard misses it and the import goes in above the docstring.

A single-line prefixed docstring escapes this by accident: the neighbouring endswith(DOCSTRING_INDICATORS) guard catches it. Only multi-line prefixed docstrings are affected. Every legal prefix and both quote flavours break; an unprefixed docstring never does.

(The report points at isort/parse.py:218; the actual place is the guard above.)

Fix

A small helper that strips a legal string prefix, but only when a quote follows it immediately -- so ordinary identifiers like rating = 1 are left alone.

Tests

One regression test in tests/unit/test_regressions.py, three blocks: the reporter's exact input; a control that the import is still added, below the docstring; and a sweep over 12 prefixes x 2 quote flavours. It fails on main with the duplicated import shown above.

pytest tests/unit gives 615 passed with this change against 614 on a clean tree -- the same 3 failures in both runs (test_importable and two test_ticketed_features cases needing the example plugin packages), so no regressions. flake8, ruff check, ruff format --check, isort --profile hug --check and mypy are clean on both changed files.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.37%. Comparing base (0cba6f6) to head (6436e6a).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2626   +/-   ##
=======================================
  Coverage   99.36%   99.37%           
=======================================
  Files          41       41           
  Lines        3172     3180    +8     
  Branches      684      686    +2     
=======================================
+ Hits         3152     3160    +8     
  Misses         12       12           
  Partials        8        8           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[DanielNoord]

Can we reuse STRING_PREFIXES here?

[DanielNoord]

Probably better to create one shared "Is start of a comment" utility instead to make clear what we are testing for here.

[Eljees]

Both done, thanks — and the branch is rebased onto current main.

The predicate has a name. _is_comment_or_string_start(line) replaces the inline _strip_string_prefix(line.lstrip()).startswith(COMMENT_INDICATORS) at the call site in process, so the condition reads as the question it is asking. I did not fold the other startswith("#") sites into it: those ask "is this a comment", while this one asks "is this a comment or a string of any kind", and the second is what the docstring case needs.

The test reuses STRING_PREFIXES. It now iterates sorted(STRING_PREFIXES) and derives the case variants from each prefix rather than repeating a hand-written list, so the two cannot drift:

for prefix in sorted(STRING_PREFIXES):
    for cased in sorted({prefix, prefix.upper(), prefix.capitalize()}):
        for quote in ('"""', "'''"):

Measured

The reported input, run against the two revisions of core.py:

isort/core.py	isort.code(r-prefixed docstring + import, add_imports=[same import])
current main	the import is emitted a second time above the docstring
this branch	unchanged, as it should be

pytest tests/unit: 621 passed, 1 skipped, 2 failed — and those two, test_isort_supports_shared_profiles_issue_970 and test_sort_configurable_sort_issue_1732, fail identically on a clean checkout of main in this environment (they want an example profile and a natural_plus sort order that come from plugins that are not installed). main alone gives 620 passed, so the delta is exactly the one test this PR adds.

One thing the rebase fixed rather than the review: before it, tests/unit/test_importable.py::test_importable failed on the branch and passed on main — the branch simply predated the pytest.raises(SystemExit) change to that file. Worth knowing it was staleness and not this change.

ruff check and ruff format --check are clean on both files.