Parenthesize singleton tuples in yield expressions

CHANGES.md

@@ -34,6 +34,8 @@
 
 - Fix unnecessary parentheses around short RHS expressions in indexed assignments like
   `x[key] = expr` (#5095)
+- Parenthesize tuple expressions in `yield` statements for consistency with function
+  calls and returns (#5170)
 - Stop splitting between a variable and its comparator (`not in`, `==`, `is`, ...) when
   the right-hand side is a bracketed expression. Black now lets the bracket explode
   instead. This fixes the awkward break that was showing up in comprehension `if`

docs/the_black_code_style/future_style.md

@@ -41,6 +41,8 @@ Currently, the following features are included in the preview style:
 - `hug_comparator`: Don't break a comparator (`not in`, `==`, `is`, ...) away from its
   left operand when the right operand is a bracketed expression that has to break
   anyway; let the bracket explode instead. ([see below](labels/hug-comparator))
+- `parenthesize_tuple_in_yield`: Add parentheses around tuple expressions in `yield`
+  statements.
 
 (labels/wrap-comprehension-in)=
 

src/black/linegen.py

@@ -681,6 +681,13 @@ def __post_init__(self) -> None:
 
         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
+        self.visit_yield_expr = partial(
+            v,
+            keywords=Ø,
+            parens=(
+                {"yield"} if Preview.parenthesize_tuple_in_yield in self.mode else Ø
+            ),
+        )
         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
         self.visit_async_funcdef = self.visit_async_stmt
@@ -1642,6 +1649,18 @@ def normalize_invisible_parens(
                     wrap_in_parentheses(node, child, visible=False)
             elif isinstance(child, Node) and node.type == syms.with_stmt:
                 remove_with_parens(child, node, mode=mode, features=features)
+            elif (
+                isinstance(child, Node)
+                and node.type == syms.yield_expr
+                and child.type == syms.yield_arg
+                and Preview.parenthesize_tuple_in_yield in mode
+            ):
+                if (
+                    len(child.children) == 1
+                    and child.children[0].type != syms.atom
+                    and is_one_tuple(child.children[0])
+                ):
+                    wrap_in_parentheses(node, child, visible=True)
             elif child.type == syms.atom and not (
                 "in" in parens_after
                 and len(child.children) == 3
@@ -1933,6 +1952,8 @@ def maybe_make_parens_invisible_in_atom(
             syms.expr_stmt,
             syms.assert_stmt,
             syms.return_stmt,
+            syms.yield_arg,
+            syms.yield_expr,
             syms.except_clause,
             syms.funcdef,
             syms.with_stmt,

src/black/mode.py

@@ -262,6 +262,7 @@ class Preview(Enum):
     pyi_blank_line_before_decorated_class = auto()
     pyi_blank_line_after_function_docstring = auto()
     hug_comparator = auto()
+    parenthesize_tuple_in_yield = auto()
 
 
 UNSTABLE_FEATURES: set[Preview] = {

src/black/resources/black.schema.json

@@ -91,7 +91,8 @@
           "fix_unnecessary_parens_in_indexed_assignment",
           "pyi_blank_line_before_decorated_class",
           "pyi_blank_line_after_function_docstring",
-          "hug_comparator"
+          "hug_comparator",
+          "parenthesize_tuple_in_yield"
         ]
       },
       "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."

tests/data/cases/yield_singleton_tuple.py

@@ -0,0 +1,11 @@
+# flags: --preview
+
+def f():
+    yield x,
+
+
+# output
+
+
+def f():
+    yield (x,)

tests/data/cases/yield_singleton_tuple_stable.py

@@ -0,0 +1,9 @@
+def f():
+    yield x,
+
+
+# output
+
+
+def f():
+    yield x,