shutil.which() docstring could be clearer

[tshepang]

BPO	15148
Nosy	@abalkin, @tarekziade, @bitdancer, @briancurtin, @hynek

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-11-02.11:43:20.948>
created_at = <Date 2012-06-23.01:16:28.498>
labels = ['docs']
title = 'shutil.which() docstring could be clearer'
updated_at = <Date 2012-11-02.11:43:20.947>
user = 'https://bugs.python.org/tshepang'

bugs.python.org fields:

activity = <Date 2012-11-02.11:43:20.947>
actor = 'r.david.murray'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-11-02.11:43:20.948>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2012-06-23.01:16:28.498>
creator = 'tshepang'
dependencies = []
files = []
hgrepos = []
issue_num = 15148
keywords = []
message_count = 11.0
messages = ['163515', '163517', '163518', '163519', '163520', '163523', '163524', '163527', '163528', '174493', '174505']
nosy_count = 8.0
nosy_names = ['belopolsky', 'tarek', 'r.david.murray', 'brian.curtin', 'docs@python', 'tshepang', 'python-dev', 'hynek']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue15148'
versions = ['Python 3.3']

[tshepang]

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'?

[python-dev]

New changeset 5975292ddf82 by Alexander Belopolsky in branch 'default':
Issue bpo-15148: Fixed typos in shutil.which() docstring
http://hg.python.org/cpython/rev/5975292ddf82

[abalkin]

*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.

[briancurtin]

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.

[abalkin]

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.

[abalkin]

Brian,

Did you intend to commit Tools/msi/msi.py in changeset 973b4806f760?

[briancurtin]

No, reverting.

[bitdancer]

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."

[python-dev]

New changeset 5f18d9d34f73 by Brian Curtin in branch 'default':
Fix bpo-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 bpo-15148. Capitalize PATH, hopefully leading to less confusion
http://hg.python.org/cpython/rev/aa153b827d17

[hynek]

Any reason why this is still open?

[bitdancer]

Doesn't look like it.