[flake8-comprehensions] Document RecursionError edge case in __len__ (C416) (astral-sh#25286)

C416's autofix rewrites a list comprehension like `[item for item in
self]` into `list(self)`, but when the original is reached from inside
`__len__`, the rewrite recurses: CPython's `list()` constructor probes
`__length_hint__` (which dispatches to `__len__`) as a sizing
optimization while iterating, so `list(self)` from inside `__len__`
calls `__len__` again. The same applies to `dict()` and `set()` calls on
`self`.

In astral-sh#13752, MichaReiser noted that extending the docs would be reasonable
and that detecting this control flow isn't the goal. I added a paragraph
to the C416 docstring with a runnable example of the failure mode, plus
the `# noqa: C416` workaround for when the comprehension is reached
(directly or transitively) from `__len__`.

The change is docstring-only. `cargo dev generate-all` and `uvx prek run
--from-ref main` both pass.

fixes astral-sh#13752

---------

Co-authored-by: Brent Westbrook <brentrwestbrook@gmail.com>

Author: 2 people

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension.rs

@@ -52,10 +52,12 @@ use crate::rules::flake8_comprehensions::fixes;
 /// cannot consistently infer if the iterable type is a sequence or a mapping and cannot suggest
 /// the correct fix for mappings.
 ///
-/// ## Fix safety
-/// Due to the known problem with dictionary comprehensions, this fix is marked as unsafe.
+/// Additionally, rewriting comprehensions inside an object's `__len__` method may cause a
+/// `RecursionError`, as collection constructors can call back into `__len__`.
 ///
-/// Additionally, this fix may drop comments when rewriting the comprehension.
+/// ## Fix safety
+/// This rule's fix is always marked as unsafe because of the known problems described above and
+/// because comments may be dropped when rewriting the comprehension.
 #[derive(ViolationMetadata)]
 #[violation_metadata(stable_since = "v0.0.73")]
 pub(crate) struct UnnecessaryComprehension {