Fluent formatting of method chains

crates/ruff_python_formatter/resources/test/fixtures/ruff/fluent.options.json

@@ -0,0 +1 @@
+[{"line_width":8}]

crates/ruff_python_formatter/resources/test/fixtures/ruff/fluent.py

@@ -0,0 +1,35 @@
+# Fixtures for fluent formatting of call chains
+# Note that `fluent.options.json` sets line width to 8
+
+
+x = a.b()
+
+x = a.b().c()
+
+x = a.b().c().d
+
+x = a.b.c.d().e()
+
+x = a.b.c().d.e().f.g()
+
+# Consecutive calls/subscripts are grouped together
+# for the purposes of fluent formatting (though, as 2025.12.15,
+# there may be a break inside of one of these
+# calls/subscripts, but that is unrelated to the fluent format.)
+
+x = a()[0]().b().c()
+
+x = a.b()[0].c.d()[1]().e
+
+# Parentheses affect both where the root of the call
+# chain is and how many calls we require before applying
+# fluent formatting (just 1, in the presence of a parenthesized
+# root, as of 2025.12.15.)
+
+x = (a).b()
+
+x = (a()).b()
+
+x = (a.b()).d.e()
+
+x = (a.b().d).e()

crates/ruff_python_formatter/resources/test/fixtures/ruff/parentheses/call_chains.py

@@ -216,3 +216,69 @@
     .baz()
 )
 
+# Note in preview we split at `pl` which some
+# folks may dislike. (Similarly with common
+# `np` and `pd` invocations).
+#
+# This is because we cannot reliably predict,
+# just from syntax, whether a short identifier
+# is being used as a 'namespace' or as an 'object'.
+#
+# As of 2025.12.15, we do not indent methods in
+# fluent formatting. If we ever decide to do so,
+# it may make sense to special case call chain roots
+# that are shorter than the indent-width (like Prettier does).
+# This would have the benefit of handling these common
+# two-letter aliases for libraries.
+
+
+expr = (
+    pl.scan_parquet("/data/pypi-parquet/*.parquet")
+    .filter(
+        [
+            pl.col("path").str.contains(
+                r"\.(asm|c|cc|cpp|cxx|h|hpp|rs|[Ff][0-9]{0,2}(?:or)?|go)$"
+            ),
+            ~pl.col("path").str.contains(r"(^|/)test(|s|ing)"),
+            ~pl.col("path").str.contains("/site-packages/", literal=True),
+        ]
+    )
+    .with_columns(
+        month=pl.col("uploaded_on").dt.truncate("1mo"),
+        ext=pl.col("path")
+        .str.extract(pattern=r"\.([a-z0-9]+)$", group_index=1)
+        .str.replace_all(pattern=r"cxx|cpp|cc|c|hpp|h", value="C/C++")
+        .str.replace_all(pattern="^f.*$", value="Fortran")
+        .str.replace("rs", "Rust", literal=True)
+        .str.replace("go", "Go", literal=True)
+        .str.replace("asm", "Assembly", literal=True)
+        .replace({"": None}),
+    )
+    .group_by(["month", "ext"])
+    .agg(project_count=pl.col("project_name").n_unique())
+    .drop_nulls(["ext"])
+    .sort(["month", "project_count"], descending=True)
+)
+
+def indentation_matching_for_loop_in_preview():
+    if make_this:
+        if more_nested_because_line_length:
+            identical_hidden_layer_sizes = all(
+            current_hidden_layer_sizes == first_hidden_layer_sizes
+            for current_hidden_layer_sizes in self.component_config[
+                HIDDEN_LAYERS_SIZES
+            ].values().attr
+           )
+
+def indentation_matching_walrus_in_preview():
+    if make_this:
+        if more_nested_because_line_length:
+            with self.read_ctx(book_type) as cursor:
+                if (entry_count := len(names := cursor.execute(
+                    'SELECT name FROM address_book WHERE address=?',
+                    (address,),
+                ).fetchall().some_attr)) == 0 or len(set(names)) > 1:
+                    return
+
+# behavior with parenthesized roots
+x = (aaaaaaaaaaaaaaaaaaaaaa).bbbbbbbbbbbbbbbbbbb.cccccccccccccccccccccccc().dddddddddddddddddddddddd().eeeeeeeeeeee

