| msg253338 - (view) |
Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) * |
Date: 2015-10-22 17:05 |
| 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? |
|
|
| msg253339 - (view) |
Author: Ezio Melotti (ezio.melotti) *  |
Date: 2015-10-22 17:10 |
| 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.) |
|
|
| msg253340 - (view) |
Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) * |
Date: 2015-10-22 17:15 |
| OK, I'll submit a patch |
|
|
| msg253342 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2015-10-22 17:31 |
| As an English speaker, I prefer ineffective. Modifying dirnames does have an effect, it modifies dirnames. What it doesn't do (is ineffective at) is thereby altering the behavior of walk. 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. |
|
|
| msg253372 - (view) |
Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) * |
Date: 2015-10-23 09:46 |
| I agree your suggestion is better, I did not see it before submitting my first patch. I've added another patch. |
|
|
| msg253375 - (view) |
Author: Roundup Robot (python-dev)  |
Date: 2015-10-23 10:39 |
| 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 |
|
|
| msg253376 - (view) |
Author: Roundup Robot (python-dev) |
Date: 2015-10-23 10:42 |
| New changeset 8247dff49113 by Victor Stinner in branch '2.7': Issue #25461: Rephrase os.walk() doc https://hg.python.org/cpython/rev/8247dff49113 |
|
|
| msg253377 - (view) |
Author: STINNER Victor (vstinner) * |
Date: 2015-10-23 10:51 |
| > 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? |
|
|
| msg253379 - (view) |
Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) * |
Date: 2015-10-23 12:30 |
| Yet another patch, this time including changes to os.walk()'s docstring as well. Ignore the two other files. |
|
|
| msg253380 - (view) |
Author: Bernt Røskar Brenna (Bernt.Røskar.Brenna) * |
Date: 2015-10-23 13:04 |
| 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? |
|
|
| msg253381 - (view) |
Author: STINNER Victor (vstinner) * |
Date: 2015-10-23 13:07 |
| 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 :-/ |
|
|
| msg253382 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2015-10-23 13:10 |
| 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. |
|
|
| msg253383 - (view) |
Author: STINNER Victor (vstinner) * |
Date: 2015-10-23 13:15 |
| "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 ;) |
|
|
| msg263869 - (view) |
Author: Luiz Poleto (luiz.poleto) * |
Date: 2016-04-21 02:50 |
| 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). |
|
|
| msg264410 - (view) |
Author: Luiz Poleto (luiz.poleto) * |
Date: 2016-04-28 04:36 |
| 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. |
|
|
| msg335289 - (view) |
Author: Joannah Nanjekye (nanjekyejoannah) * |
Date: 2019-02-12 06:52 |
| 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. |
|
|
| msg335301 - (view) |
Author: STINNER Victor (vstinner) * |
Date: 2019-02-12 13:01 |
| > 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 .patch have been written after I pushed my changes. Would you be interested to convert these patches into a proper PR? |
|
|
| msg351629 - (view) |
Author: Benjamin Peterson (benjamin.peterson) * |
Date: 2019-09-10 12:44 |
| 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/734f1202a50641eb2c4bfbcd5b75247c1dc99a8f |
|
|
| msg351646 - (view) |
Author: miss-islington (miss-islington) |
Date: 2019-09-10 13:22 |
| 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/c43f26eca35f22707a52fb8f3fbfc9340639b58d |
|
|
| msg351656 - (view) |
Author: miss-islington (miss-islington) |
Date: 2019-09-10 13:34 |
| 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/d94b762ce824e97c441f9231f0e69ef8f59beeab |
|
|