[issue25461] Unclear language (the word ineffective) in the documentation for os.walk
New submission from Bernt Røskar Brenna: At least for me (non-english speaker), the following is confusing: "Modifying dirnames when topdown is False is ineffective, because in bottom-up mode the directories in dirnames are generated before dirpath itself is generated." I suggest to replace "is ineffective" with "has no effect". Ineffective could also mean: "Has low performance", could it not? ---------- assignee: docs@python components: Documentation messages: 253338 nosy: Bernt.Røskar.Brenna, docs@python priority: normal severity: normal status: open title: Unclear language (the word ineffective) in the documentation for os.walk type: enhancement versions: Python 2.7, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Ezio Melotti added the comment: Thanks for the report. This sounds like a reasonable request to me. Would you like to make a patch? (If so, you can check the devguide.) ---------- keywords: +easy nosy: +ezio.melotti stage: -> needs patch versions: +Python 3.4, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Bernt Røskar Brenna added the comment: OK, I'll submit a patch ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Changes by STINNER Victor <victor.stinner@gmail.com>: ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Roundup Robot added the comment: New changeset 0286bb18a351 by Victor Stinner in branch '3.4': Issue #25461: Rephrase os.walk() doc https://hg.python.org/cpython/rev/0286bb18a351 New changeset 9f68e41fb4a7 by Victor Stinner in branch '3.5': Merge 3.4 (Issue #25461) https://hg.python.org/cpython/rev/9f68e41fb4a7 New changeset db07937b3e49 by Victor Stinner in branch 'default': Merge 3.4 (Issue #25461) https://hg.python.org/cpython/rev/db07937b3e49 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Roundup Robot added the comment: New changeset 8247dff49113 by Victor Stinner in branch '2.7': Issue #25461: Rephrase os.walk() doc https://hg.python.org/cpython/rev/8247dff49113 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
STINNER Victor added the comment:
If you want to avoid ineffective because its meaning is subtle (a reasonable request), the correct replacement would be "modifying dirnames has no effect on the behavior of the walk", which is wordier but clearer.
I prefer the new sentence, it's more explicit. Maybe I pushed the change too fast. @David: are you ok with the change? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Bernt Røskar Brenna added the comment: Yet another patch, this time including changes to os.walk()'s docstring as well. Ignore the two other files. ---------- Added file: http://bugs.python.org/file40849/os_walk_doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Bernt Røskar Brenna added the comment: A question/comment: In this case (and there are probably other cases like it) - it seems to me that the docstring (in os.py) and the docs (in os.rst) are similar enough that the docstring from the code could be included in the docs (using Sphinx's autodoc). What is the preferred way? Is there a reason to have it the way it is? I notice the .rst docs have some formatting applied, is it considered not OK to put formatting in docstrings? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
STINNER Victor added the comment: We don't use autodoc. It would be "nice" to have a tool to update .rst files from .py and .c files, but it's not the case right now :-/ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Ezio Melotti added the comment: Usually docstrings are short and to the point, and serve more as a remainder, whereas the online docs explain everything in detail. Also rst markup in docstrings would be distractings, so we keep docstrings and online docs separated, even though there is often some overlapping. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
STINNER Victor added the comment: "Also rst markup in docstrings would be distractings, so we keep docstrings and online docs separated, even though there is often some overlapping." Ah yes, and the doc in Doc/ directory contains more information like ".. versionchanged:: (...)", ".. versionadded:: (...)", links to other doc using reST markups, etc. In general, the doc in Doc/ is higher quality than docstrings ;) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Luiz Poleto added the comment: The Doc/library/os.rst bit in the current patch fails to apply in all versions specified in this bug report (it seems that it was generated before the commit that included an earlier version of it). ---------- nosy: +luiz.poleto _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Luiz Poleto added the comment: The change to os.rst is already committed so I modified the patch to remove it and keep only the change to os.py, which looks good and ready to be committed. ---------- Added file: http://bugs.python.org/file42635/issue25461.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________
Change by Jonathan Fine <jfine2358@gmail.com>: ---------- nosy: +jfine2358 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
Joannah Nanjekye <nanjekyejoannah@gmail.com> added the comment: What is the status on this? From this discussion, it looks like @vstinner pushed changes to resolve this. Do we close this? If this still needs a patch, then one of the patches can be reviewed in a PR on GitHub. ---------- nosy: +nanjekyejoannah _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
STINNER Victor <vstinner@redhat.com> added the comment:
What is the status on this? From this discussion, it looks like @vstinner pushed changes to resolve this. Do we close this? If this still needs a patch, then one of the patches can be reviewed in a PR on GitHub.
It seems like os_walk_doc.patch and issue25461.patch have been written after I pushed my changes. Would you be interested to convert these patches into a proper PR? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
Change by Roundup Robot <devnull@psf.upfronthosting.co.za>: ---------- pull_requests: +11867 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
Benjamin Peterson <benjamin@python.org> added the comment: New changeset 734f1202a50641eb2c4bfbcd5b75247c1dc99a8f by Benjamin Peterson (Bernt Røskar Brenna) in branch 'master': closes bpo-25461: Update os.walk() docstring to match the online docs. (GH-11836) https://github.com/python/cpython/commit/734f1202a50641eb2c4bfbcd5b75247c1dc... ---------- nosy: +benjamin.peterson resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +15489 pull_request: https://github.com/python/cpython/pull/15843 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +15490 pull_request: https://github.com/python/cpython/pull/15844 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset c43f26eca35f22707a52fb8f3fbfc9340639b58d by Miss Islington (bot) in branch '3.8': closes bpo-25461: Update os.walk() docstring to match the online docs. (GH-11836) https://github.com/python/cpython/commit/c43f26eca35f22707a52fb8f3fbfc934063... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset d94b762ce824e97c441f9231f0e69ef8f59beeab by Miss Islington (bot) in branch '3.7': closes bpo-25461: Update os.walk() docstring to match the online docs. (GH-11836) https://github.com/python/cpython/commit/d94b762ce824e97c441f9231f0e69ef8f59... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25461> _______________________________________
participants (9)
-
Benjamin Peterson -
Bernt Røskar Brenna
-
Ezio Melotti
-
Joannah Nanjekye
-
Jonathan Fine
-
Luiz Poleto
-
miss-islington
-
Roundup Robot
-
STINNER Victor