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

Doc/library/locale.rst

@@ -365,12 +365,26 @@ The :mod:`locale` module defines the following exception and functions:
  Please note that this function will only work for exactly one %char specifier.
  For whole format strings, use :func:`format_string`.
 
+ .. deprecated:: 3.7
+ Use :meth:`format_string` instead
 
-.. function:: format_string(format, val, grouping=False)
+
+.. function:: format_string(format, val, grouping=False, monetary=False)
+
+ 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,
+ also takes the grouping into account.
+
+ If *monetary* is true, the conversion uses monetary thousands separator and
+ grouping strings.
 
  Processes formatting specifiers as in ``format % val``, but takes the current
  locale settings into account.
 
+ .. versionchanged:: 3.7
+ The *monetary* keyword parameter was added.
+
 
 .. function:: currency(val, symbol=True, grouping=False, international=False)
 

Doc/whatsnew/3.7.rst

@@ -97,6 +97,14 @@ New Modules
 Improved Modules
 ================
 
+locale
+------
+
+Added another argument *monetary* in :meth:`format_string` of :mod:`locale`.
+If *monetary* is true, the conversion uses monetary thousands separator and
+grouping strings.
+(Contributed by Garvit in :issue:`10379`.)
+
 os
 --
 
@@ -169,6 +177,9 @@ Deprecated
  ``0x03050400`` and ``0x03060000`` (not including) or ``0x03060100`` or
  higher. (Contributed by Serhiy Storchaka in :issue:`27867`.)
 
+- Deprecated :meth:`format` from :mod:`locale`, use the :meth:`format_string`
+ instead. (Contributed by Garvit in :issue:`10379`.)
+
 - Methods
  :meth:`MetaPathFinder.find_module() <importlib.abc.MetaPathFinder.find_module>`
  (replaced by

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,10 @@ 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 self.assertWarns(DeprecationWarning):
+ locale.format("%-10.f", 4200, grouping=True)
+
  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