Add references to past discussion threads, fix formatting and typos (#1335)
This commit is contained in:
sweeneyde
GitHub
parent
0093a853e8
commit
9c16d3539e
100
pep-0616.rst
100
pep-0616.rst
|
|
@ -23,14 +23,15 @@ if present, and would be added to to Unicode ``str`` objects, binary
|
|||
Rationale
|
||||
=========
|
||||
|
||||
There have been repeated issues [#confusion]_ on the Bug Tracker
|
||||
and StackOverflow related to user confusion about the existing
|
||||
``str.lstrip`` and ``str.rstrip`` methods. These users are typically
|
||||
expecting the behavior of ``cutprefix`` and ``cutsuffix``, but they
|
||||
are surprised that the parameter for ``lstrip`` is interpreted as a
|
||||
set of characters, not a substring. This repeated issue is evidence
|
||||
that these methods are useful, and the new methods allow a cleaner
|
||||
redirection of users to the desired behavior.
|
||||
There have been repeated issues on Python-Ideas [#pyid]_ [3]_,
|
||||
Python-Dev [4]_ [5]_ [6]_ [7]_, the Bug Tracker, and
|
||||
StackOverflow [#confusion]_, related to user confusion about the
|
||||
existing ``str.lstrip`` and ``str.rstrip`` methods. These users are
|
||||
typically expecting the behavior of ``cutprefix`` and ``cutsuffix``,
|
||||
but they are surprised that the parameter for ``lstrip`` is
|
||||
interpreted as a set of characters, not a substring. This repeated
|
||||
issue is evidence that these methods are useful. The new methods
|
||||
allow a cleaner redirection of users to the desired behavior.
|
||||
|
||||
As another testimonial for the usefulness of these methods, several
|
||||
users on Python-Ideas [#pyid]_ reported frequently including similar
|
||||
|
|
@ -105,19 +106,19 @@ Methods with the corresponding semantics will be added to the builtin
|
|||
``bytes`` and ``bytearray`` objects. If ``b`` is either a ``bytes``
|
||||
or ``bytearray`` object, then ``b.cutsuffix()`` and ``b.cutprefix()``
|
||||
will accept any bytes-like object or tuple of bytes-like objects as an
|
||||
argument. The one-at-a-time checking of types matches the implementation
|
||||
argument. The one-at-a-time checking of types matches the implementation
|
||||
of ``startswith()`` and ``endswith()`` methods.
|
||||
|
||||
The ``self_str[:]`` copying behavior in the code ensures that the
|
||||
``bytearray`` methods do not return ``self``, but it does not preclude
|
||||
the ``str`` and ``bytes`` methods from returning ``self``. Because
|
||||
the ``str`` and ``bytes`` methods from returning ``self``. Because
|
||||
``str`` and ``bytes`` instances are immutable, the ``cutprefix()``
|
||||
and ``cutsuffix()`` methods on these objects methods may (but are not
|
||||
and ``cutsuffix()`` methods on these objects may (but are not
|
||||
required to) make the optimization of returning ``self`` if
|
||||
``type(self) is str`` (``type(self) is bytes`` respectively)
|
||||
and the given affixes are not found, or are empty. As such, following
|
||||
behavior is considered a CPython implementation detail, and is not
|
||||
guaranteed by this specification::
|
||||
and the given affixes are not found, or are empty. As such, the
|
||||
following behavior is considered a CPython implementation detail, and
|
||||
is not guaranteed by this specification::
|
||||
|
||||
>>> x = 'foobar' * 10**6
|
||||
>>> x.cutprefix('baz') is x is x.cutsuffix('baz')
|
||||
|
|
@ -127,7 +128,7 @@ guaranteed by this specification::
|
|||
|
||||
To test whether any affixes were removed during the call, users
|
||||
should use the constant-time behavior of comparing the lengths of
|
||||
original and new strings::
|
||||
the original and new strings::
|
||||
|
||||
>>> string = 'Python String Input'
|
||||
>>> new_string = string.cutprefix("Py")
|
||||
|
|
@ -149,19 +150,18 @@ one or more of the following:
|
|||
|
||||
1. Less fragile:
|
||||
|
||||
- The code will not depend on the user to count the length of a
|
||||
literal.
|
||||
The code will not depend on the user to count the length of a literal.
|
||||
|
||||
2. More performant:
|
||||
|
||||
- The code does not require a call to the Python built-in
|
||||
``len`` function, nor to the more expensive ``str.replace``
|
||||
function.
|
||||
The code does not require a call to the Python built-in ``len``
|
||||
function, nor to the more expensive ``str.replace()``
|
||||
method.
|
||||
|
||||
3. More descriptive:
|
||||
|
||||
- The methods give a higher-level API for code readability, as
|
||||
opposed to the traditional method of string slicing.
|
||||
The methods give a higher-level API for code readability, as
|
||||
opposed to the traditional method of string slicing.
|
||||
|
||||
|
||||
find_recursionlimit.py
|
||||
|
|
@ -305,45 +305,45 @@ Several alternatives method names have been proposed. Some are listed
|
|||
below, along with commentary for why they should be rejected in favor
|
||||
of ``cutprefix`` (the same arguments hold for ``cutsuffix``).
|
||||
|
||||
- ``ltrim``
|
||||
- ``ltrim``, ``trimprefix``, etc.:
|
||||
|
||||
- "Trim" does in other languages (e.g. JavaScript, Java, Go,
|
||||
PHP) what ``strip`` methods do in Python.
|
||||
"Trim" does in other languages (e.g. JavaScript, Java, Go, PHP)
|
||||
what ``strip`` methods do in Python.
|
||||
|
||||
- ``lstrip(string=...)``
|
||||
|
||||
- This would avoid adding a new method, but for different
|
||||
behavior, it's better to have two different methods than one
|
||||
method with a keyword argument that select the behavior.
|
||||
This would avoid adding a new method, but for different
|
||||
behavior, it's better to have two different methods than one
|
||||
method with a keyword argument that select the behavior.
|
||||
|
||||
- ``cut_prefix``
|
||||
- ``cut_prefix``:
|
||||
|
||||
- All of the other methods of the string API, e.g.
|
||||
``str.startswith()``, use ``lowercase`` rather than
|
||||
``lower_case_with_underscores``.
|
||||
All of the other methods of the string API, e.g.
|
||||
``str.startswith()``, use ``lowercase`` rather than
|
||||
``lower_case_with_underscores``.
|
||||
|
||||
- ``cutleft``, ``leftcut``, or ``lcut``
|
||||
- ``cutleft``, ``leftcut``, or ``lcut``:
|
||||
|
||||
- The explicitness of "prefix" is preferred.
|
||||
The explicitness of "prefix" is preferred.
|
||||
|
||||
- ``removeprefix``, ``deleteprefix``, ``withoutprefix``, ``dropprefix``, etc.
|
||||
- ``removeprefix``, ``deleteprefix``, ``withoutprefix``, ``dropprefix``, etc.:
|
||||
|
||||
- All of these might have been acceptable, but they have more
|
||||
characters than ``cut``. Some suggested that the verb "cut"
|
||||
implies mutability, but the string API already contains verbs
|
||||
like "replace", "strip", "split", and "swapcase".
|
||||
All of these might have been acceptable, but they have more
|
||||
characters than ``cut``. Some suggested that the verb "cut"
|
||||
implies mutability, but the string API already contains verbs
|
||||
like "replace", "strip", "split", and "swapcase".
|
||||
|
||||
- ``stripprefix``
|
||||
- ``stripprefix``:
|
||||
|
||||
- Users may benefit from remembering that "strip" means working
|
||||
with sets of characters, while other methods work with
|
||||
substrings, so re-using "strip" here should be avoided.
|
||||
Users may benefit from remembering that "strip" means working
|
||||
with sets of characters, while other methods work with
|
||||
substrings, so re-using "strip" here should be avoided.
|
||||
|
||||
|
||||
Reference Implementation
|
||||
========================
|
||||
|
||||
See the pull request on GitHub [#pr]_.
|
||||
See the pull request on GitHub [#pr]_ (not updated).
|
||||
|
||||
|
||||
References
|
||||
|
|
@ -351,8 +351,18 @@ References
|
|||
|
||||
.. [#pr] GitHub pull request with implementation
|
||||
(https://github.com/python/cpython/pull/18939)
|
||||
.. [#pyid] Discussion on Python-Ideas
|
||||
.. [#pyid] [Python-Ideas] "New explicit methods to trim strings"
|
||||
(https://mail.python.org/archives/list/python-ideas@python.org/thread/RJARZSUKCXRJIP42Z2YBBAEN5XA7KEC3/)
|
||||
.. [3] "Re: [Python-ideas] adding a trim convenience function"
|
||||
(https://mail.python.org/archives/list/python-ideas@python.org/thread/SJ7CKPZSKB5RWT7H3YNXOJUQ7QLD2R3X/#C2W5T7RCFSHU5XI72HG53A6R3J3SN4MV)
|
||||
.. [4] "Re: [Python-Dev] strip behavior provides inconsistent results with certain strings"
|
||||
(https://mail.python.org/archives/list/python-ideas@python.org/thread/XYFQMFPUV6FR2N5BGYWPBVMZ5BE5PJ6C/#XYFQMFPUV6FR2N5BGYWPBVMZ5BE5PJ6C)
|
||||
.. [5] [Python-Dev] "correction of a bug"
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/thread/AOZ7RFQTQLCZCTVNKESZI67PB3PSS72X/#AOZ7RFQTQLCZCTVNKESZI67PB3PSS72X)
|
||||
.. [6] [Python-Dev] "str.lstrip bug?"
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/thread/OJDKRIESKGTQFNLX6KZSGKU57UXNZYAN/#CYZUFFJ2Q5ZZKMJIQBZVZR4NSLK5ZPIH)
|
||||
.. [7] [Python-Dev] "strip behavior provides inconsistent results with certain strings"
|
||||
(https://mail.python.org/archives/list/python-dev@python.org/thread/ZWRGCGANHGVDPP44VQKRIYOYX7LNVDVG/#ZWRGCGANHGVDPP44VQKRIYOYX7LNVDVG)
|
||||
.. [#confusion] Comment listing Bug Tracker and StackOverflow issues
|
||||
(https://mail.python.org/archives/list/python-ideas@python.org/message/GRGAFIII3AX22K3N3KT7RB4DPBY3LPVG/)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue