Skip to content

Commit f0d071b

Browse files
committed
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.
1 parent 9d45abf commit f0d071b

6 files changed

Lines changed: 76 additions & 2 deletions

File tree

‎Doc/deprecations/pending-removal-in-3.18.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ Pending removal in Python 3.18
44
* No longer accept a boolean value when a file descriptor is expected.
55
(Contributed by Serhiy Storchaka in :gh:`82626`.)
66

7+
* :mod:`collections`:
8+
9+
* The undocumented ``maxsplit`` keyword parameter of
10+
:meth:`!collections.UserString.replace` has been deprecated since
11+
Python 3.16. Pass the count as a positional argument or use the
12+
``count`` keyword parameter instead.
13+
714
* :mod:`decimal`:
815

916
* The non-standard and undocumented :class:`~decimal.Decimal` format

‎Doc/library/collections.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1438,3 +1438,9 @@ attribute.
14381438
.. versionchanged:: 3.5
14391439
New methods ``__getnewargs__``, ``__rmod__``, ``casefold``,
14401440
``format_map``, ``isprintable``, and ``maketrans``.
1441+
1442+
.. deprecated-removed:: 3.16 3.18
1443+
The third parameter of :meth:`!replace` is now named *count*, as in
1444+
:meth:`str.replace`, and the undocumented ``maxsplit`` keyword
1445+
parameter is deprecated. Prefer passing the count as a positional
1446+
argument for maximum backwards compatibility.

‎Doc/whatsnew/3.16.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1329,6 +1329,15 @@ New deprecations
13291329

13301330
(Contributed by Stan Ulbrych in :gh:`159240`.)
13311331

1332+
* :mod:`collections`:
1333+
1334+
* The third parameter of :meth:`!collections.UserString.replace` is now
1335+
named *count*, as in :meth:`str.replace`. Support for the undocumented
1336+
``maxsplit`` keyword parameter is now deprecated and slated for removal
1337+
in Python 3.18. Prefer passing the count as a positional argument for
1338+
maximum backwards compatibility.
1339+
(Contributed by David Andrews in :gh:`161970`.)
1340+
13321341
* :mod:`functools`:
13331342

13341343
* Using a return annotation to infer the dispatch type for

‎Lib/collections/__init__.py‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1414,6 +1414,9 @@ def extend(self, other):
14141414
### UserString
14151415
################################################################################
14161416

1417+
_MISSING = sentinel("MISSING")
1418+
1419+
14171420
class UserString(_collections_abc.Sequence):
14181421

14191422
def __init__(self, seq):
@@ -1611,7 +1614,22 @@ def lstrip(self, chars=None):
16111614
def partition(self, sep):
16121615
return self.data.partition(sep)
16131616

1614-
def replace(self, old, new, count=-1):
1617+
# The 'maxsplit' keyword parameter can be removed in Python 3.18.
1618+
def replace(self, old, new, count=-1, *, maxsplit=_MISSING):
1619+
if maxsplit is not _MISSING:
1620+
if count != -1:
1621+
raise TypeError("'count' and 'maxsplit' are mutually exclusive "
1622+
"and support for 'maxsplit' keyword parameter "
1623+
"is slated for removal in Python 3.18")
1624+
import warnings
1625+
warnings._deprecated(
1626+
"maxsplit",
1627+
message="the {name!r} keyword parameter is deprecated since "
1628+
"Python 3.16 and slated for removal in Python {remove}; "
1629+
"use the 'count' keyword parameter or pass the count "
1630+
"as a positional argument instead",
1631+
remove=(3, 18))
1632+
count = maxsplit
16151633
if isinstance(old, UserString):
16161634
old = old.data
16171635
if isinstance(new, UserString):

‎Lib/test/test_userstring.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,22 @@
11
# UserString is a wrapper around the native builtin string type.
22
# UserString instances should behave similar to builtin string objects.
33

4+
import re
45
import unittest
56
from test import string_tests
67
from test import support
78

89
from collections import UserString
910

1011

12+
DEPRECATED_MAXSPLIT_PARAMETER = re.escape(
13+
"the 'maxsplit' keyword parameter is deprecated since "
14+
"Python 3.16 and slated for removal in Python 3.18; "
15+
"use the 'count' keyword parameter or pass the count "
16+
"as a positional argument instead"
17+
)
18+
19+
1120
class UserStringSubclass(UserString):
1221
pass
1322

@@ -187,6 +196,29 @@ def test_implementation(self):
187196
self.assertEqual(i, 5)
188197
self.assertEqual(i2, 5)
189198

199+
def test_replace_count(self):
200+
s = UserString('aaa')
201+
self.assertEqual(s.replace('a', 'b', 2), 'bba')
202+
self.assertEqual(s.replace('a', 'b', count=2), 'bba')
203+
self.assertEqual(s.replace(UserString('a'), UserString('b'), count=1),
204+
'baa')
205+
206+
def test_replace_maxsplit_deprecated(self):
207+
# gh-161970: the third parameter was misnamed 'maxsplit'.
208+
s = UserStringSubclass('aaa')
209+
with self.assertWarnsRegex(DeprecationWarning,
210+
DEPRECATED_MAXSPLIT_PARAMETER) as cm:
211+
r = s.replace('a', 'b', maxsplit=2)
212+
self.assertEqual(cm.filename, __file__)
213+
self.assertEqual(r, 'bba')
214+
self.assertIs(type(r), UserStringSubclass)
215+
216+
msg = "'count' and 'maxsplit' are mutually exclusive"
217+
with self.assertRaisesRegex(TypeError, msg):
218+
s.replace('a', 'b', 1, maxsplit=2)
219+
with self.assertRaisesRegex(TypeError, msg):
220+
s.replace('a', 'b', count=1, maxsplit=2)
221+
190222

191223
if __name__ == "__main__":
192224
unittest.main()
Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
Rename the *maxsplit* parameter of :meth:`!collections.UserString.replace` to
1+
The third parameter of :meth:`!collections.UserString.replace` is now named
22
*count*, matching :meth:`str.replace`, so that it can be passed as a keyword.
3+
Support for the undocumented ``maxsplit`` keyword parameter is deprecated and
4+
slated for removal in Python 3.18.

0 commit comments

Comments
 (0)