docs: be clearer that glob results are unordered #140184
Conversation
| .. note:: | ||
| The pathnames are returned in no particular order. If you need a specific | ||
| order, sort the results. | ||
|
|
There was a problem hiding this comment.
There's already "although results are returned in arbitrary order" in the paragraph above. Can you remove that?
There was a problem hiding this comment.
I think it’s ok to repeat the point.
There was a problem hiding this comment.
This is already repeated twice:
"although results are returned in arbitrary order." (9f3c094)
"Whether or not the results are sorted depends on the file system." (52465e1)
The note directive is used to highlight non-obvious details that may require additional attention from the user. If you think this is the case, then this directive should also be used for os.listdir() and os,scandir().
| .. note:: | ||
| The pathnames are returned in no particular order. If you need a specific | ||
| order, sort the results. | ||
|
|
There was a problem hiding this comment.
I think it’s ok to repeat the point.
|
Please don’t. Docs already say order is file system dependent. Brevity is inherently valuable. |
nedbat
force-pushed
the
nedbat/glob-no-order
branch
2 times, most recently
from
a46210d to
56cd062
Compare
nedbat
force-pushed
the
nedbat/glob-no-order
branch
from
56cd062 to
df78ded
Compare
|
I've tweaked the initial paragraph, including removing the mention of order, to let the Note handle it instead. |
hugovk
added
needs backport to 3.13
|
I think saying it once, in a note, at the module level and again for each function (not as a note) is about right. LGTM. |
|
Thanks @nedbat for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14. |
* docs: be clearer that glob results are unordered * trim down the opening paragraph (cherry picked from commit ed672f7) Co-authored-by: Ned Batchelder <[email protected]>
* docs: be clearer that glob results are unordered * trim down the opening paragraph (cherry picked from commit ed672f7) Co-authored-by: Ned Batchelder <[email protected]>
|
GH-140339 is a backport of this pull request to the 3.14 branch. |
|
GH-140340 is a backport of this pull request to the 3.13 branch. |
…140339) (cherry picked from commit ed672f7) Co-authored-by: Ned Batchelder <[email protected]>
…140340) (cherry picked from commit ed672f7) Co-authored-by: Ned Batchelder <[email protected]>
7 participants
From this dpo discussion: https://discuss.python.org/t/should-glob-glob-output-be-stable/104385
📚 Documentation preview 📚: https://cpython-previews--140184.org.readthedocs.build/