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.

• Template strings are a simpler method of string substitution with a placeholder syntax similar to UNIX shells.

  • $identifier or ${identifier} as used as placeholders, and $$ is used to escape a $.
  • identifier could be any case-insensitive ASCII alphanumeric string (with underscores).
  • string.Template() is used to instantiate a template, and its .substitute() or .safe_substitute() method is used to interpolate in the values of the placeholders.
    • .substitute(mapping={}, /, **kwds) method could be provided a dict-like object containing the placeholders as keys with corresponding values, or keyword arguments where keywords are placeholders.
      • If both keyword arguments and dictionary are provided, keyword arguments override dictionary.
      • Upon encountering invalid/missing placeholders, or spurious $ raises a KeyError or ValueError respectively.
    • .safe_substitute() method is similar to .substitute() leaves invalid/missing identifier and spurious $ as is without raising errors.
    • .is_valid() maybe called beforehand to verify the correctness of the template before substitution occurs.
    • .get_identifiers() returns a list of placeholder names, which maybe needed in some scenarios.

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. ↩