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

picnixz · web-flow · commit b5febf73b9b0 · 2025-05-16T18:36:48.000Z
diff --git a/Lib/string/__init__.py b/Lib/string/__init__.py
@@ -264,22 +264,18 @@ def _vformat(self, format_string, args, kwargs, used_args, recursion_depth,
 
         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,34 +288,32 @@ def convert_field(self, value, conversion):
             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:
             if is_attr:
                 obj = getattr(obj, i)
             else:
                 obj = obj[i]
-
         return obj, first
