classification
Title: shutil.which() docstring could be clearer
Type: Stage: resolved
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, brian.curtin, docs@python, hynek, python-dev, r.david.murray, tarek, tshepang
Priority: normal Keywords:

Created on 2012-06-23 01:16 by tshepang, last changed 2012-11-02 11:43 by r.david.murray. This issue is now closed.

Messages (11)
msg163515 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-06-23 01:16
I find this a little hard to parse (ignoring the obvious typo and the grammar error):

"""
Given a file, mode, and a path string, return the path whichs conform to the given mode on the path.
"""

One other suggestion: wouldn't 'file' read better as 'command'?
msg163517 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-06-23 01:56
New changeset 5975292ddf82 by Alexander Belopolsky in branch 'default':
Issue #15148: Fixed typos in shutil.which() docstring
http://hg.python.org/cpython/rev/5975292ddf82
msg163518 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-06-23 02:09
*file* is correct because shutil.which() is more general than shell which command.  (It can be used to find source files on PYTHONPATH, for example.)

I think the confusing part is "return the path ... on the path."  This can be fixed in reST by marking the second "path" as the argument, but the docstring should be rephrased.  Note that reST documentation for shutil.which() is missing in Doc/library/shutil.rst.
msg163519 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2012-06-23 02:17
I updated file to command in 973b4806f760. It needs to be command so it matches the implementation's argument name, and because it doesn't exactly take a file.

Alexander, can you explain the part about finding a file on PYTHONPATH? I don't think this has anything to do with shutil.which, or at least I have no idea how it would.
msg163520 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-06-23 02:25
> Alexander, can you explain the part about finding a file on PYTHONPATH?

I thought about something like this:

>>> shutil.which('shutil.py', os.F_OK, ':'.join(sys.path))
'/Users/sasha/Work/python-hg/py3k/Lib/shutil.py'

but win32 code seems to assume a search for a command.
msg163523 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-06-23 02:34
Brian,

Did you intend to commit Tools/msi/msi.py in changeset 973b4806f760?
msg163524 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2012-06-23 02:36
No, reverting.
msg163527 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-06-23 03:27
Yeah, Brian had it as 'file' before, and I asked him to change it because it is confusing.  'file' sounds like a Python file object, which this is not.  'filename' would be OK, but 'cmd', as you note, is what it is really about.

One possibility for the path confusion is to capitalize the references to the system path, since both posix and windows capitalize it.:

"Given a name, mode, and PATH, return the path to the first file which conforms to the given mode found on the PATH, or None if there is no such file.  mode defaults to os.F_OK|os.X_OK.  PATH can be specified via the path argument, if not specified it defaults to the PATH set in the environment."
msg163528 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-06-23 03:49
New changeset 5f18d9d34f73 by Brian Curtin in branch 'default':
Fix #15148. Make the shutil.which docstring more thorough
http://hg.python.org/cpython/rev/5f18d9d34f73

New changeset aa153b827d17 by Brian Curtin in branch 'default':
Fix #15148. Capitalize PATH, hopefully leading to less confusion
http://hg.python.org/cpython/rev/aa153b827d17
msg174493 - (view) Author: Hynek Schlawack (hynek) * (Python committer) Date: 2012-11-02 07:20
Any reason why this is still open?
msg174505 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-11-02 11:43
Doesn't look like it.
History
Date User Action Args
2012-11-02 11:43:20r.david.murraysetstatus: open -> closed

messages: + msg174505
stage: resolved
2012-11-02 07:20:40hyneksetmessages: + msg174493
2012-06-29 18:55:53tshepangsetresolution: fixed
2012-06-23 03:49:27python-devsetmessages: + msg163528
2012-06-23 03:27:46r.david.murraysetnosy: + r.david.murray
messages: + msg163527
2012-06-23 02:36:42brian.curtinsetmessages: + msg163524
2012-06-23 02:34:44belopolskysetmessages: + msg163523
2012-06-23 02:25:41belopolskysetmessages: + msg163520
2012-06-23 02:17:00brian.curtinsetmessages: + msg163519
2012-06-23 02:09:46belopolskysetnosy: + belopolsky, brian.curtin
messages: + msg163518
2012-06-23 01:56:48python-devsetnosy: + python-dev
messages: + msg163517
2012-06-23 01:17:18tshepangsettitle: shutul.which() docstring could be clearer -> shutil.which() docstring could be clearer
2012-06-23 01:16:38tshepangsetversions: + Python 3.3
2012-06-23 01:16:28tshepangcreate