greg/cpython
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: be clearer that glob results are unordered (#140184)

Browse Source 
* docs: be clearer that glob results are unordered

* trim down the opening paragraph
This commit is contained in:
Ned Batchelder
2025-10-19 16:16:35 -04:00
committed by GitHub
parent f9323213c9
commit ed672f7a8a
2 changed files with 18 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
Doc/library/glob.rst
View File

@@ -18,23 +18,27 @@
single: - (minus); in glob-style wildcards single: - (minus); in glob-style wildcards
single: . (dot); in glob-style wildcards single: . (dot); in glob-style wildcards
The :mod:`glob` module finds all the pathnames matching a specified pattern The :mod:`!glob` module finds pathnames
according to the rules used by the Unix shell, although results are returned in using pattern matching rules similar to the Unix shell.
arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character No tilde expansion is done, but ``*``, ``?``, and character
ranges expressed with ``[]`` will be correctly matched. This is done by using ranges expressed with ``[]`` will be correctly matched. This is done by using
the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and
not by actually invoking a subshell. not by actually invoking a subshell.
Note that files beginning with a dot (``.``) can only be matched by .. note::
The pathnames are returned in no particular order. If you need a specific
order, sort the results.
Files beginning with a dot (``.``) can only be matched by
patterns that also start with a dot, patterns that also start with a dot,
unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`. unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`.
(For tilde and shell variable expansion, use :func:`os.path.expanduser` and For tilde and shell variable expansion, use :func:`os.path.expanduser` and
:func:`os.path.expandvars`.) :func:`os.path.expandvars`.
For a literal match, wrap the meta-characters in brackets. For a literal match, wrap the meta-characters in brackets.
For example, ``'[?]'`` matches the character ``'?'``. 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, \ .. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, \
@@ -51,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` 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 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 *pathname* is relative, the result will contain paths relative to
*root_dir*. *root_dir*.

6
Lib/glob.py
View File

@@ -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 '?' dot are special cases that are not matched by '*' and '?'
patterns by default. 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 If `include_hidden` is true, the patterns '*', '?', '**' will match hidden
directories. 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 '?' dot are special cases that are not matched by '*' and '?'
patterns. 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 If recursive is true, the pattern '**' will match any files and
zero or more directories and subdirectories. zero or more directories and subdirectories.
""" """