classification
Title: Documentation for str.find() is confusing
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: Ted Lemon, docs@python, georg.brandl, orsenthil, python-dev
Priority: normal Keywords: easy

Created on 2015-08-20 02:34 by Ted Lemon, last changed 2016-01-04 02:08 by orsenthil. This issue is now closed.

Messages (6)
msg248872 - (view) Author: Ted Lemon (Ted Lemon) Date: 2015-08-20 02:34
The documentation for str.find() on python.org, for all current versions, says:

Return the lowest index in the string where substring sub is found, such that sub is contained in the slice s[start:end]. Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found.

I think that what is meant here is this:

Return the lowest index in a string s where substring sub is found, such that if a is the returned index, and b == a + len(sub), sub is contained in the slice s[a:b]. Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found.
msg248875 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-08-20 05:49
The "slice" clause is talking about the additional arguments. A clearer version could be 


Return the lowest index in the string where substring sub is found within the slice s[start:end].  Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found.
msg248887 - (view) Author: Ted Lemon (Ted Lemon) Date: 2015-08-20 14:54
Hm, okay, that explains it.   I was previously mystified.  How about this as a refinement on your proposal, though:

Return the lowest index in the string where substring sub is found within the string.  Optional arguments start and end restrict the search to the slice of the string, s[start:end].  Returned index is relative to the beginning of the string, not the beginning of the slice. Return -1 if sub is not found.
msg257433 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-04 02:00
New changeset 7150e8a38c63 by Senthil Kumaran in branch '3.4':
Issue24898 - Improve str.find documentation.
https://hg.python.org/cpython/rev/7150e8a38c63

New changeset 164b564e3c1a by Senthil Kumaran in branch '3.5':
merge from 3.4
https://hg.python.org/cpython/rev/164b564e3c1a

New changeset 136adbcefa5f by Senthil Kumaran in branch 'default':
merge from 3.5
https://hg.python.org/cpython/rev/136adbcefa5f
msg257434 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-04 02:07
New changeset da934a19855b by Senthil Kumaran in branch '2.7':
Backport documentation improvement.
https://hg.python.org/cpython/rev/da934a19855b
msg257435 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-01-04 02:08
Updated the docs as per Georg's suggestion. Thank you Ted Lemon for bringing this up.
History
Date User Action Args
2016-01-04 02:08:31orsenthilsetstatus: open -> closed

assignee: docs@python -> orsenthil
versions: + Python 3.4
nosy: + orsenthil

messages: + msg257435
resolution: fixed
stage: needs patch -> resolved
2016-01-04 02:07:17python-devsetmessages: + msg257434
2016-01-04 02:00:42python-devsetnosy: + python-dev
messages: + msg257433
2016-01-04 00:14:06ezio.melottisetkeywords: + easy
stage: needs patch
type: enhancement
versions: + Python 2.7, Python 3.5
2015-08-20 14:54:13Ted Lemonsetmessages: + msg248887
2015-08-20 05:49:23georg.brandlsetnosy: + georg.brandl
messages: + msg248875
2015-08-20 02:34:48Ted Lemoncreate