From c5269d7efbd56fea0d14d2926df728d18540c0ea Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 15 Oct 2025 20:37:23 -0400 Subject: [PATCH 1/2] docs: be clearer that glob results are unordered --- Doc/library/glob.rst | 4 ++++ Lib/glob.py | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 59ad1b07f27338..8addcb7d4435bd 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -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. + 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`. diff --git a/Lib/glob.py b/Lib/glob.py index 5d42077003a240..c2f8ce279aba64 100644 --- a/Lib/glob.py +++ b/Lib/glob.py @@ -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. @@ -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. """ From df78deddbe6d0a8556172f31f56c0646f528b490 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 19 Oct 2025 07:53:21 -0400 Subject: [PATCH 2/2] trim down the opening paragraph --- Doc/library/glob.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 8addcb7d4435bd..52c44928153337 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -18,9 +18,9 @@ single: - (minus); in glob-style wildcards single: . (dot); in glob-style wildcards -The :mod:`glob` module finds all the pathnames matching a specified pattern -according to the rules used by the Unix shell, although results are returned in -arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character +The :mod:`!glob` module finds pathnames +using pattern matching rules similar to the Unix shell. +No tilde expansion is done, but ``*``, ``?``, and character 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. @@ -29,16 +29,16 @@ not by actually invoking a subshell. The pathnames are returned in no particular order. If you need a specific order, sort the results. -Note that files beginning with a dot (``.``) can only be matched by +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`. -(For tilde and shell variable expansion, use :func:`os.path.expanduser` and -:func:`os.path.expandvars`.) +For tilde and shell variable expansion, use :func:`os.path.expanduser` and +:func:`os.path.expandvars`. For a literal match, wrap the meta-characters in brackets. For example, ``'[?]'`` matches the character ``'?'``. -The :mod:`glob` module defines the following functions: +The :mod:`!glob` module defines the following functions: .. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, \ @@ -55,7 +55,7 @@ The :mod:`glob` module defines the following functions: If *root_dir* is not ``None``, it should be a :term:`path-like object` specifying the root directory for searching. It has the same effect on - :func:`glob` as changing the current directory before calling it. If + :func:`!glob` as changing the current directory before calling it. If *pathname* is relative, the result will contain paths relative to *root_dir*.