[sanjayrohith]

Summary

Documents that map objects and generator expressions are not interchangeable
when the mapped expression raises, which is a known source of false positives
for unnecessary-map (C417).

Once an exception propagates out of a generator, the generator is closed and
every later next() call raises StopIteration. A map object has no frame to
close, so a caller that handles the exception can keep iterating. Code that
relies on this - for example, collecting every element that converts
successfully and reporting all failures at the end, rather than stopping at the
first one - behaves differently after C417's fix is applied.

As discussed in the issue, there isn't a good way for Ruff to detect this
situation and suppress the diagnostic, so this adds a ## Known problems
section describing the difference and notes it under ## Fix safety as an
additional reason the fix is unsafe.

Docs-only; no behavior change.

Closes #27304

Test Plan

cargo dev generate-all, plus cargo nextest run -p ruff_linter -p ruff_dev
and cargo clippy -p ruff_linter --all-targets -- -D warnings to confirm the
doc comment still builds and no generated artifact is stale.

[Copilot]

Pull request overview

This PR updates the Rustdoc for the flake8-comprehensions C417 rule (unnecessary-map) to document a known semantic difference between map() objects and generator expressions when the mapping operation raises, clarifying why Ruff cannot reliably suppress false positives and why the fix is marked unsafe.

Changes:

• Add a ## Known problems section explaining the exception/iteration behavior difference between map() and generator expressions.
• Expand ## Fix safety to note that the fix can change error-propagation/iterator behavior in addition to occasionally dropping comments.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ntBre]

Thanks, this looks good to me. Initially I thought the example was a bit long, but I think this is a pretty subtle issue that justifies an example. I just had one nit about the fix safety docs.

[astral-sh-bot]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.