From: Facundo Batista <facundo@taniquetil.com.ar>
Date: Mon, 2 Mar 2026 11:56:28 +0000 (-0300)
Subject: gh-144835: Added missing explanations for some parameters in glob and iglob. (#144836)
X-Git-Tag: v3.15.0a7~109
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e54225545866d780b12d8e70c33d25fc13b2c3a9;p=thirdparty%2FPython%2Fcpython.git

gh-144835: Added missing explanations for some parameters in glob and iglob. (#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

---------

Co-authored-by: Gregory P. Smith <68491+gpshead@users.noreply.github.com>
---

diff --git a/Lib/glob.py b/Lib/glob.py
index c2f8ce279aba..575e4bcba5be 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`.