[3.12] gh-122767: document "new style" formatting for complexes (GH-122848) (#126129)

gh-122767: document "new style" formatting for complexes (GH-122848)

(cherry picked from commit 0bbbe15)

Co-authored-by: Sergey B Kirpichev <[email protected]>
Co-authored-by: Bénédikt Tran <[email protected]>

Author: 3 people

Doc/library/string.rst

@@ -350,8 +350,9 @@ The meaning of the various alignment options is as follows:
 | ``'='`` | Forces the padding to be placed after the sign (if any)  |
 |         | but before the digits.  This is used for printing fields |
 |         | in the form '+000000120'. This alignment option is only  |
-|         | valid for numeric types.  It becomes the default for     |
-|         | numbers when '0' immediately precedes the field width.   |
+|         | valid for numeric types, excluding :class:`complex`.     |
+|         | It becomes the default for numbers when '0' immediately  |
+|         | precedes the field width.                                |
 +---------+----------------------------------------------------------+
 | ``'^'`` | Forces the field to be centered within the available     |
 |         | space.                                                   |
@@ -432,9 +433,9 @@ including any prefixes, separators, and other formatting characters.
 If not specified, then the field width will be determined by the content.
 
 When no explicit alignment is given, preceding the *width* field by a zero
-(``'0'``) character enables
-sign-aware zero-padding for numeric types.  This is equivalent to a *fill*
-character of ``'0'`` with an *alignment* type of ``'='``.
+(``'0'``) character enables sign-aware zero-padding for numeric types,
+excluding :class:`complex`.  This is equivalent to a *fill* character of
+``'0'`` with an *alignment* type of ``'='``.
 
 .. versionchanged:: 3.10
    Preceding the *width* field by ``'0'`` no longer affects the default
@@ -588,6 +589,15 @@ The available presentation types for :class:`float` and
    |         | as altered by the other format modifiers.                |
    +---------+----------------------------------------------------------+
 
+The available presentation types for :class:`complex` are the same as those for
+:class:`float` (``'%'`` is not allowed).  Both the real and imaginary components
+of a complex number are formatted as floating-point numbers, according to the
+specified presentation type.  They are separated by the mandatory sign of the
+imaginary part, the latter being terminated by a ``j`` suffix.  If the presentation
+type is missing, the result will match the output of :func:`str` (complex numbers with
+a non-zero real part are also surrounded by parentheses), possibly altered by
+other format modifiers.
+
 
 .. _formatexamples: