diff --git a/Doc/deprecations/pending-removal-in-3.21.rst b/Doc/deprecations/pending-removal-in-3.21.rst index c85f170e3d3f948..89828dc883c656f 100644 --- a/Doc/deprecations/pending-removal-in-3.21.rst +++ b/Doc/deprecations/pending-removal-in-3.21.rst @@ -18,6 +18,13 @@ Pending removal in Python 3.21 * The ``dims`` property of ``ast.Tuple`` will be removed in Python 3.21. Use the ``ast.Tuple.elts`` property instead. +* :mod:`collections`: + + * The undocumented ``maxsplit`` keyword parameter of + :meth:`!collections.UserString.replace` has been deprecated since + Python 3.16. Pass the count as a positional argument or use the + ``count`` keyword parameter instead. + * :mod:`functools`: * Using a return annotation to infer the dispatch type for diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 40f780c7d049d4e..7a689567b112cf5 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -1438,3 +1438,9 @@ attribute. .. versionchanged:: 3.5 New methods ``__getnewargs__``, ``__rmod__``, ``casefold``, ``format_map``, ``isprintable``, and ``maketrans``. + + .. deprecated-removed:: 3.16 3.21 + The third parameter of :meth:`!replace` is now named *count*, as in + :meth:`str.replace`, and the undocumented ``maxsplit`` keyword + parameter is deprecated. Prefer passing the count as a positional + argument for maximum backwards compatibility. diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst index f86a6ec69172d8a..3198cc761c1dd9f 100644 --- a/Doc/whatsnew/3.16.rst +++ b/Doc/whatsnew/3.16.rst @@ -1329,6 +1329,15 @@ New deprecations (Contributed by Stan Ulbrych in :gh:`159240`.) +* :mod:`collections`: + + * The third parameter of :meth:`!collections.UserString.replace` is now + named *count*, as in :meth:`str.replace`. Support for the undocumented + ``maxsplit`` keyword parameter is now deprecated and slated for removal + in Python 3.21. Prefer passing the count as a positional argument for + maximum backwards compatibility. + (Contributed by David Andrews in :gh:`161970`.) + * :mod:`functools`: * Using a return annotation to infer the dispatch type for diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 2239787dd6b51aa..59bee66430e9acc 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1414,6 +1414,9 @@ def extend(self, other): ### UserString ################################################################################ +_MISSING = sentinel("MISSING") + + class UserString(_collections_abc.Sequence): def __init__(self, seq): @@ -1611,12 +1614,29 @@ def lstrip(self, chars=None): def partition(self, sep): return self.data.partition(sep) - def replace(self, old, new, maxsplit=-1): + # The 'maxsplit' keyword parameter can be removed in Python 3.21. + def replace(self, old, new, count=_MISSING, *, maxsplit=_MISSING): + if maxsplit is not _MISSING: + if count is not _MISSING: + raise TypeError("'count' and 'maxsplit' are mutually exclusive " + "and support for 'maxsplit' keyword parameter " + "is slated for removal in Python 3.21") + import warnings + warnings._deprecated( + "maxsplit", + message="the {name!r} keyword parameter is deprecated since " + "Python 3.16 and slated for removal in Python {remove}; " + "use the 'count' keyword parameter or pass the count " + "as a positional argument instead", + remove=(3, 21)) + count = maxsplit + elif count is _MISSING: + count = -1 if isinstance(old, UserString): old = old.data if isinstance(new, UserString): new = new.data - return self.__class__(self.data.replace(old, new, maxsplit)) + return self.__class__(self.data.replace(old, new, count)) def rfind(self, sub, start=0, end=_sys.maxsize): if isinstance(sub, UserString): diff --git a/Lib/test/string_tests.py b/Lib/test/string_tests.py index f66051531faaa16..1aeb0374498c9c3 100644 --- a/Lib/test/string_tests.py +++ b/Lib/test/string_tests.py @@ -194,10 +194,11 @@ def test_count(self): self.assertEqual(r1, r2, '%s != %s for %s' % (r1, r2, i)) def test_count_keyword(self): - self.assertEqual('aa'.replace('a', 'b', 0), 'aa'.replace('a', 'b', count=0)) - self.assertEqual('aa'.replace('a', 'b', 1), 'aa'.replace('a', 'b', count=1)) - self.assertEqual('aa'.replace('a', 'b', 2), 'aa'.replace('a', 'b', count=2)) - self.assertEqual('aa'.replace('a', 'b', 3), 'aa'.replace('a', 'b', count=3)) + self.checkequal('aa', 'aa', 'replace', 'a', 'b', count=0) + self.checkequal('ba', 'aa', 'replace', 'a', 'b', count=1) + self.checkequal('bb', 'aa', 'replace', 'a', 'b', count=2) + self.checkequal('bb', 'aa', 'replace', 'a', 'b', count=3) + self.checkequal('bb', 'aa', 'replace', 'a', 'b', count=-1) def test_find(self): self.checkequal(0, 'abcdefghiabc', 'find', 'abc') diff --git a/Lib/test/test_userstring.py b/Lib/test/test_userstring.py index 1ba5b661aba016b..6c31eb09f88269c 100644 --- a/Lib/test/test_userstring.py +++ b/Lib/test/test_userstring.py @@ -1,6 +1,7 @@ # UserString is a wrapper around the native builtin string type. # UserString instances should behave similar to builtin string objects. +import re import unittest from test import string_tests from test import support @@ -8,6 +9,14 @@ from collections import UserString +DEPRECATED_MAXSPLIT_PARAMETER = re.escape( + "the 'maxsplit' keyword parameter is deprecated since " + "Python 3.16 and slated for removal in Python 3.21; " + "use the 'count' keyword parameter or pass the count " + "as a positional argument instead" +) + + class UserStringSubclass(UserString): pass @@ -187,6 +196,34 @@ def test_implementation(self): self.assertEqual(i, 5) self.assertEqual(i2, 5) + def test_replace_count(self): + s = UserString('aaa') + self.assertEqual(s.replace('a', 'b', 2), 'bba') + self.assertEqual(s.replace('a', 'b', count=2), 'bba') + self.assertEqual(s.replace(UserString('a'), UserString('b'), count=1), + 'baa') + + def test_replace_maxsplit_deprecated(self): + # gh-161970: the third parameter was misnamed 'maxsplit'. + s = UserStringSubclass('aaa') + with self.assertWarnsRegex(DeprecationWarning, + DEPRECATED_MAXSPLIT_PARAMETER) as cm: + r = s.replace('a', 'b', maxsplit=2) + self.assertEqual(cm.filename, __file__) + self.assertEqual(r, 'bba') + self.assertIs(type(r), UserStringSubclass) + + msg = "'count' and 'maxsplit' are mutually exclusive" + with self.assertRaisesRegex(TypeError, msg): + s.replace('a', 'b', 1, maxsplit=2) + with self.assertRaisesRegex(TypeError, msg): + s.replace('a', 'b', count=1, maxsplit=2) + # An explicit count equal to the default still conflicts. + with self.assertRaisesRegex(TypeError, msg): + s.replace('a', 'b', -1, maxsplit=2) + with self.assertRaisesRegex(TypeError, msg): + s.replace('a', 'b', count=-1, maxsplit=2) + if __name__ == "__main__": unittest.main() diff --git a/Misc/NEWS.d/next/Library/2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst b/Misc/NEWS.d/next/Library/2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst new file mode 100644 index 000000000000000..211f8846305d8d6 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst @@ -0,0 +1,4 @@ +The third parameter of :meth:`!collections.UserString.replace` is now named +*count*, matching :meth:`str.replace`, so that it can be passed as a keyword. +Support for the undocumented ``maxsplit`` keyword parameter is deprecated and +slated for removal in Python 3.21.