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.18.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
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.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.
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.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
Expand Down
22 changes: 20 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,27 @@ 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.18.
def replace(self, old, new, count=-1, *, maxsplit=_MISSING):

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s.replace('a', 'b', -1, maxsplit=1) will not raise, maybe we can set count's default to _MISSING to address this.

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):
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
32 changes: 32 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.18; "
"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,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()
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.18.
Loading