From 9d45abf9a820cd77d4c0c16176c6c49a23774c85 Mon Sep 17 00:00:00 2001 From: Broyojo Date: Fri, 13 Nov 2026 19:23:52 -0500 Subject: [PATCH 1/4] gh-161970: Rename UserString.replace() parameter maxsplit to count --- Lib/collections/__init__.py | 4 ++-- Lib/test/string_tests.py | 9 +++++---- .../2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst | 2 ++ 3 files changed, 9 insertions(+), 6 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 2239787dd6b51aa..c291dbd36868d01 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1611,12 +1611,12 @@ def lstrip(self, chars=None): def partition(self, sep): return self.data.partition(sep) - def replace(self, old, new, maxsplit=-1): + def replace(self, old, new, 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/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..d72b523faac4f11 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst @@ -0,0 +1,2 @@ +Rename the *maxsplit* parameter of :meth:`!collections.UserString.replace` to +*count*, matching :meth:`str.replace`, so that it can be passed as a keyword. From f0d071b472854aadf7e4e24987ca896f12571b2f Mon Sep 17 00:00:00 2001 From: Broyojo Date: Sat, 14 Nov 2026 17:45:52 +0000 Subject: [PATCH 2/4] gh-161970: Deprecate UserString.replace() maxsplit keyword instead of removing it Keep accepting the old keyword name for a deprecation period instead of breaking callers that pass maxsplit= (typeshed spells the parameter maxsplit). Passing maxsplit= now emits a DeprecationWarning and is slated for removal in Python 3.18; passing both count and maxsplit raises TypeError. This mirrors the deprecation of the 'string' keyword parameter in hashlib (gh-134978), with a two-year period. --- Doc/deprecations/pending-removal-in-3.18.rst | 7 ++++ Doc/library/collections.rst | 6 ++++ Doc/whatsnew/3.16.rst | 9 ++++++ Lib/collections/__init__.py | 20 +++++++++++- Lib/test/test_userstring.py | 32 +++++++++++++++++++ ...-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst | 4 ++- 6 files changed, 76 insertions(+), 2 deletions(-) diff --git a/Doc/deprecations/pending-removal-in-3.18.rst b/Doc/deprecations/pending-removal-in-3.18.rst index fb10420ab38c52f..8c2f9b7bd13c4bf 100644 --- a/Doc/deprecations/pending-removal-in-3.18.rst +++ b/Doc/deprecations/pending-removal-in-3.18.rst @@ -4,6 +4,13 @@ Pending removal in Python 3.18 * No longer accept a boolean value when a file descriptor is expected. (Contributed by Serhiy Storchaka in :gh:`82626`.) +* :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:`decimal`: * The non-standard and undocumented :class:`~decimal.Decimal` format diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 40f780c7d049d4e..ba54ffb8d927fdf 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.18 + 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..13f7a69b56d5eff 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.18. 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 c291dbd36868d01..84028acc242fee8 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,7 +1614,22 @@ def lstrip(self, chars=None): def partition(self, sep): return self.data.partition(sep) - def replace(self, old, new, count=-1): + # The 'maxsplit' keyword parameter can be removed in Python 3.18. + def replace(self, old, new, count=-1, *, maxsplit=_MISSING): + if maxsplit is not _MISSING: + if count != -1: + raise TypeError("'count' and 'maxsplit' are mutually exclusive " + "and support for 'maxsplit' keyword parameter " + "is slated for removal in Python 3.18") + 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, 18)) + count = maxsplit if isinstance(old, UserString): old = old.data if isinstance(new, UserString): diff --git a/Lib/test/test_userstring.py b/Lib/test/test_userstring.py index 1ba5b661aba016b..86276bb966b566d 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.18; " + "use the 'count' keyword parameter or pass the count " + "as a positional argument instead" +) + + class UserStringSubclass(UserString): pass @@ -187,6 +196,29 @@ 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) + 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 index d72b523faac4f11..b06c2d7ba874e2f 100644 --- 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 @@ -1,2 +1,4 @@ -Rename the *maxsplit* parameter of :meth:`!collections.UserString.replace` to +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.18. From 836df52ba266e8b7205a51825ec3f3cd42e2d971 Mon Sep 17 00:00:00 2001 From: Broyojo Date: Sun, 15 Nov 2026 11:25:04 -0500 Subject: [PATCH 3/4] gh-161970: Reject an explicit count together with maxsplit in UserString.replace() --- Lib/collections/__init__.py | 6 ++++-- Lib/test/test_userstring.py | 5 +++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 84028acc242fee8..44e8b805d8992c3 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1615,9 +1615,9 @@ def partition(self, sep): return self.data.partition(sep) # The 'maxsplit' keyword parameter can be removed in Python 3.18. - def replace(self, old, new, count=-1, *, maxsplit=_MISSING): + def replace(self, old, new, count=_MISSING, *, maxsplit=_MISSING): if maxsplit is not _MISSING: - if count != -1: + 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.18") @@ -1630,6 +1630,8 @@ def replace(self, old, new, count=-1, *, maxsplit=_MISSING): "as a positional argument instead", remove=(3, 18)) count = maxsplit + elif count is _MISSING: + count = -1 if isinstance(old, UserString): old = old.data if isinstance(new, UserString): diff --git a/Lib/test/test_userstring.py b/Lib/test/test_userstring.py index 86276bb966b566d..f65389dbfe673c1 100644 --- a/Lib/test/test_userstring.py +++ b/Lib/test/test_userstring.py @@ -218,6 +218,11 @@ def test_replace_maxsplit_deprecated(self): 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__": From 5c8a18f40d102a9a7df2778310fc1f48014af16a Mon Sep 17 00:00:00 2001 From: Broyojo Date: Mon, 16 Nov 2026 12:34:32 -0500 Subject: [PATCH 4/4] gh-161970: Extend the maxsplit deprecation period to Python 3.21 --- Doc/deprecations/pending-removal-in-3.18.rst | 7 ------- Doc/deprecations/pending-removal-in-3.21.rst | 7 +++++++ Doc/library/collections.rst | 2 +- Doc/whatsnew/3.16.rst | 2 +- Lib/collections/__init__.py | 6 +++--- Lib/test/test_userstring.py | 2 +- .../Library/2026-11-13-00-00-00.gh-issue-161970.Kq3vRw.rst | 2 +- 7 files changed, 14 insertions(+), 14 deletions(-) diff --git a/Doc/deprecations/pending-removal-in-3.18.rst b/Doc/deprecations/pending-removal-in-3.18.rst index 8c2f9b7bd13c4bf..fb10420ab38c52f 100644 --- a/Doc/deprecations/pending-removal-in-3.18.rst +++ b/Doc/deprecations/pending-removal-in-3.18.rst @@ -4,13 +4,6 @@ Pending removal in Python 3.18 * No longer accept a boolean value when a file descriptor is expected. (Contributed by Serhiy Storchaka in :gh:`82626`.) -* :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:`decimal`: * The non-standard and undocumented :class:`~decimal.Decimal` format 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 ba54ffb8d927fdf..7a689567b112cf5 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -1439,7 +1439,7 @@ attribute. New methods ``__getnewargs__``, ``__rmod__``, ``casefold``, ``format_map``, ``isprintable``, and ``maketrans``. - .. deprecated-removed:: 3.16 3.18 + .. 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 diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst index 13f7a69b56d5eff..3198cc761c1dd9f 100644 --- a/Doc/whatsnew/3.16.rst +++ b/Doc/whatsnew/3.16.rst @@ -1334,7 +1334,7 @@ New deprecations * 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.18. Prefer passing the count as a positional argument for + in Python 3.21. Prefer passing the count as a positional argument for maximum backwards compatibility. (Contributed by David Andrews in :gh:`161970`.) diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 44e8b805d8992c3..59bee66430e9acc 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1614,13 +1614,13 @@ def lstrip(self, chars=None): def partition(self, sep): return self.data.partition(sep) - # The 'maxsplit' keyword parameter can be removed in Python 3.18. + # 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.18") + "is slated for removal in Python 3.21") import warnings warnings._deprecated( "maxsplit", @@ -1628,7 +1628,7 @@ def replace(self, old, new, count=_MISSING, *, maxsplit=_MISSING): "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, 18)) + remove=(3, 21)) count = maxsplit elif count is _MISSING: count = -1 diff --git a/Lib/test/test_userstring.py b/Lib/test/test_userstring.py index f65389dbfe673c1..6c31eb09f88269c 100644 --- a/Lib/test/test_userstring.py +++ b/Lib/test/test_userstring.py @@ -11,7 +11,7 @@ DEPRECATED_MAXSPLIT_PARAMETER = re.escape( "the 'maxsplit' keyword parameter is deprecated since " - "Python 3.16 and slated for removal in Python 3.18; " + "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" ) 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 index b06c2d7ba874e2f..211f8846305d8d6 100644 --- 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 @@ -1,4 +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.18. +slated for removal in Python 3.21.