F-String Formatting Style

[dhruvmanila]

This document provides examples to initiate a discussion on formatting f-strings, particularly the expression part, which can now be broken into multiple lines as of Python 3.12.

The main decision which needs to be taken is when to add line breaks within the replacement field of f-strings, especially when either or all of the following are present:

1. Conversion flag
2. Format specifier
3. Parentheses

Another important one is regarding quotes. Now that we’re allowed to re-use the same quotation style in f-strings, should the same quote be used throughout the f-string?

Black's implementation (WIP): psf/black#3822
Ruff's implementation (WIP): #9642

Tagging some folks to initiate a conversation to keep the style compatible with Black @tusharsadhwani @ambv

---

Examples:

This can be best discussed with various examples:

1

A simple expression containing a comment right after the opening curly braces.

x = f"aaaaa {  # comment
    bbbbb } ccccc"

Possible formatting style:

x = f"aaaaa {  # comment
    bbbbb
} ccccc"

2

Taking the example from above and adding a few additional comments:

x = f"aaa {  # comment 1
    # comment 2
    bbb
}"

And some more:

x = f"aaa {  # comment 1
    # comment 2
    bbb  # comment 3
    # comment 4
}"  # comment 5

The code snippets in (2) illustrate the preferred style for formatting f-strings with comments.

3

When there are more than 1 replacement field and the f-string exceeds the line-length

x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"

Should we only break the expression from left to right?

x = f"aaaaaaaaaaaa {
    bbbbbbbbbbbbbb
} cccccccccccccccccccc { ddddddddddddddd } eeeeeeeeeeeeee"

Or, break it from right to left?

x = f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc {
	ddddddddddddddd
} eeeeeeeeeeeeee"

Or, both expressions?

x = f"aaaaaaaaaaaa {
    bbbbbbbbbbbbbb
} cccccccccccccccccccc {
    ddddddddddddddd
} eeeeeeeeeeeeee"

And, should this be parenthesized?

x = (
    f"aaaaaaaaaaaa {
        bbbbbbbbbbbbbb
    } cccccccccccccccccccc {
        ddddddddddddddd
    } eeeeeeeeeeeeee"
)

4

When the expression is either a dictionary or set, then we need to surround the expression with an additional whitespace to not escape the curly brace. But, this is only to be done if the expression doesn’t fit on the line.

x = f"aaaaa { {'bbb', 'ccc', 'ddd'}} eeeee"

Here, we need to preserve the whitespace between the opening curly brace of the replacement field and the set otherwise it behaves as escaping the opening curly braces. The question is whether to add a whitespace before the closing curly braces for consistency?

x = f"aaaaa { {'bbb', 'ccc', 'ddd'} } eeeee"
#            ^                     ^ Should we add this?
#            This needs to
#            be preserved

5

When the expression is a collection exceeding the line-length

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { [ 'aaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbb', 'ccccccccccccccccccc', 'dddddddddddddddd', 'eeeeeeeeeeeeeee', ] } ddddddddddddd"

Should we break it twice? This means to break at both { and [.

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa {
    [
        'aaaaaaaaaaaaaaa',
        'bbbbbbbbbbbbbbbbbbb',
        'ccccccccccccccccccc',
        'dddddddddddddddd',
        'eeeeeeeeeeeeeee',
    ]
} ddddddddddddd"

Or, hug the parentheses as done in the preview style?

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa {[
    'aaaaaaaaaaaaaaa',
    'bbbbbbbbbbbbbbbbbbb',
    'ccccccccccccccccccc'
    'dddddddddddddddd',
    'eeeeeeeeeeeeeee',
]} ddddddddddddd"

6

If the conversion flag is present, should it always be right after the expression or can it go to another line? I think it should be the former, even in the case the expression breaks into multiple lines like the example shown above. So,

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbb'!r } ccccccccccccccc"

Not breaking before the conversion flag:

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa {
	'bbbbbbbbbbbbbbbbbbbbbbbbbbbbb'!r
} ccccccccccccccc"

But, if there’s a collection instead:

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa {
	[
        'aaaaaaaaaaaaaaa',
        'bbbbbbbbbbbbbbbbbbb',
        'ccccccccccccccccccc',
    ]!r
} ddddddddddddd"

7

Should we break before the : token if format spec is present and the f-string breaks across multiple lines with expression? This would be a bit similar to formatting a slice expression.

x = f"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa { "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + "cccccccccccccc" + "dddddddddddddddddddddd" + "eeeeeeeeeeeeee":>10 } ccccccccccccccc"

Should the above be formatted as the following? The downside here is that it’s difficult to notice the format specifier otherwise.

x = f'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa {
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + "cccccccccccccc" + "dddddddddddddddddddddd" + "eeeeeeeeeeeeee":>10 
} ccccccccccccccc'

Or,

x = f'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa {
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + "cccccccccccccc" + "dddddddddddddddddddddd" + "eeeeeeeeeeeeee"
	:>10 
} ccccccccccccccc'

Note that whitespaces aren’t allowed in the format spec. Here, the line break is allowed because the newline character ends the format specifier. This creates an interesting code snippet which is valid during parsing and runtime:

