[issue15148] shutul.which() docstring could be clearer
New submission from Tshepang Lekhonkhobe <tshepang@gmail.com>: 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'? ---------- assignee: docs@python components: Documentation messages: 163515 nosy: docs@python, hynek, tarek, tshepang priority: normal severity: normal status: open title: shutul.which() docstring could be clearer _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- versions: +Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- title: shutul.which() docstring could be clearer -> shutil.which() docstring could be clearer _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset 5975292ddf82 by Alexander Belopolsky in branch 'default': Issue #15148: Fixed typos in shutil.which() docstring http://hg.python.org/cpython/rev/5975292ddf82 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Alexander Belopolsky <alexander.belopolsky@gmail.com> added the comment: *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. ---------- nosy: +belopolsky, brian.curtin _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Brian Curtin <brian@python.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Alexander Belopolsky <alexander.belopolsky@gmail.com> added the comment:
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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Alexander Belopolsky <alexander.belopolsky@gmail.com> added the comment: Brian, Did you intend to commit Tools/msi/msi.py in changeset 973b4806f760? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Brian Curtin <brian@python.org> added the comment: No, reverting. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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." ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- resolution: -> fixed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
Hynek Schlawack added the comment: Any reason why this is still open? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
R. David Murray added the comment: Doesn't look like it. ---------- stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15148> _______________________________________
participants (6)
-
Alexander Belopolsky -
Brian Curtin
-
Hynek Schlawack
-
R. David Murray
-
Roundup Robot
-
Tshepang Lekhonkhobe