From dec4154c8ae82f53731b09f3db44502e92951510 Mon Sep 17 00:00:00 2001
From: Brent Westbrook <36778786+ntBre@users.noreply.github.com>
Date: Fri, 12 Dec 2025 12:57:09 -0500
Subject: [PATCH] Document known lambda formatting deviations from Black
 (#21954)

Summary
--

Following #8179, we now format long lambda expressions a bit more like
Black, preferring to keep long parameter lists on a single line, but we
go one step further to break the body itself across multiple lines and
parenthesize it if it's still too long. This PR documents both the
stable deviation that breaks parameters across multiple lines, and the
new preview deviation that breaks the body instead.

I also fixed a couple of typos in the section immediately above my
addition.

Test Plan
--

I tested all of the snippets here against `main` for the preview
behavior, our playground for the stable behavior, and Black's playground
for their behavior
---
 docs/formatter/black.md | 97 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 1 deletion(-)

diff --git a/docs/formatter/black.md b/docs/formatter/black.md
index 9b18bf5443..8849a6d5fd 100644
--- a/docs/formatter/black.md
+++ b/docs/formatter/black.md
@@ -722,7 +722,7 @@ with tempfile.TemporaryDirectory() as d1:
 
 ### Preserving parentheses around single-element lists
 
-Ruff preserves at least one parentheses around list elements, even if the list only contains a single element. The Black 2025 or newer, on the other hand, removes the parentheses 
+Ruff preserves at least one set of parentheses around list elements, even if the list only contains a single element. The Black 2025 style or newer, on the other hand, removes the parentheses
 for single-element lists if they aren't multiline and doing so does not change semantics:
 
 ```python
@@ -742,3 +742,98 @@ items = [(True)]
 items = {(123)}
 
 ```
+
+### Long lambda expressions
+
+In [preview](../preview.md), Ruff will keep lambda parameters on a single line,
+just like Black:
+
+```python
+# Input
+def a():
+    return b(
+        c,
+        d,
+        e,
+        f=lambda self, *args, **kwargs: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+            *args, **kwargs
+        ),
+    )
+
+# Ruff Stable
+def a():
+    return b(
+        c,
+        d,
+        e,
+        f=lambda self,
+        *args,
+        **kwargs: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(*args, **kwargs),
+    )
+
+# Black and Ruff Preview
+def a():
+    return b(
+        c,
+        d,
+        e,
+        f=lambda self, *args, **kwargs: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+            *args, **kwargs
+        ),
+    )
+```
+
+However, if the body expression exceeds the configured line length, Ruff will
+additionally add parentheses around the lambda body and break it over multiple
+lines:
+
+```python
+# Input
+def a():
+    return b(
+        c,
+        d,
+        e,
+        # Additional `b` character pushes this over the line length
+        f=lambda self, *args, **kwargs: baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+            *args, **kwargs
+        ),
+        # More complex expressions also trigger wrapping
+        g=lambda self, *args, **kwargs: baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+            *args, **kwargs
+        ) + 1,
+    )
+
+# Black
+def a():
+    return b(
+        c,
+        d,
+        e,
+        # Additional `b` character pushes this over the line length
+        f=lambda self, *args, **kwargs: baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+            *args, **kwargs
+        ),
+        # More complex expressions also trigger wrapping
+        g=lambda self, *args, **kwargs: baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(
+            *args, **kwargs
+        )
+        + 1,
+    )
+
+# Ruff Preview
+def a():
+    return b(
+        c,
+        d,
+        e,
+        # Additional `b` character pushes this over the line length
+        f=lambda self, *args, **kwargs: (
+            baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(*args, **kwargs)
+        ),
+        # More complex expressions also trigger wrapping
+        g=lambda self, *args, **kwargs: (
+            baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa(*args, **kwargs) + 1
+        ),
+    )
+```