f"{  # comment 1
	foo:>2
	# comment 2
}"

Here, the comment 2 is actually a valid comment. But, if it’s placed right after the format specifier, then it’s invalid and will be part of the format specifier as a string. This is because of #7787.

8

Should we re-use the same quotes throughout the f-string?

f"first {f"second" + "third"} fourth"

---

Self-documenting expression

When self-documenting expressions are present in an f-string (= after an expression), then all whitespace needs to be preserved which means the formatter shouldn’t take any decisions at all. But, we can still normalize whitespace / format the conversion flag and format spec because that isn’t used in the string value. For example,

print(f"{x   =   !s
         :>0

         }")

We can format the above as:

print(f"{x   =   !s:>0}")

Because both are equivalent. And, whitespace isn’t allowed in the format specifier otherwise it raises a ValueError with the message “Space not allowed in string format specifier”.

Another question here is whether to preserve whitespace for nested f-strings when a self-documenting expression is present in the parent f-string. For example,

>>> x = 1
>>> print(
...     f"""
... {
...     (f"{x    }") =
...  }"""
... )

    (f"{x    }") =
 '1'

Here, the whitespace in the nested f-string is preserved in the output (f”{x }”) but if there’s a comment or newline, then we get unexpected output:

>>> x = 1
>>> print(
...     f"""
... {
...     f"{x
... 
... 
... 
...        # comment
...        }" =
...  }"""
... )

    f"{x
 '1'

