Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions Doc/deprecations/pending-removal-in-3.21.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions Doc/library/collections.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
9 changes: 9 additions & 0 deletions Doc/whatsnew/3.16.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 22 additions & 2 deletions Lib/collections/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -1414,6 +1414,9 @@ def extend(self, other):
### UserString
################################################################################

_MISSING = sentinel("MISSING")


class UserString(_collections_abc.Sequence):

def __init__(self, seq):
Expand Down Expand Up @@ -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):
Expand Down
9 changes: 5 additions & 4 deletions Lib/test/string_tests.py
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
37 changes: 37 additions & 0 deletions Lib/test/test_userstring.py
Original file line number Diff line number Diff line change
@@ -1,13 +1,22 @@
# 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

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

Expand Down Expand Up @@ -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()
Original file line number Diff line number Diff line change
@@ -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.
Loading