crates/ruff_python_formatter/src/expression/expr_attribute.rs

@@ -10,6 +10,7 @@ use crate::expression::parentheses::{
     NeedsParentheses, OptionalParentheses, Parentheses, is_expression_parenthesized,
 };
 use crate::prelude::*;
+use crate::preview::is_fluent_layout_split_first_call_enabled;
 
 #[derive(Default)]
 pub struct FormatExprAttribute {
@@ -47,20 +48,26 @@ impl FormatNodeRule<ExprAttribute> for FormatExprAttribute {
                     )
                 };
 
-            if call_chain_layout == CallChainLayout::Fluent {
+            if call_chain_layout.is_fluent() {
                 if parenthesize_value {
                     // Don't propagate the call chain layout.
                     value.format().with_options(Parentheses::Always).fmt(f)?;
                 } else {
                     match value.as_ref() {
                         Expr::Attribute(expr) => {
-                            expr.format().with_options(call_chain_layout).fmt(f)?;
+                            expr.format()
+                                .with_options(call_chain_layout.transition_after_attribute())
+                                .fmt(f)?;
                         }
                         Expr::Call(expr) => {
-                            expr.format().with_options(call_chain_layout).fmt(f)?;
+                            expr.format()
+                                .with_options(call_chain_layout.transition_after_attribute())
+                                .fmt(f)?;
                         }
                         Expr::Subscript(expr) => {
-                            expr.format().with_options(call_chain_layout).fmt(f)?;
+                            expr.format()
+                                .with_options(call_chain_layout.transition_after_attribute())
+                                .fmt(f)?;
                         }
                         _ => {
                             value.format().with_options(Parentheses::Never).fmt(f)?;
@@ -105,8 +112,30 @@ impl FormatNodeRule<ExprAttribute> for FormatExprAttribute {
             // Allow the `.` on its own line if this is a fluent call chain
             // and the value either requires parenthesizing or is a call or subscript expression
             // (it's a fluent chain but not the first element).
-            else if call_chain_layout == CallChainLayout::Fluent {
-                if parenthesize_value || value.is_call_expr() || value.is_subscript_expr() {
+            //
+            // In preview we also break _at_ the first call in the chain.
+            // For example:
+            //
+            // ```diff
+            // # stable formatting vs. preview
+            //  x = (
+            // -    df.merge()
+            // +    df
+            // +    .merge()
+            //      .groupby()
+            //      .agg()
+            //      .filter()
+            //  )
+            // ```
+            else if call_chain_layout.is_fluent() {
+                if parenthesize_value
+                    || value.is_call_expr()
+                    || value.is_subscript_expr()
+                    // Remember to update the doc-comment above when
+                    // stabilizing this behavior.
+                    || (is_fluent_layout_split_first_call_enabled(f.context())
+                        && call_chain_layout.is_first_call_like())
+                {
                     soft_line_break().fmt(f)?;
                 }
             }
@@ -148,8 +177,8 @@ impl FormatNodeRule<ExprAttribute> for FormatExprAttribute {
             )
         });
 
-        let is_call_chain_root = self.call_chain_layout == CallChainLayout::Default
-            && call_chain_layout == CallChainLayout::Fluent;
+        let is_call_chain_root =
+            self.call_chain_layout == CallChainLayout::Default && call_chain_layout.is_fluent();
         if is_call_chain_root {
             write!(f, [group(&format_inner)])
         } else {
@@ -169,7 +198,8 @@ impl NeedsParentheses for ExprAttribute {
             self.into(),
             context.comments().ranges(),
             context.source(),
-        ) == CallChainLayout::Fluent
+        )
+        .is_fluent()
         {
             OptionalParentheses::Multiline
         } else if context.comments().has_dangling(self) {

crates/ruff_python_formatter/src/expression/expr_call.rs

@@ -47,7 +47,10 @@ impl FormatNodeRule<ExprCall> for FormatExprCall {
                 func.format().with_options(Parentheses::Always).fmt(f)
             } else {
                 match func.as_ref() {
-                    Expr::Attribute(expr) => expr.format().with_options(call_chain_layout).fmt(f),
+                    Expr::Attribute(expr) => expr
+                        .format()
+                        .with_options(call_chain_layout.decrement_call_like_count())
+                        .fmt(f),
                     Expr::Call(expr) => expr.format().with_options(call_chain_layout).fmt(f),
                     Expr::Subscript(expr) => expr.format().with_options(call_chain_layout).fmt(f),
                     _ => func.format().with_options(Parentheses::Never).fmt(f),
@@ -67,9 +70,7 @@ impl FormatNodeRule<ExprCall> for FormatExprCall {
         //     queryset.distinct().order_by(field.name).values_list(field_name_flat_long_long=True)
         // )
         // ```
-        if call_chain_layout == CallChainLayout::Fluent
-            && self.call_chain_layout == CallChainLayout::Default
-        {
+        if call_chain_layout.is_fluent() && self.call_chain_layout == CallChainLayout::Default {
             group(&fmt_func).fmt(f)
         } else {
             fmt_func.fmt(f)
@@ -87,7 +88,8 @@ impl NeedsParentheses for ExprCall {
             self.into(),
             context.comments().ranges(),
             context.source(),
-        ) == CallChainLayout::Fluent
+        )
+        .is_fluent()
         {
             OptionalParentheses::Multiline
         } else if context.comments().has_dangling(self) {

crates/ruff_python_formatter/src/expression/expr_lambda.rs

@@ -397,7 +397,8 @@ impl Format<PyFormatContext<'_>> for FormatBody<'_> {
                 body.into(),
                 comments.ranges(),
                 f.context().source(),
-            ) == CallChainLayout::Fluent
+            )
+            .is_fluent()
             {
                 parenthesize_if_expands(&unparenthesized).fmt(f)
             } else {

crates/ruff_python_formatter/src/expression/expr_subscript.rs

@@ -51,7 +51,10 @@ impl FormatNodeRule<ExprSubscript> for FormatExprSubscript {
                 value.format().with_options(Parentheses::Always).fmt(f)
             } else {
                 match value.as_ref() {
-                    Expr::Attribute(expr) => expr.format().with_options(call_chain_layout).fmt(f),
+                    Expr::Attribute(expr) => expr
+                        .format()
+                        .with_options(call_chain_layout.decrement_call_like_count())
+                        .fmt(f),
                     Expr::Call(expr) => expr.format().with_options(call_chain_layout).fmt(f),
                     Expr::Subscript(expr) => expr.format().with_options(call_chain_layout).fmt(f),
                     _ => value.format().with_options(Parentheses::Never).fmt(f),
@@ -71,8 +74,8 @@ impl FormatNodeRule<ExprSubscript> for FormatExprSubscript {
                 .fmt(f)
         });
 
-        let is_call_chain_root = self.call_chain_layout == CallChainLayout::Default
-            && call_chain_layout == CallChainLayout::Fluent;
+        let is_call_chain_root =
+            self.call_chain_layout == CallChainLayout::Default && call_chain_layout.is_fluent();
         if is_call_chain_root {
             write!(f, [group(&format_inner)])
         } else {
@@ -92,7 +95,8 @@ impl NeedsParentheses for ExprSubscript {
                 self.into(),
                 context.comments().ranges(),
                 context.source(),
-            ) == CallChainLayout::Fluent
+            )
+            .is_fluent()
             {
                 OptionalParentheses::Multiline
             } else if is_expression_parenthesized(