gh-94226: Remove the locale.format() function (#94229)

Remove the locale.format() function, deprecated in Python
3.7: use locale.format_string() instead.

Remove TestFormatPatternArg test case: it is irrelevant for
locale.format_string() which accepts complex formats.

Author: vstinner

Doc/library/locale.rst

@@ -412,18 +412,6 @@ The :mod:`locale` module defines the following exception and functions:
       The *monetary* keyword parameter was added.
 
 
-.. function:: format(format, val, grouping=False, monetary=False)
-
-   Please note that this function works like :meth:`format_string` but will
-   only work for exactly one ``%char`` specifier.  For example, ``'%f'`` and
-   ``'%.0f'`` are both valid specifiers, but ``'%f KiB'`` is not.
-
-   For whole format strings, use :func:`format_string`.
-
-   .. deprecated:: 3.7
-      Use :meth:`format_string` instead.
-
-
 .. function:: currency(val, symbol=True, grouping=False, international=False)
 
    Formats a number *val* according to the current :const:`LC_MONETARY` settings.
@@ -507,7 +495,7 @@ The :mod:`locale` module defines the following exception and functions:
 
 .. data:: LC_NUMERIC
 
-   Locale category for formatting numbers.  The functions :func:`.format`,
+   Locale category for formatting numbers.  The functions :func:`format_string`,
    :func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are
    affected by that category.  All other numeric formatting operations are not
    affected.
@@ -569,7 +557,7 @@ document that your module is not compatible with non-\ ``C`` locale settings.
 
 The only way to perform numeric operations according to the locale is to use the
 special functions defined by this module: :func:`atof`, :func:`atoi`,
-:func:`.format`, :func:`.str`.
+:func:`format_string`, :func:`.str`.
 
 There is no way to perform case conversions and character classifications
 according to the locale.  For (Unicode) text strings these are done according

Doc/tutorial/stdlib2.rst

@@ -59,7 +59,7 @@ formatting numbers with group separators::
    'English_United States.1252'
    >>> conv = locale.localeconv()          # get a mapping of conventions
    >>> x = 1234567.8
-   >>> locale.format("%d", x, grouping=True)
+   >>> locale.format_string("%d", x, grouping=True)
    '1,234,567'
    >>> locale.format_string("%s%.*f", (conv['currency_symbol'],
    ...                      conv['frac_digits'], x), grouping=True)

Doc/whatsnew/3.12.rst

@@ -269,6 +269,11 @@ Removed
   :func:`ssl.match_hostname` function.
   (Contributed by Victor Stinner in :gh:`94199`.)
 
+* Remove the :func:`locale.format` function, deprecated in Python 3.7:
+  use :func:`locale.format_string` instead.
+  (Contributed by Victor Stinner in :gh:`94226`.)
+
+
 Porting to Python 3.12
 ======================
 

Lib/locale.py

@@ -26,7 +26,7 @@
 # trying the import.  So __all__ is also fiddled at the end of the file.
 __all__ = ["getlocale", "getdefaultlocale", "getpreferredencoding", "Error",
            "setlocale", "resetlocale", "localeconv", "strcoll", "strxfrm",
-           "str", "atof", "atoi", "format", "format_string", "currency",
+           "str", "atof", "atoi", "format_string", "currency",
            "normalize", "LC_CTYPE", "LC_COLLATE", "LC_TIME", "LC_MONETARY",
            "LC_NUMERIC", "LC_ALL", "CHAR_MAX", "getencoding"]
 
@@ -247,21 +247,6 @@ def format_string(f, val, grouping=False, monetary=False):
 
     return new_f % val
 
-def format(percent, value, grouping=False, monetary=False, *additional):
-    """Deprecated, use format_string instead."""
-    import warnings
-    warnings.warn(
-        "This method will be removed in a future version of Python. "
-        "Use 'locale.format_string()' instead.",
-        DeprecationWarning, stacklevel=2
-    )
-
-    match = _percent_re.match(percent)
-    if not match or len(match.group())!= len(percent):
-        raise ValueError(("format() must be given exactly one %%char "
-                         "format specifier, %s not valid") % repr(percent))
-    return _format(percent, value, grouping, monetary, *additional)
-
 def currency(val, symbol=True, grouping=False, international=False):
     """Formats val according to the currency settings
     in the current locale."""

Lib/test/test_locale.py

@@ -141,18 +141,9 @@ class BaseFormattingTest(object):
     # Utility functions for formatting tests
     #
 
-    def _test_formatfunc(self, format, value, out, func, **format_opts):
-        self.assertEqual(
-            func(format, value, **format_opts), out)
-
-    def _test_format(self, format, value, out, **format_opts):
-        with check_warnings(('', DeprecationWarning)):
-            self._test_formatfunc(format, value, out,
-                func=locale.format, **format_opts)
-
     def _test_format_string(self, format, value, out, **format_opts):
-        self._test_formatfunc(format, value, out,
-            func=locale.format_string, **format_opts)
+        self.assertEqual(
+            locale.format_string(format, value, **format_opts), out)
 
     def _test_currency(self, value, out, **format_opts):
         self.assertEqual(locale.currency(value, **format_opts), out)
@@ -166,44 +157,40 @@ def setUp(self):
         self.sep = locale.localeconv()['thousands_sep']
 
     def test_grouping(self):
-        self._test_format("%f", 1024, grouping=1, out='1%s024.000000' % self.sep)
-        self._test_format("%f", 102, grouping=1, out='102.000000')
-        self._test_format("%f", -42, grouping=1, out='-42.000000')
-        self._test_format("%+f", -42, grouping=1, out='-42.000000')
+        self._test_format_string("%f", 1024, grouping=1, out='1%s024.000000' % self.sep)
+        self._test_format_string("%f", 102, grouping=1, out='102.000000')
+        self._test_format_string("%f", -42, grouping=1, out='-42.000000')
+        self._test_format_string("%+f", -42, grouping=1, out='-42.000000')
 
     def test_grouping_and_padding(self):
-        self._test_format("%20.f", -42, grouping=1, out='-42'.rjust(20))
+        self._test_format_string("%20.f", -42, grouping=1, out='-42'.rjust(20))
         if self.sep:
-            self._test_format("%+10.f", -4200, grouping=1,
+            self._test_format_string("%+10.f", -4200, grouping=1,
                 out=('-4%s200' % self.sep).rjust(10))
-            self._test_format("%-10.f", -4200, grouping=1,
+            self._test_format_string("%-10.f", -4200, grouping=1,
                 out=('-4%s200' % self.sep).ljust(10))
 
     def test_integer_grouping(self):
-        self._test_format("%d", 4200, grouping=True, out='4%s200' % self.sep)
-        self._test_format("%+d", 4200, grouping=True, out='+4%s200' % self.sep)
-        self._test_format("%+d", -4200, grouping=True, out='-4%s200' % self.sep)
+        self._test_format_string("%d", 4200, grouping=True, out='4%s200' % self.sep)
+        self._test_format_string("%+d", 4200, grouping=True, out='+4%s200' % self.sep)
+        self._test_format_string("%+d", -4200, grouping=True, out='-4%s200' % self.sep)
 
     def test_integer_grouping_and_padding(self):
-        self._test_format("%10d", 4200, grouping=True,
+        self._test_format_string("%10d", 4200, grouping=True,
             out=('4%s200' % self.sep).rjust(10))
-        self._test_format("%-10d", -4200, grouping=True,
+        self._test_format_string("%-10d", -4200, grouping=True,
             out=('-4%s200' % self.sep).ljust(10))
 
     def test_simple(self):
-        self._test_format("%f", 1024, grouping=0, out='1024.000000')
-        self._test_format("%f", 102, grouping=0, out='102.000000')
-        self._test_format("%f", -42, grouping=0, out='-42.000000')
-        self._test_format("%+f", -42, grouping=0, out='-42.000000')
+        self._test_format_string("%f", 1024, grouping=0, out='1024.000000')
+        self._test_format_string("%f", 102, grouping=0, out='102.000000')
+        self._test_format_string("%f", -42, grouping=0, out='-42.000000')
+        self._test_format_string("%+f", -42, grouping=0, out='-42.000000')
 
     def test_padding(self):
-        self._test_format("%20.f", -42, grouping=0, out='-42'.rjust(20))
-        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)
+        self._test_format_string("%20.f", -42, grouping=0, out='-42'.rjust(20))
+        self._test_format_string("%+10.f", -4200, grouping=0, out='-4200'.rjust(10))
+        self._test_format_string("%-10.f", 4200, grouping=0, out='4200'.ljust(10))
 
     def test_complex_formatting(self):
         # Spaces in formatting string
@@ -230,20 +217,9 @@ def test_complex_formatting(self):
                 out='int 1%s000 float 1%s000.00 str str' %
                 (self.sep, self.sep))
 
-
-class TestFormatPatternArg(unittest.TestCase):
-    # Test handling of pattern argument of format
-
-    def test_onlyOnePattern(self):
-        with check_warnings(('', DeprecationWarning)):
-            # Issue 2522: accept exactly one % pattern, and no extra chars.
-            self.assertRaises(ValueError, locale.format, "%f\n", 'foo')
-            self.assertRaises(ValueError, locale.format, "%f\r", 'foo')
-            self.assertRaises(ValueError, locale.format, "%f\r\n", 'foo')
-            self.assertRaises(ValueError, locale.format, " %f", 'foo')
-            self.assertRaises(ValueError, locale.format, "%fg", 'foo')
-            self.assertRaises(ValueError, locale.format, "%^g", 'foo')
-            self.assertRaises(ValueError, locale.format, "%f%%", 'foo')
+        self._test_format_string("total=%i%%", 100, out='total=100%')
+        self._test_format_string("newline: %i\n", 3, out='newline: 3\n')
+        self._test_format_string("extra: %ii", 3, out='extra: 3i')
 
 
 class TestLocaleFormatString(unittest.TestCase):
@@ -292,45 +268,45 @@ class TestCNumberFormatting(CCookedTest, BaseFormattingTest):
     # Test number formatting with a cooked "C" locale.
 
     def test_grouping(self):
-        self._test_format("%.2f", 12345.67, grouping=True, out='12345.67')
+        self._test_format_string("%.2f", 12345.67, grouping=True, out='12345.67')
 
     def test_grouping_and_padding(self):
-        self._test_format("%9.2f", 12345.67, grouping=True, out=' 12345.67')
+        self._test_format_string("%9.2f", 12345.67, grouping=True, out=' 12345.67')
 
 
 class TestFrFRNumberFormatting(FrFRCookedTest, BaseFormattingTest):
     # Test number formatting with a cooked "fr_FR" locale.
 
     def test_decimal_point(self):
-        self._test_format("%.2f", 12345.67, out='12345,67')
+        self._test_format_string("%.2f", 12345.67, out='12345,67')
 
     def test_grouping(self):
-        self._test_format("%.2f", 345.67, grouping=True, out='345,67')
-        self._test_format("%.2f", 12345.67, grouping=True, out='12 345,67')
+        self._test_format_string("%.2f", 345.67, grouping=True, out='345,67')
+        self._test_format_string("%.2f", 12345.67, grouping=True, out='12 345,67')
 
     def test_grouping_and_padding(self):
-        self._test_format("%6.2f", 345.67, grouping=True, out='345,67')
-        self._test_format("%7.2f", 345.67, grouping=True, out=' 345,67')
-        self._test_format("%8.2f", 12345.67, grouping=True, out='12 345,67')
-        self._test_format("%9.2f", 12345.67, grouping=True, out='12 345,67')
-        self._test_format("%10.2f", 12345.67, grouping=True, out=' 12 345,67')
-        self._test_format("%-6.2f", 345.67, grouping=True, out='345,67')
-        self._test_format("%-7.2f", 345.67, grouping=True, out='345,67 ')
-        self._test_format("%-8.2f", 12345.67, grouping=True, out='12 345,67')
-        self._test_format("%-9.2f", 12345.67, grouping=True, out='12 345,67')
-        self._test_format("%-10.2f", 12345.67, grouping=True, out='12 345,67 ')
+        self._test_format_string("%6.2f", 345.67, grouping=True, out='345,67')
+        self._test_format_string("%7.2f", 345.67, grouping=True, out=' 345,67')
+        self._test_format_string("%8.2f", 12345.67, grouping=True, out='12 345,67')
+        self._test_format_string("%9.2f", 12345.67, grouping=True, out='12 345,67')
+        self._test_format_string("%10.2f", 12345.67, grouping=True, out=' 12 345,67')
+        self._test_format_string("%-6.2f", 345.67, grouping=True, out='345,67')
+        self._test_format_string("%-7.2f", 345.67, grouping=True, out='345,67 ')
+        self._test_format_string("%-8.2f", 12345.67, grouping=True, out='12 345,67')
+        self._test_format_string("%-9.2f", 12345.67, grouping=True, out='12 345,67')
+        self._test_format_string("%-10.2f", 12345.67, grouping=True, out='12 345,67 ')
 
     def test_integer_grouping(self):
-        self._test_format("%d", 200, grouping=True, out='200')
-        self._test_format("%d", 4200, grouping=True, out='4 200')
+        self._test_format_string("%d", 200, grouping=True, out='200')
+        self._test_format_string("%d", 4200, grouping=True, out='4 200')
 
     def test_integer_grouping_and_padding(self):
-        self._test_format("%4d", 4200, grouping=True, out='4 200')
-        self._test_format("%5d", 4200, grouping=True, out='4 200')
-        self._test_format("%10d", 4200, grouping=True, out='4 200'.rjust(10))
-        self._test_format("%-4d", 4200, grouping=True, out='4 200')
-        self._test_format("%-5d", 4200, grouping=True, out='4 200')
-        self._test_format("%-10d", 4200, grouping=True, out='4 200'.ljust(10))
+        self._test_format_string("%4d", 4200, grouping=True, out='4 200')
+        self._test_format_string("%5d", 4200, grouping=True, out='4 200')
+        self._test_format_string("%10d", 4200, grouping=True, out='4 200'.rjust(10))
+        self._test_format_string("%-4d", 4200, grouping=True, out='4 200')
+        self._test_format_string("%-5d", 4200, grouping=True, out='4 200')
+        self._test_format_string("%-10d", 4200, grouping=True, out='4 200'.ljust(10))
 
     def test_currency(self):
         euro = '\u20ac'

Misc/NEWS.d/next/Library/2022-06-24-18-20-42.gh-issue-94226.8ZL4Fm.rst

@@ -0,0 +1,2 @@
+Remove the :func:`locale.format` function, deprecated in Python 3.7: use
+:func:`locale.format_string` instead. Patch by Victor Stinner.