Preview minimal f-string formatting

crates/ruff_python_formatter/resources/test/fixtures/ruff/expression/fstring.options.json

@@ -0,0 +1,8 @@
+[
+  {
+    "preview": "enabled"
+  },
+  {
+    "preview": "disabled"
+  }
+]

crates/ruff_python_formatter/resources/test/fixtures/ruff/expression/fstring.py

@@ -30,30 +30,30 @@
 # an expression inside a formatted value
 (
     f'{1}'
-    # comment
+    # comment 1
     ''
 )
 
 (
-    f'{1}'  # comment
+    f'{1}'  # comment 2
     f'{2}'
 )
 
 (
     f'{1}'
-    f'{2}'  # comment
+    f'{2}'  # comment 3
 )
 
 (
-    1, (  # comment
+    1, (  # comment 4
         f'{2}'
     )
 )
 
 (
     (
         f'{1}'
-        # comment
+        # comment 5
     ),
     2
 )
@@ -62,3 +62,221 @@
 x = f'''a{""}b'''
 y = f'''c{1}d"""e'''
 z = f'''a{""}b''' f'''c{1}d"""e'''
+
+# F-String formatting test cases (Preview)
+
+# Simple expression with a mix of debug expression and comments.
+x = f"{a}"
+x = f"{
+    a = }"
+x = f"{ # comment 6
+    a }"
+x = f"{   # comment 7
+    a = }"
+
+# Remove the parentheses as adding them doesn't make then fit within the line length limit.
+# This is similar to how we format it before f-string formatting.
+aaaaaaaaaaa = (
+    f"asaaaaaaaaaaaaaaaa { aaaaaaaaaaaa + bbbbbbbbbbbb + ccccccccccccccc + dddddddd } cccccccccc"
+)
+# Here, we would use the best fit layout to put the f-string indented on the next line
+# similar to the next example.
+aaaaaaaaaaa = f"asaaaaaaaaaaaaaaaa { aaaaaaaaaaaa + bbbbbbbbbbbb + ccccccccccccccc } cccccccccc"
+aaaaaaaaaaa = (
+    f"asaaaaaaaaaaaaaaaa { aaaaaaaaaaaa + bbbbbbbbbbbb + ccccccccccccccc } cccccccccc"
+)
+
+# This should never add the optional parentheses because even after adding them, the
+# f-string exceeds the line length limit.
+x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ccccccccccccccc"
+x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" = } ccccccccccccccc"
+x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { # comment 8
+                                             "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ccccccccccccccc"
+x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { # comment 9
+                                             "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" = } ccccccccccccccc"
+
+# Multiple larger expressions which exceeds the line length limit. Here, we need to decide
+# whether to split at the first or second expression. This should work similarly to the
+# assignment statement formatting where we split from right to left in preview mode.
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"
+
+# The above example won't split but when we start introducing line breaks:
+x = f"aaaaaaaaaaaa {
+        bbbbbbbbbbbbbb } cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb
+                    } cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc {
+        ddddddddddddddd } eeeeeeeeeeeeee"
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc { ddddddddddddddd
+                                                            } eeeeeeeeeeeeee"
+
+# But, in case comments are present, we would split at the expression containing the
+# comments:
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb # comment 10
+                    } cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb
+                    } cccccccccccccccccccc { # comment 11
+                                            ddddddddddddddd } eeeeeeeeeeeeee"
+
+# Here, the expression part itself starts with a curly brace so we need to add an extra
+# space between the opening curly brace and the expression.
+x = f"{ {'x': 1, 'y': 2} }"
+# Although the extra space isn't required before the ending curly brace, we add it for
+# consistency.
+x = f"{ {'x': 1, 'y': 2}}"
+x = f"{ {'x': 1, 'y': 2} = }"
+x = f"{  # comment 12
+    {'x': 1, 'y': 2} }"
+x = f"{    # comment 13
+    {'x': 1, 'y': 2} = }"
+
+# But, in this case, we would split the expression itself because it exceeds the line
+# length limit so we need not add the extra space.
+xxxxxxx = f"{
+    {'aaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbb', 'ccccccccccccccccccccc'}
+}"
+# And, split the expression itself because it exceeds the line length.
+xxxxxxx = f"{
+    {'aaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbb', 'cccccccccccccccccccccccccc'}
+}"
+
+# Quotes
+f"foo 'bar' {x}"
+f"foo \"bar\" {x}"
+f'foo "bar" {x}'
+f'foo \'bar\' {x}'
+f"foo {"bar"}"
+f"foo {'\'bar\''}"
+
+# Here, the formatter will remove the escapes which is correct because they aren't allowed
+# pre 3.12. This means we can assume that the f-string is used in the context of 3.12.
+f"foo {'\"bar\"'}"
+
+
+# Triple-quoted strings
+# It's ok to use the same quote char for the inner string if it's single-quoted.
+f"""test {'inner'}"""
+f"""test {"inner"}"""
+# But if the inner string is also triple-quoted then we should preserve the existing quotes.
+f"""test {'''inner'''}"""
+
+# Magic trailing comma
+#
+# The expression formatting will result in breaking it across multiple lines with a
+# trailing comma but as the expression isn't already broken, we will remove all the line
+# breaks which results in the trailing comma being present. This test case makes sure
+# that the trailing comma is removed as well.
+f"aaaaaaa {['aaaaaaaaaaaaaaa', 'bbbbbbbbbbbbb', 'ccccccccccccccccc', 'ddddddddddddddd', 'eeeeeeeeeeeeee']} aaaaaaa"
+
+# And, if the trailing comma is already present, we still need to remove it.
+f"aaaaaaa {['aaaaaaaaaaaaaaa', 'bbbbbbbbbbbbb', 'ccccccccccccccccc', 'ddddddddddddddd', 'eeeeeeeeeeeeee',]} aaaaaaa"
+
+# Keep this Multiline by breaking it at the square brackets.
+f"""aaaaaa {[
+    xxxxxxxx,
+    yyyyyyyy,
+]} ccc"""
+
+# Add the magic trailing comma because the elements don't fit within the line length limit
+# when collapsed.
+f"aaaaaa {[
+    xxxxxxxxxxxx,
+    xxxxxxxxxxxx,
+    xxxxxxxxxxxx,
+    xxxxxxxxxxxx,
+    xxxxxxxxxxxx,
+    xxxxxxxxxxxx,
+    yyyyyyyyyyyy
+]} ccccccc"
+
+# Remove the parenthese because they aren't required
+xxxxxxxxxxxxxxx = (
+    f"aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbb {
+        xxxxxxxxxxx  # comment 14
+        + yyyyyyyyyy
+    } dddddddddd"
+)
+
+# Comments
+
+# No comments should be dropped!
+f"{ # comment 15
+    # comment 16
+    foo # comment 17
+    # comment 18
+}"  # comment 19
+# comment 20
+
+# Conversion flags
+#
+# This is not a valid Python code because of the additional whitespace between the `!`
+# and conversion type. But, our parser isn't strict about this. This should probably be
+# removed once we have a strict parser.
+x = f"aaaaaaaaa { x !  r }"
+
+# Even in the case of debug expresions, we only need to preserve the whitespace within
+# the expression part of the replacement field.
+x = f"aaaaaaaaa { x   = !  r  }"
+
+# Combine conversion flags with format specifiers
+x = f"{x   =   !  s
+         :>0
+
+         }"
+# This is interesting. There can be a comment after the format specifier but only if it's
+# on it's own line. Refer to https://github.com/astral-sh/ruff/pull/7787 for more details.
+# We'll format is as trailing comments.
+x = f"{x  !s
+         :>0
+         # comment 21
+         }"
+
+x = f"""
+{              # comment 22
+ x =   :.0{y # comment 23
+           }f}"""
+
+# Here, the debug expression is in a nested f-string so we should start preserving
+# whitespaces from that point onwards. This means we should format the outer f-string.
+x = f"""{"foo " +    # comment 24
+    f"{   x =
+
+       }"    # comment 25
+ }
+        """
+
+# Mix of various features.
+f"{  # comment 26
+    foo # after foo
+   :>{
+          x # after x
+          }
+    # comment 27
+    # comment 28
+} woah {x}"
+
+# Indentation
+
+# What should be the indentation?
+# https://github.com/astral-sh/ruff/discussions/9785#discussioncomment-8470590
+if indent0:
+    if indent1:
+        if indent2:
+            foo = f"""hello world
+hello {
+          f"aaaaaaa {
+              [
+                  'aaaaaaaaaaaaaaaaaaaaa',
+                  'bbbbbbbbbbbbbbbbbbbbb',
+                  'ccccccccccccccccccccc',
+                  'ddddddddddddddddddddd'
+              ]
+          } bbbbbbbb" +
+          [
+              'aaaaaaaaaaaaaaaaaaaaa',
+              'bbbbbbbbbbbbbbbbbbbbb',
+              'ccccccccccccccccccccc',
+              'ddddddddddddddddddddd'
+          ]
+      } --------
+"""

