bpo-10379: deprecate locale.format in lieu of locale.format_string

Doc/library/locale.rst

@@ -354,6 +354,9 @@ The :mod:`locale` module defines the following exception and functions:
 
 .. function:: format(format, val, grouping=False, monetary=False)
 
+   .. deprecated:: 3.7
+      Use `format_string` instead
+
    Formats a number *val* according to the current :const:`LC_NUMERIC` setting.
    The format follows the conventions of the ``%`` operator.  For floating point
    values, the decimal point is modified if appropriate.  If *grouping* is true,
@@ -366,11 +369,15 @@ The :mod:`locale` module defines the following exception and functions:
    For whole format strings, use :func:`format_string`.
 
 
-.. function:: format_string(format, val, grouping=False)
+.. function:: format_string(format, val, grouping=False, monetary=False)
 
    Processes formatting specifiers as in ``format % val``, but takes the current
    locale settings into account.
 
+   .. versionchanged:: 3.7
+   The *monetary* keyword parameter was added.
+   Replaces :meth:`format`.
+
 
 .. function:: currency(val, symbol=True, grouping=False, international=False)
 

Lib/locale.py

@@ -17,6 +17,7 @@
 import collections
 from builtins import str as _builtin_str
 import functools
+import warnings
 
 # Try importing the _locale module.
 #
@@ -181,12 +182,13 @@ def _strip_padding(s, amount):
                          r'(?P<modifiers>[-#0-9 +*.hlL]*?)[eEfFgGdiouxXcrs%]')
 
 def format(percent, value, grouping=False, monetary=False, *additional):
-    """Returns the locale-aware substitution of a %? specifier
-    (percent).
+    """Deprecated, use format_string instead."""
+    warnings.warn(
+        "This method will be removed in future versions.  "
+        "Use 'locale.format_string()' instead.",
+        DeprecationWarning, stacklevel=2
+    )
 
-    additional is for format strings which contain one or more
-    '*' modifiers."""
-    # this is only for one-percent-specifier strings and this should be checked
     match = _percent_re.match(percent)
     if not match or len(match.group())!= len(percent):
         raise ValueError(("format() must be given exactly one %%char "
@@ -217,10 +219,12 @@ def _format(percent, value, grouping=False, monetary=False, *additional):
             formatted = _strip_padding(formatted, seps)
     return formatted
 
-def format_string(f, val, grouping=False):
+def format_string(f, val, grouping=False, monetary=False):
     """Formats a string in the same way that the % formatting would use,
     but takes the current locale into account.
-    Grouping is applied if the third parameter is true."""
+    Grouping is applied if the third parameter is true.
+    Conversion uses monetary thousands separator and grouping strings if
+    forth parameter monetary is true."""
     percents = list(_percent_re.finditer(f))
     new_f = _percent_re.sub('%s', f)
 
@@ -230,7 +234,7 @@ def format_string(f, val, grouping=False):
             if perc.group()[-1]=='%':
                 new_val.append('%')
             else:
-                new_val.append(format(perc.group(), val, grouping))
+                new_val.append(_format(perc.group(), val, grouping, monetary))
     else:
         if not isinstance(val, tuple):
             val = (val,)
@@ -244,7 +248,7 @@ def format_string(f, val, grouping=False):
                 new_val.append(_format(perc.group(),
                                       val[i],
                                       grouping,
-                                      False,
+                                      monetary,
                                       *val[i+1:i+1+starcount]))
                 i += (1 + starcount)
     val = tuple(new_val)
@@ -262,7 +266,7 @@ def currency(val, symbol=True, grouping=False, international=False):
         raise ValueError("Currency formatting is not possible using "
                          "the 'C' locale.")
 
-    s = format('%%.%if' % digits, abs(val), grouping, monetary=True)
+    s = format_string('%%.%if' % digits, abs(val), grouping, monetary=True)
     # '<' and '>' are markers if the sign must be inserted between symbol and value
     s = '<' + s + '>'
 
@@ -298,7 +302,7 @@ def currency(val, symbol=True, grouping=False, international=False):
 
 def str(val):
     """Convert float to string, taking the locale into account."""
-    return format("%.12g", val)
+    return format_string("%.12g", val)
 
 def delocalize(string):
     "Parses a string as a normalized number according to the locale settings."
@@ -327,7 +331,7 @@ def atoi(string):
 def _test():
     setlocale(LC_ALL, "")
     #do grouping
-    s1 = format("%d", 123456789,1)
+    s1 = format_string("%d", 123456789,1)
     print(s1, "is", atoi(s1))
     #standard formatting
     s1 = str(3.14)

Lib/test/test_locale.py

@@ -3,6 +3,7 @@
 import locale
 import sys
 import codecs
+import warnings
 
 class BaseLocalizedTest(unittest.TestCase):
     #
@@ -197,6 +198,13 @@ def test_padding(self):
         self._test_format("%+10.f", -4200, grouping=0, out='-4200'.rjust(10))
         self._test_format("%-10.f", 4200, grouping=0, out='4200'.ljust(10))
 
+    def test_format_deprecation(self):
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always", DeprecationWarning)
+            locale.format("%-10.f", 4200, grouping=True)
+        for warning in w:
+            self.assertTrue(warning.category is DeprecationWarning)
+
     def test_complex_formatting(self):
         # Spaces in formatting string
         self._test_format_string("One million is %i", 1000000, grouping=1,

Lib/test/test_types.py

@@ -381,16 +381,16 @@ def test_float__format__locale(self):
 
         for i in range(-10, 10):
             x = 1234567890.0 * (10.0 ** i)
-            self.assertEqual(locale.format('%g', x, grouping=True), format(x, 'n'))
-            self.assertEqual(locale.format('%.10g', x, grouping=True), format(x, '.10n'))
+            self.assertEqual(locale.format_string('%g', x, grouping=True), format(x, 'n'))
+            self.assertEqual(locale.format_string('%.10g', x, grouping=True), format(x, '.10n'))
 
     @run_with_locale('LC_NUMERIC', 'en_US.UTF8')
     def test_int__format__locale(self):
         # test locale support for __format__ code 'n' for integers
 
         x = 123456789012345678901234567890
         for i in range(0, 30):
-            self.assertEqual(locale.format('%d', x, grouping=True), format(x, 'n'))
+            self.assertEqual(locale.format_string('%d', x, grouping=True), format(x, 'n'))
 
             # move to the next integer to test
             x = x // 10