Issue #23671: string.Template now allows to specify the "self" parameter as

serhiy-storchaka · serhiy-storchaka · commit b876df4cbb0b · 2015-03-24T22:30:46.000+02:00
keyword argument.  string.Formatter now allows to specify the "self" and
the "format_string" parameters as keyword arguments.
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
@@ -95,6 +95,10 @@ implementation as the built-in :meth:`format` method.
       an arbitrary set of positional and keyword arguments.
       :meth:`format` is just a wrapper that calls :meth:`vformat`.
 
+      .. deprecated:: 3.5
+         Passing a format string as keyword argument *format_string* has been
+         deprecated.
+
    .. method:: vformat(format_string, args, kwargs)
 
       This function does the actual work of formatting.  It is exposed as a
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
@@ -526,6 +526,10 @@ Deprecated Python modules, functions and methods
   :func:`~http.cookies.Morsel.set` method in order to avoid the deprecation
   warning.
 
+* Passing a format string as keyword argument *format_string* to the
+  :meth:`~string.Formatter.format` method of the :class:`string.Formatter`
+  class has been deprecated.
+
 
 Deprecated functions and types of the C API
 -------------------------------------------
diff --git a/Lib/string.py b/Lib/string.py
@@ -94,7 +94,11 @@ def _invalid(self, mo):
         raise ValueError('Invalid placeholder in string: line %d, col %d' %
                          (lineno, colno))
 
-    def substitute(self, *args, **kws):
+    def substitute(*args, **kws):
+        if not args:
+            raise TypeError("descriptor 'substitute' of 'Template' object "
+                            "needs an argument")
+        self, *args = args  # allow the "self" keyword be passed
         if len(args) > 1:
             raise TypeError('Too many positional arguments')
         if not args:
@@ -120,7 +124,11 @@ def convert(mo):
                              self.pattern)
         return self.pattern.sub(convert, self.template)
 
-    def safe_substitute(self, *args, **kws):
+    def safe_substitute(*args, **kws):
+        if not args:
+            raise TypeError("descriptor 'safe_substitute' of 'Template' object "
+                            "needs an argument")
+        self, *args = args  # allow the "self" keyword be passed
         if len(args) > 1:
             raise TypeError('Too many positional arguments')
         if not args:
@@ -160,7 +168,22 @@ def convert(mo):
 # The field name parser is implemented in _string.formatter_field_name_split
 
 class Formatter:
-    def format(self, format_string, *args, **kwargs):
+    def format(*args, **kwargs):
+        if not args:
+            raise TypeError("descriptor 'format' of 'Formatter' object "
+                            "needs an argument")
+        self, *args = args  # allow the "self" keyword be passed
+        try:
+            format_string, *args = args # allow the "format_string" keyword be passed
+        except ValueError:
+            if 'format_string' in kwargs:
+                format_string = kwargs.pop('format_string')
+                import warnings
+                warnings.warn("Passing 'format_string' as keyword argument is "
+                              "deprecated", DeprecationWarning, stacklevel=2)
+            else:
+                raise TypeError("format() missing 1 required positional "
+                                "argument: 'format_string'") from None
         return self.vformat(format_string, args, kwargs)
 
     def vformat(self, format_string, args, kwargs):
diff --git a/Lib/test/test_pep292.py b/Lib/test/test_pep292.py
@@ -26,6 +26,7 @@ def test_regular_templates(self):
         self.assertEqual(s.substitute(dict(who='tim', what='ham')),
                          'tim likes to eat a bag of ham worth $100')
         self.assertRaises(KeyError, s.substitute, dict(who='tim'))
+        self.assertRaises(TypeError, Template.substitute)
 
     def test_regular_templates_with_braces(self):
         s = Template('$who likes ${what} for ${meal}')
@@ -198,6 +199,9 @@ def test_keyword_arguments(self):
         eq(s.substitute(dict(mapping='one'), mapping='two'),
            'the mapping is two')
 
+        s = Template('the self is $self')
+        eq(s.substitute(self='bozo'), 'the self is bozo')
+
     def test_keyword_arguments_safe(self):
         eq = self.assertEqual
         raises = self.assertRaises
@@ -216,6 +220,9 @@ def test_keyword_arguments_safe(self):
         raises(TypeError, s.substitute, d, {})
         raises(TypeError, s.safe_substitute, d, {})
 
+        s = Template('the self is $self')
+        eq(s.safe_substitute(self='bozo'), 'the self is bozo')
+
     def test_delimiter_override(self):
         eq = self.assertEqual
         raises = self.assertRaises
diff --git a/Lib/test/test_string.py b/Lib/test/test_string.py
@@ -31,6 +31,21 @@ def test_basic_formatter(self):
         self.assertEqual(fmt.format("foo"), "foo")
         self.assertEqual(fmt.format("foo{0}", "bar"), "foobar")
         self.assertEqual(fmt.format("foo{1}{0}-{1}", "bar", 6), "foo6bar-6")
+        self.assertRaises(TypeError, fmt.format)
+        self.assertRaises(TypeError, string.Formatter.format)
+
+    def test_format_keyword_arguments(self):
+        fmt = string.Formatter()
+        self.assertEqual(fmt.format("-{arg}-", arg='test'), '-test-')
+        self.assertRaises(KeyError, fmt.format, "-{arg}-")
+        self.assertEqual(fmt.format("-{self}-", self='test'), '-test-')
+        self.assertRaises(KeyError, fmt.format, "-{self}-")
+        self.assertEqual(fmt.format("-{format_string}-", format_string='test'),
+                         '-test-')
+        self.assertRaises(KeyError, fmt.format, "-{format_string}-")
+        with self.assertWarnsRegex(DeprecationWarning, "format_string"):
+            self.assertEqual(fmt.format(arg='test', format_string="-{arg}-"),
+                             '-test-')
 
     def test_auto_numbering(self):
         fmt = string.Formatter()
diff --git a/Misc/NEWS b/Misc/NEWS
@@ -30,6 +30,10 @@ Core and Builtins
 Library
 -------
 
+- Issue #23671: string.Template now allows to specify the "self" parameter as
+  keyword argument.  string.Formatter now allows to specify the "self" and
+  the "format_string" parameters as keyword arguments.
+
 - Issue #23502: The pprint module now supports mapping proxies.
 
 - Issue #17530: pprint now wraps long bytes objects and bytearrays.
