f-strings and the format specification mini-language: the details that bite

What it is

An f-string evaluates each expression inside braces at run time and formats it through the same machinery as str.format: an optional conversion (!r, !s, !a) followed by a format spec after a colon, [[fill]align][sign][z][#][0][width][grouping][.precision][type]. The debug specifier = (f"{x=}", Python 3.8) prints the expression text and its repr, preserving any whitespace around the sign. Since 3.12 (PEP 701) the expression part may reuse the enclosing quote, contain backslashes and comments, and span lines. A spec may itself contain replacement fields, so f"{name:>{width}}" takes the width from a variable.

Why it matters

Formatting is where numbers become text in logs, reports and files. A spec mistake produces plausible but wrong output, and the same source can be a syntax error on an older interpreter.

How to apply

• Format floats explicitly: .3f for fixed decimals, .3g for significant digits. The documentation states that with no type, a float is shown like g, except that fixed-point output always keeps at least one digit after the point and the precision defaults to whatever represents the value faithfully.
• Group thousands with , or _ (f"{n:,}"); use n only with a deliberately set locale, since the documentation notes the default locale is not the system locale.
• Zero-pad numbers with f"{n:05d}"; the documentation states that a leading 0 enables sign-aware zero-padding for numeric types and, since 3.10, no longer affects string alignment.
• Show ratios with .1%, which multiplies by 100 and appends the percent sign.
• Use !r for values that may be empty or contain whitespace (f"got {value!r}") so the quotes are visible.
• Write literal braces as {{ and }}.
• In logging calls pass arguments lazily (log.debug("x=%s", x)); an f-string argument is evaluated even when the level is disabled.

Pitfalls

f"{s:.10}" truncates a string to ten characters: for strings, precision is the maximum field size, which is easy to write by accident when a width was meant. Rounding does not remove the sign of a small negative: f"{-0.0001:.2f}" gives -0.00; the z option (3.11) coerces negative zero to positive zero after rounding. Formatting does not repair binary floating point: f"{2.675:.2f}" prints 2.67 because the stored value lies just below 2.675 (see the floating-point article); a Decimal formats from its exact digits under the decimal context's rounding mode. f"{x = }" keeps the spaces in the output. Nested quotes of the same kind and backslashes inside braces are errors on 3.11 and older, so a library that supports those versions must avoid them.