crates/ruff_python_formatter/resources/test/fixtures/ruff/expression/fstring_py312.options.json

@@ -0,0 +1,5 @@
+[
+  {
+    "target_version": "py312"
+  }
+]

crates/ruff_python_formatter/resources/test/fixtures/ruff/expression/fstring_py312.py

@@ -0,0 +1,6 @@
+# This file contains test cases only for cases where the logic tests for whether
+# the target version is 3.12 or later. A user can have 3.12 syntax even if the target
+# version isn't set.
+
+# Quotes re-use
+f"{'a'}"

crates/ruff_python_formatter/src/builders.rs

@@ -1,7 +1,7 @@
 use ruff_formatter::{write, Argument, Arguments};
 use ruff_text_size::{Ranged, TextRange, TextSize};
 
-use crate::context::{NodeLevel, WithNodeLevel};
+use crate::context::{FStringState, NodeLevel, WithNodeLevel};
 use crate::other::commas::has_magic_trailing_comma;
 use crate::prelude::*;
 
@@ -205,6 +205,15 @@ impl<'fmt, 'ast, 'buf> JoinCommaSeparatedBuilder<'fmt, 'ast, 'buf> {
     }
 
     pub(crate) fn finish(&mut self) -> FormatResult<()> {
+        // If the formatter is inside an f-string expression element, and the layout
+        // is flat, then we don't need to add a trailing comma.
+        if let FStringState::InsideExpressionElement(context) = self.fmt.context().f_string_state()
+        {
+            if context.layout().is_flat() {
+                return Ok(());
+            }
+        }
+
         self.result.and_then(|()| {
             if let Some(last_end) = self.entries.position() {
                 let magic_trailing_comma = has_magic_trailing_comma(

crates/ruff_python_formatter/src/comments/placement.rs

@@ -289,6 +289,28 @@ fn handle_enclosed_comment<'a>(
             }
         }
         AnyNodeRef::FString(fstring) => CommentPlacement::dangling(fstring, comment),
+        AnyNodeRef::FStringExpressionElement(_) => {
+            // Handle comments after the format specifier (should be rare):
+            //
+            // ```python
+            // f"literal {
+            //     expr:.3f
+            //     # comment
+            // }"
+            // ```
+            //
+            // This is a valid comment placement.
+            if matches!(
+                comment.preceding_node(),
+                Some(
+                    AnyNodeRef::FStringExpressionElement(_) | AnyNodeRef::FStringLiteralElement(_)
+                )
+            ) {
+                CommentPlacement::trailing(comment.enclosing_node(), comment)
+            } else {
+                handle_bracketed_end_of_line_comment(comment, locator)
+            }
+        }
         AnyNodeRef::ExprList(_)
         | AnyNodeRef::ExprSet(_)
         | AnyNodeRef::ExprListComp(_)