gh-134082: modernize docstrings in `string.Formatter` (#134083)

diff --git a/Lib/string/__init__.py b/Lib/string/__init__.py
index eab5067c9b133ea1210efacd92eb5f69c2336236..b7782e042b94eb00436255b7a7ac7c496c740e8b 100644 (file)
--- a/Lib/string/__init__.py
+++ b/Lib/string/__init__.py
@@ -264,22 +264,18 @@ class Formatter:
 
         return ''.join(result), auto_arg_index
 
-
     def get_value(self, key, args, kwargs):
         if isinstance(key, int):
             return args[key]
         else:
             return kwargs[key]
 
-
     def check_unused_args(self, used_args, args, kwargs):
         pass
 
-
     def format_field(self, value, format_spec):
         return format(value, format_spec)
 
-
     def convert_field(self, value, conversion):
         # do any conversion on the resulting object
         if conversion is None:
@@ -292,28 +288,27 @@ class Formatter:
             return ascii(value)
         raise ValueError("Unknown conversion specifier {0!s}".format(conversion))
 
-
-    # returns an iterable that contains tuples of the form:
-    # (literal_text, field_name, format_spec, conversion)
-    # literal_text can be zero length
-    # field_name can be None, in which case there's no
-    #  object to format and output
-    # if field_name is not None, it is looked up, formatted
-    #  with format_spec and conversion and then used
     def parse(self, format_string):
-        return _string.formatter_parser(format_string)
+        """
+        Return an iterable that contains tuples of the form
+        (literal_text, field_name, format_spec, conversion).
 
 
-    # given a field_name, find the object it references.
-    #  field_name:   the field being looked up, e.g. "0.name"
-    #                 or "lookup[3]"
-    #  used_args:    a set of which args have been used
-    #  args, kwargs: as passed in to vformat
+        *field_name* can be None, in which case there's no object
+        to format and output; otherwise, it is looked up and
+        formatted with *format_spec* and *conversion*.
+        """
+        return _string.formatter_parser(format_string)
+
     def get_field(self, field_name, args, kwargs):
-        first, rest = _string.formatter_field_name_split(field_name)
+        """Find the object referenced by a given field name.
 
+        The field name *field_name* can be for instance "0.name"
+        or "lookup[3]". The *args* and *kwargs* arguments are
+        passed to get_value().
+        """
+        first, rest = _string.formatter_field_name_split(field_name)
         obj = self.get_value(first, args, kwargs)
-
         # loop through the rest of the field_name, doing
         #  getattr or getitem as needed
         for is_attr, i in rest:
@@ -321,5 +316,4 @@ class Formatter:
                 obj = getattr(obj, i)
             else:
                 obj = obj[i]
-
         return obj, first