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

@@ -62,3 +62,138 @@
 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
+    a }"
+x = f"{   # comment
+    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
+                                             "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ccccccccccccccc"
+x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { # comment
+                                             "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
+                    } cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"
+x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb
+                    } cccccccccccccccccccc { # comment
+                                            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
+    {'x': 1, 'y': 2} }"
+x = f"{    # comment
+    {'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'}
+}"
+
+# Comments
+
+# No comments should be dropped!
+f"{ # comment 1
+    # comment 2
+    foo # comment 3
+    # comment 4
+}"  # comment 5
+# comment 6
+
+# 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
+         }"
+
+x = f"""
+{              # dangling comment 1
+ x =   :.0{y # dangling comment 2
+           }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 1
+    f"{   x =
+
+       }"    # comment 2
+ }
+        """
+
+# Mix of various features.
+f"{  # dangling comment 1
+    foo # after foo
+   :>{
+          x # after x
+          }
+    # dangling comment 2
+    # dangling comment 3
+} woah {x}"

crates/ruff_python_formatter/src/comments/placement.rs

@@ -289,6 +289,18 @@ fn handle_enclosed_comment<'a>(
             }
         }
         AnyNodeRef::FString(fstring) => CommentPlacement::dangling(fstring, comment),
+        AnyNodeRef::FStringExpressionElement(_) => {
+            if matches!(
+                comment.preceding_node(),
+                Some(
+                    AnyNodeRef::FStringExpressionElement(_) | AnyNodeRef::FStringLiteralElement(_)
+                )
+            ) {
+                CommentPlacement::dangling(comment.enclosing_node(), comment)
+            } else {
+                handle_bracketed_end_of_line_comment(comment, locator)
+            }
+        }
         AnyNodeRef::ExprList(_)
         | AnyNodeRef::ExprSet(_)
         | AnyNodeRef::ExprListComp(_)

crates/ruff_python_formatter/src/context.rs

@@ -1,11 +1,18 @@
 use crate::comments::Comments;
-use crate::string::QuoteChar;
+use crate::string::{QuoteChar, StringQuotes};
 use crate::PyFormatOptions;
 use ruff_formatter::{Buffer, FormatContext, GroupId, IndentWidth, SourceCode};
 use ruff_source_file::Locator;
 use std::fmt::{Debug, Formatter};
 use std::ops::{Deref, DerefMut};
 
+#[derive(Copy, Clone, Debug, Default)]
+pub(crate) enum ExprLocation {
+    InsideFString(StringQuotes),
+    #[default]
+    Other,
+}
+
 #[derive(Clone)]
 pub struct PyFormatContext<'a> {
     options: PyFormatOptions,
@@ -22,6 +29,7 @@ pub struct PyFormatContext<'a> {
     /// quote style that is inverted from the one here in order to ensure that
     /// the formatted Python code will be valid.
     docstring: Option<QuoteChar>,
+    expr_location: ExprLocation,
 }
 
 impl<'a> PyFormatContext<'a> {
@@ -33,6 +41,7 @@ impl<'a> PyFormatContext<'a> {
             node_level: NodeLevel::TopLevel(TopLevelStatementPosition::Other),
             indent_level: IndentLevel::new(0),
             docstring: None,
+            expr_location: ExprLocation::Other,
         }
     }
 
@@ -86,6 +95,14 @@ impl<'a> PyFormatContext<'a> {
         }
     }
 
+    pub(crate) fn expr_location(&self) -> ExprLocation {
+        self.expr_location
+    }
+
+    pub(crate) fn set_expr_location(&mut self, expr_location: ExprLocation) {
+        self.expr_location = expr_location;
+    }
+
     /// Returns `true` if preview mode is enabled.
     pub(crate) const fn is_preview(&self) -> bool {
         self.options.preview().is_enabled()
@@ -332,3 +349,65 @@ where
             .set_indent_level(self.saved_level);
     }
 }
