A complete summary of format-specifiers in Python

Summary of Format Specification.md

Format strings (str.format() or format(), extended to f-strings and t-strings) are based off of format specification mini-language which is made up of replacement fields where values are substituted in.

• Replacement fields are surrounded with {} ({} itself is escaped with {{}}), and begin with a field name, optionally followed by a conversion field (preceded by !), and a format specification (preceded by :).
• A field name consists of an argument name, which is a number or an identifier (specifying the kwarg), and infinitely nested attribute accesses (e.g. .a.b.c), indexing ([0][1][2]), or a combination of the two (e.g. [0].a[1].b[2].c).
  • If a format string consists only of numbers in sequence (excluding attribute access and indexing), they could be omitted.
• A conversion field is used if the str() value (!s), or a repr() value (!r) is needed.
• A format specification is used to format the value in a specific manner; its syntax is summarised as. [options][width][integral_grouping][[precision]fractional_grouping][type]
  • Although most types adhere to a common syntax, a type is free to define its own specification.
  • These could have replacement fields within themselves (e.g. for dynamic fill character/width).
  • It consists of a type, preceded by width and precision modifiers, preceded by fill, align and sign modifiers.
  • Options control several auxiliary aspects for formatting; its syntax is summarised as [[fill]align][sign]['z']['#']['0'].
    • Alignment may be left-justified (<), right-justified (>), or centred (^) within specified width.
      • Numbers are right-justified by default, other types are left-justified.
      • If a fill value precedes alignment, it's used instead of spaces.
    • Sign may be always-present (+), present for negatives (-), or left blank for positives ( ).
    • Negative zeroes — used for floating point calculations involving infinities, having no mathematical meaning — are coerced into positive with z.
    • Alternate form is used with #, which for certain representation of numeric types differ.
      • 0b, 0x/0X, or 0o prepended to binary, hex, or octal format of an integer.
      • A decimal point always following of an float or complex number.
    • Sign-aware zero padding (i.e. zero padded from sign upto first numeral) is enabled with 0 for all numeric types, except complex numbers.
  • Width controls the minimum field width excluding prefixes, separators, and other formatting characters; if left unspecified, it's not considered.
  • Precision controls formatting depending on the type of format.
    • Number of decimal digits after radix for float format (f/F).
    • Number of decimal digits before and after radix for general format (g/G).
    • Maximum number of characters for other formats.
    • Important: It is illegal for integer formats, and will raise an error.
  • Both width and precision maybe followed by grouping specifier , and _.
    • If after width, applies to the integral part.
    • If after precision, applies to the fractional part; precision is optional.
    • , inserts commas every three digits.
    • _ inserts underscores every three digits for decimal format, but every four digits for binary, hex or octal format.
  • Types controls the data format; following formats — integer, float and string — are available:

    • String format is either s or nothing.

    • Integer formats available:

      Specifier	Semantics
      b	Binary format.
      c	Character; same as chr().
      d	Decimal format.
      o	Octal format.
      x	Hex format; lower-case letters for digits A-F.
      X 1	Hex format; upper-case letters for digits A-F.
      n 2	Locale-aware number. 2
      None	Same as d.

    • Decimal formats available (float has an implicit precision of 6):

      Specifier	Semantics
      e / E	Scientific notation; exactly precision plus one significant digits, followed by an exponent, separated with an e/E.
      f / F	Fixed-point notation; exactly precision digits after decimal point.
      g / G 3	General notation; rounds to precision significant digits, automatically chooses f or g based on its magnitude.
      n 4	Locale-aware decimal number.
      %	Percentage; same as f, but multiplied prior by 100, followed by a % sign.
      None	Similar to g, except in fixed-point notation, at least one digit follows the decimal point.

    • For complex types, real and imaginary components are formatted individually according to decimal format specified (% not allowed). If nothing specified, then in addition to decimal format rules for floats, complex numbers are wrapped in parenthesis.

Footnotes

1. In case # is specified, the prefix 0x will be upper-cased to 0X as well. ↩

2. Same as d, except digit group separators are based on current-locale, and not on the format-specification. ↩ ↩²

3. Insignificant trailing zeros are removed from the significand, and the decimal point is also removed if there are no remaining digits following it, unless # is present. ↩

4. Same as d, except digit group separators for the integral part are based on current-locale, and not on the format-specification. ↩