From a75f0bd4760b5f02b10c90d3f0033b03dcbf515d Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 2 Mar 2026 14:32:13 +0100 Subject: [PATCH] [3.13] gh-144835: Added missing explanations for some parameters in glob and iglob. (GH-144836) (#145416) Co-authored-by: Facundo Batista Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com> --- Lib/glob.py | 27 ++++++++++++++++--- ...-02-15-12-02-20.gh-issue-144835.w_oS_J.rst | 2 ++ 2 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2026-02-15-12-02-20.gh-issue-144835.w_oS_J.rst diff --git a/Lib/glob.py b/Lib/glob.py index f45177fb70fe..3fec2aa97e6a 100644 --- a/Lib/glob.py +++ b/Lib/glob.py @@ -15,7 +15,7 @@ __all__ = ["glob", "iglob", "escape", "translate"] def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False): - """Return a list of paths matching a pathname pattern. + """Return a list of paths matching a `pathname` pattern. The pattern may contain simple shell-style wildcards a la fnmatch. Unlike fnmatch, filenames starting with a @@ -25,6 +25,15 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, The order of the returned list is undefined. Sort it if you need a particular order. + If `root_dir` is not None, it should be a path-like object specifying the + root directory for searching. It has the same effect as changing the + current directory before calling it (without actually + changing it). If pathname is relative, the result will contain + paths relative to `root_dir`. + + If `dir_fd` is not None, it should be a file descriptor referring to a + directory, and paths will then be relative to that directory. + If `include_hidden` is true, the patterns '*', '?', '**' will match hidden directories. @@ -36,7 +45,7 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False): - """Return an iterator which yields the paths matching a pathname pattern. + """Return an iterator which yields the paths matching a `pathname` pattern. The pattern may contain simple shell-style wildcards a la fnmatch. However, unlike fnmatch, filenames starting with a @@ -46,7 +55,19 @@ def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, 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 `root_dir` is not None, it should be a path-like object specifying + the root directory for searching. It has the same effect as changing + the current directory before calling it (without actually + changing it). If pathname is relative, the result will contain + paths relative to `root_dir`. + + If `dir_fd` is not None, it should be a file descriptor referring to a + directory, and paths will then be relative to that directory. + + If `include_hidden` is true, the patterns '*', '?', '**' will match hidden + directories. + + If `recursive` is true, the pattern '**' will match any files and zero or more directories and subdirectories. """ sys.audit("glob.glob", pathname, recursive) diff --git a/Misc/NEWS.d/next/Library/2026-02-15-12-02-20.gh-issue-144835.w_oS_J.rst b/Misc/NEWS.d/next/Library/2026-02-15-12-02-20.gh-issue-144835.w_oS_J.rst new file mode 100644 index 000000000000..9d603b51c48a --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-02-15-12-02-20.gh-issue-144835.w_oS_J.rst @@ -0,0 +1,2 @@ +Added missing explanations for some parameters in :func:`glob.glob` and +:func:`glob.iglob`. -- 2.47.3