+
+pub(crate) struct WithExprLocation<'a, B, D>
+where
+    D: DerefMut<Target = B>,
+    B: Buffer<Context = PyFormatContext<'a>>,
+{
+    buffer: D,
+    saved_location: ExprLocation,
+}
+
+impl<'a, B, D> WithExprLocation<'a, B, D>
+where
+    D: DerefMut<Target = B>,
+    B: Buffer<Context = PyFormatContext<'a>>,
+{
+    pub(crate) fn new(expr_location: ExprLocation, mut buffer: D) -> Self {
+        let context = buffer.state_mut().context_mut();
+        let saved_location = context.expr_location();
+
+        context.set_expr_location(expr_location);
+
+        Self {
+            buffer,
+            saved_location,
+        }
+    }
+}
+
+impl<'a, B, D> Deref for WithExprLocation<'a, B, D>
+where
+    D: DerefMut<Target = B>,
+    B: Buffer<Context = PyFormatContext<'a>>,
+{
+    type Target = B;
+
+    fn deref(&self) -> &Self::Target {
+        &self.buffer
+    }
+}
+
+impl<'a, B, D> DerefMut for WithExprLocation<'a, B, D>
+where
+    D: DerefMut<Target = B>,
+    B: Buffer<Context = PyFormatContext<'a>>,
+{
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.buffer
+    }
+}
+
+impl<'a, B, D> Drop for WithExprLocation<'a, B, D>
+where
+    D: DerefMut<Target = B>,
+    B: Buffer<Context = PyFormatContext<'a>>,
+{
+    fn drop(&mut self) {
+        self.buffer
+            .state_mut()
+            .context_mut()
+            .set_expr_location(self.saved_location);
+    }
+}

crates/ruff_python_formatter/src/expression/expr_f_string.rs

@@ -48,6 +48,24 @@ impl NeedsParentheses for ExprFString {
     ) -> OptionalParentheses {
         if self.value.is_implicit_concatenated() {
             OptionalParentheses::Multiline
+        // TODO(dhruvmanila): Ideally what we want here is a new variant which
+        // is something like:
+        // - If the expression fits by just adding the parentheses, then add them and
+        //   avoid breaking the f-string expression. So,
+        //   ```
+        //   xxxxxxxxx = (
+        //       f"aaaaaaaaaaaa { xxxxxxx + yyyyyyyy } bbbbbbbbbbbbb"
+        //   )
+        //   ```
+        // - But, if the expression is too long to fit even with parentheses, then
+        //   don't add the parentheses and instead break the expression at `soft_line_break`.
+        //   ```
+        //   xxxxxxxxx = f"aaaaaaaaaaaa {
+        //       xxxxxxxxx + yyyyyyyyyy
+        //   } bbbbbbbbbbbbb"
+        //   ```
+        // This isn't completely decided yet, refer to the relevant discussion:
+        // https://github.com/astral-sh/ruff/discussions/9785
         } else if AnyString::FString(self).is_multiline(context.source()) {
             OptionalParentheses::Never
         } else {

crates/ruff_python_formatter/src/options.rs

@@ -466,3 +466,12 @@ pub enum PythonVersion {
     Py311,
     Py312,
 }
+
+impl PythonVersion {
+    /// Return `true` if the current version supports [PEP 701].
+    ///
+    /// [PEP 701]: https://peps.python.org/pep-0701/
+    pub fn supports_pep_701(self) -> bool {
+        self >= Self::Py312
+    }
+}

crates/ruff_python_formatter/src/other/bytes_literal.rs

@@ -17,7 +17,7 @@ impl FormatNodeRule<BytesLiteral> for FormatBytesLiteral {
                 Quoting::CanChange,
                 &locator,
                 f.options().quote_style(),
-                f.context().docstring(),
+                f.context(),
                 is_hex_codes_in_unicode_sequences_enabled(f.context()),
             )
             .fmt(f)