Skip to content

docs: be clearer that glob results are unordered #140184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: be clearer that glob results are unordered #140184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Doc/library/glob.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ ranges expressed with ``[]`` will be correctly matched. This is done by using
the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and
not by actually invoking a subshell.

.. note::
The pathnames are returned in no particular order. If you need a specific
order, sort the results.

Comment on lines +28 to +31
Copy link
Contributor

@nineteendo nineteendo Oct 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's already "although results are returned in arbitrary order" in the paragraph above. Can you remove that?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it’s ok to repeat the point.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 that files beginning with a dot (``.``) can only be matched by
patterns that also start with a dot,
unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`.
Expand Down
6 changes: 6 additions & 0 deletions Lib/glob.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
dot are special cases that are not matched by '*' and '?'
patterns by default.
The order of the returned list is undefined. Sort it if you need a
particular order.
If `include_hidden` is true, the patterns '*', '?', '**' will match hidden
directories.
Expand All @@ -40,6 +43,9 @@ def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False,
dot are special cases that are not matched by '*' and '?'
patterns.
The order of the returned paths is undefined. Sort them if you need a
particular order.
If recursive is true, the pattern '**' will match any files and
zero or more directories and subdirectories.
"""
Expand Down
Loading