classification
Title: string.strip() documentation is misleading
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: BreamoreBoy, PhoenixofMT, docs@python, python-dev, r.david.murray, rhettinger, terry.reedy, willingc
Priority: normal Keywords: patch

Created on 2015-05-15 20:49 by PhoenixofMT, last changed 2015-05-23 16:12 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
iss24204.patch willingc, 2015-05-16 18:16 review
iss24204b.patch willingc, 2015-05-23 16:05 review
Messages (9)
msg243283 - (view) Author: Jim (PhoenixofMT) Date: 2015-05-15 20:49
This probably applies to all versions with the strip() method, but I'm using 3.4. Section 4.7.1 of the documentation has a poorly worded description/example for the behaviour of string.strip([chars]).

A casual reading of "The chars argument is not a prefix or suffix; rather, all combinations of its values are stripped" lead me to believe this

>>> '0.0'.strip('.')
'0.0'

should be equivalent to the solution I found later

>>> '0.0'.replace('.', '')
'00'

The bit about [chars] requires recursive thinking ("are _stripped_") and clouds the fact that strip() iterates from beginning and end, discarding characters until it reaches a character that isn't in [chars].

In the example, it's not obvious (or wasn't to me) that the 'm' wasn't removed from 'example', and the missing periods gave the impression that they had been removed from the middle of the string instead of iterated to from the ends.

I can't think of a good way to rewrite the description, but perhaps you could borrow an example from rstrip() and add/replace:

>>> 'mississippi'.strip('mip')
'ssiss'

The glaring existence of that 'i' in the middle, when all others have been removed makes the limitation clear.

>>> '    hello world    '.strip()
'hello world'

Makes another good example.

Just trying to save someone else 20 minutes of confusion.
msg243284 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2015-05-15 21:28
https://docs.python.org/3/library/stdtypes.html#str.strip first sentence "Return a copy of the string with the leading and trailing characters removed."  How can that be reworded to make it clearer?
msg243289 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-05-16 00:14
Indeed, the sentence that confused you was added because people were continually confused by the fact that doing:

   'foo.boo'.strip('.boo')

would result in 'f' rather than 'foo'.

We would welcome an improvement, but apparently this is very hard to make clear.

Repeating the mississippi example is probably a good idea.
msg243314 - (view) Author: Jim (PhoenixofMT) Date: 2015-05-16 13:43
Maybe, "... all combinations of its values are stripped from the beginning and end."

It is rather difficult to be both clear AND concise. Heck, I'm having trouble just trying to explain it.

Mark, that part is clear, but I think somehow reiterating how the method works would be helpful to someone who is only familiar with a handful of the string methods, knows strip() removes characters, sees that several characters can be specified, and assumes that all such characters will be removed.

As it is, it's sort of like a puzzle that's glaringly obvious once you figure it out, but frustrating in proportion to the amount of time spent figuring. Almost more trouble to figure out how to explain it without turning it into a tutorial than it is to sort it out on your own at the console.
msg243347 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-05-16 18:16
Additional text added about stripping characters from the leading end and trailing end of the string. An additional example that illustrates the outer characters being stripped while the inner string characters, even though matching the chars set of characters, remain.
msg243839 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-05-22 16:34
With 'leading end' and 'trailing end' replaced by 'left and 'right', the addition looks good to me.
msg243855 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-05-22 22:03
This patch looks reasonable.
msg243930 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-05-23 16:05
Updated patch with Terry's suggested changes. Thanks Terry and Raymond for the review of the initial patch.
msg243931 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-05-23 16:12
New changeset 367e3923532f by Raymond Hettinger in branch 'default':
Issue #24204:  Elaborate of the str.strip() documentation.
https://hg.python.org/cpython/rev/367e3923532f
History
Date User Action Args
2015-05-23 16:12:53rhettingersetstatus: open -> closed
2015-05-23 16:12:26rhettingersetassignee: docs@python -> rhettinger
resolution: fixed
stage: patch review -> resolved
2015-05-23 16:12:04python-devsetnosy: + python-dev
messages: + msg243931
2015-05-23 16:05:32willingcsetfiles: + iss24204b.patch

messages: + msg243930
2015-05-22 22:03:14rhettingersetnosy: + rhettinger
messages: + msg243855
2015-05-22 16:34:54terry.reedysetnosy: + terry.reedy
messages: + msg243839
2015-05-16 18:16:50willingcsetfiles: + iss24204.patch

nosy: + willingc
messages: + msg243347

keywords: + patch
stage: patch review
2015-05-16 13:43:19PhoenixofMTsetmessages: + msg243314
2015-05-16 00:14:36r.david.murraysetnosy: + r.david.murray
messages: + msg243289
2015-05-15 21:28:19BreamoreBoysetnosy: + BreamoreBoy
messages: + msg243284
2015-05-15 20:49:36PhoenixofMTcreate