Here, the newlines and comment after the nested f-string (f”{x) isn’t preserved in the output.

With that, I think we should stop formatting the current f-string once we encounter a self-documenting expression.

[Eutropios]

I think it would be useful to also see how yapf (google/yapf#1136) and autopep8 (hhatto/autopep8#712) decide to implement this formalization.

[Avasam]

Speaking of autopep8, I've been tracking how close Ruff is to full parity with its autofixes: #9057

[dhruvmanila]

Style decision: Indentation

What should be the indentation level of the expression part of an f-string? The problem here is that the formatter can't push the { for alignment as otherwise it would mean adding whitespace in the string value of the f-string. But, it can push the } as it's all expression before it.

For example:

if indent0:
    if indent1:
        if indent2:
            foo = f"""
# Heading
--------- {
    [
        "aaaaaaaaaaaaaaaaaaaaa",
        "bbbbbbbbbbbbbbbbbbbbb",
        "ccccccccccccccccccccc",
        "ddddddddddddddddddddd"
    ]
} ----------
"""

1

Should it be relative to the enclosing node?

if indent0:
    if indent1:
        if indent2:
            foo = f"""
# Heading
--------- {
                [
                    "aaaaaaaaaaaaaaaaaaaaa",
                    "bbbbbbbbbbbbbbbbbbbbb",
                    "ccccccccccccccccccccc",
                    "ddddddddddddddddddddd",
                ]
            } ----------
"""

2

Should it be relative to the opening curly brace? This is problematic because the opening curly brace could be at a position which is not in multiples of 4 as there's text before it.

if indent0:
    if indent1:
        if indent2:
            foo = f"""
# heading
--------- {
      [
          "aaaaaaaaaaaaaaaaaaaaa",
          "bbbbbbbbbbbbbbbbbbbbb",
          "ccccccccccccccccccccc",
          "ddddddddddddddddddddd",
      ]
  } ----------
"""

3

Should it be always be an absolute 4 space indent from line start?

if indent0:
    if indent1:
        if indent2:
            foo = f"""
# heading
--------- {
    [
        "aaaaaaaaaaaaaaaaaaaaa",
        "bbbbbbbbbbbbbbbbbbbbb",
        "ccccccccccccccccccccc",
        "ddddddddddddddddddddd",
    ]
} ----------
"""

Real world example: https://github.com/python-poetry/poetry/blob/f49f3ee838379c26790dda60893ff51ab431e975/tests/packages/test_locker.py#L1162-L1190

[MichaReiser]

You probably run into issues with option 3 when you have nested f-strings. Do you know how other formatters handle the indent?

[dhruvmanila]

I'm sorry but I'm unable to figure out what kind of issues are you referring to?

For example, it's always 4 space indent no matter the nesting level. The indent is relative to the start of the line.

if indent0:
    if indent1:
        if indent2:
            foo = f"""
# Heading
--------- {
    f"aaaaaaa {
    [
        "aaaaaaaaaaaaaaaaaaaaa",
        "bbbbbbbbbbbbbbbbbbbbb",
        "ccccccccccccccccccccc",
        "ddddddddddddddddddddd"
    ]
} bbbbbbbb" +
    [
        "aaaaaaaaaaaaaaaaaaaaa",
        "bbbbbbbbbbbbbbbbbbbbb",
        "ccccccccccccccccccccc",
        "ddddddddddddddddddddd"
    ]
} ----------
"""

Do you know how other formatters handle the indent?

I don't think any formatters implement f-string formatting ;)
Or, are you referring to any formatter outside the Python ecosystem?

[MichaReiser]

Your example demonstrates the problem. It's no longer recognizable which fstring element the } closes

I'm referring to other formatters implementing formatting of string interpolation expressions

[dhruvmanila]

Oh I see. You mean a problem in the style and not an issue in implementing the said style.

I'm referring to other formatters implementing formatting of string interpolation expressions

Prettier is doing a mix of (1) and (2). Basically, it looks at closest expression indent - it could be from the parent assignment statement (foo) or the inner replacement field ({).

This actually makes sense. Currently, we do (1). The only downside of mixing (2) is that the indent is not necessarily going to be in multiples of indent width then. For example:

if indent0:
    if indent1:
        if indent2:
            foo = f"""hello world
hello {
          f"aaaaaaa {
              [
                  'aaaaaaaaaaaaaaaaaaaaa',
                  'bbbbbbbbbbbbbbbbbbbbb',
                  'ccccccccccccccccccccc',
                  'ddddddddddddddddddddd'
              ]
          } bbbbbbbb"
          + [
              'aaaaaaaaaaaaaaaaaaaaa',
              'bbbbbbbbbbbbbbbbbbbbb',
              'ccccccccccccccccccccc',
              'ddddddddddddddddddddd'
          ]
      } --------
"""

Notice that the indentation of the inner f-string is relative to the opening curly brace on the previous line.

[JelleZijlstra]

Since this was brought up in psf/black#3822 (comment), here are my opinions, going over the examples in the OP:

1. Your proposed formatting seems fine.
2. Seems fine too except I don't see why you use an 8-space indent. Should be 4-space.
3. I think putting line breaks inside the expression part always looks weird and you shouldn't do it. I would want to format this as something like:

x = (
    f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc"
    f" { ddddddddddddddd } eeeeeeeeeeeeee"
)

However, it's hard for a formatter to decide on exact line breaks, so in Black I'd leave this up to users to do.

4. Adding whitespace on both sides looks nicer to me.

5. As above, I wouldn't break this into lines at all. I would make hugging here consistent with the preview style (i.e., hug only if you'd hug in the corresponding function call). Your second codeblock here has the [ overindented; I assume that's a typo.
   6, 7. The format specifier cannot have a newline after it, because that means the newline goes into the format spec string, and common types (e.g. int.__format__) will reject that newline. I think that means you have to preserve the way the user wrote the format spec. For consistency, I'd also recommend putting conversion specifiers (!r) immediately before the closing brace.

6. I would prefer to alternate quote styles as long as possible; it's easier for humans to read.

Self-documenting expressions section: You actually can't normalize whitespace in the format spec either, because that can affect behavior. See psf/black#4112 (comment).

[JelleZijlstra]

And one more thought: it's good that Ruff is also a linter, because most of the examples we're discussing are terrible code and a linter should probably flag them :D

[dhruvmanila]

Thanks for your valuable feedback! This is really helpful.

2. Seems fine too except I don't see why you use an 8-space indent. Should be 4-space.

It must be a typo. It should probably be fixed now.

3. I think putting line breaks inside the expression part always looks weird and you shouldn't do it. I would want to format this as something like:

x = (
    f"aaaaaaaaaaaa { bbbbbbbbbbbbbb } cccccccccccccccccccc"
    f" { ddddddddddddddd } eeeeeeeeeeeeee"
)

However, it's hard for a formatter to decide on exact line breaks, so in Black I'd leave this up to users to do.

Regarding line breaks, what our current heuristic is that if any of the expression in an f-string is multiline (containing line breaks), this signals to the formatter that it can break expressions. This means that breaking expressions inside f-string is in the control of the programmer. This is similar to how Prettier does it for JavaScript's template literals (https://prettier.io/docs/en/next/rationale.html#template-literals).

5. As above, I wouldn't break this into lines at all. I would make hugging here consistent with the preview style (i.e., hug only if you'd hug in the corresponding function call). Your second codeblock here has the [ overindented; I assume that's a typo.

Yes, that's a typo. I agree with the hugging point here which is yet to be implemented.

6, 7. The format specifier cannot have a newline after it, because that means the newline goes into the format spec string, and common types (e.g. int.__format__) will reject that newline. I think that means you have to preserve the way the user wrote the format spec.

Oh I see. Thanks for noticing that. We'd need to fix it. This would basically mean that we shouldn't add any newlines in the expression part as well if the format specifier is present because that doesn't look consistent. So, the following should collapse the expression:

f"""foo {
    xxxxxxx:.3f}"""

For consistency, I'd also recommend putting conversion specifiers (!r) immediately before the closing brace.

It seems that there can't be any line breaks after the conversion flag for pre 3.12 versions even in triple-quoted strings:

f"""aaaaaa {
    foo!s
} bbbbb"""

Which seems inconsistent because it's valid without the conversion flag:

f"""aaaaaa {
    foo
} bbbbb"""

I need to fix this as well.

6. I would prefer to alternate quote styles as long as possible; it's easier for humans to read.

Yeah, I think so as well.

Self-documenting expressions section: You actually can't normalize whitespace in the format spec either, because that can affect behavior. See psf/black#4112 (comment).

Oh I see. This is interesting.