From d828bac30c224fc3b689dec2770eb97d286b2f1b Mon Sep 17 00:00:00 2001 From: Facundo Batista Date: Mon, 2 Mar 2026 08:56:28 -0300 Subject: [PATCH] gh-144835: Added missing explanations for some parameters in glob and iglob. (GH-144836) * Added missing explanations for some parameters in glob and iglob. * News entry. * Added proper 'func' indication in News file. * Consistent use of backticks. * Improved wording. * consistent wording between the two docstrings --------- (cherry picked from commit e54225545866d780b12d8e70c33d25fc13b2c3a9) 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 f45177fb70fea4..3fec2aa97e6ae0 100644 --- a/Lib/glob.py +++ b/Lib/glob.py @@ -15,7 +15,7 @@ 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 00000000000000..9d603b51c48a93 --- /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`.