From 6182c5d2b3a990b2470ade376940fa7f437ecaf9 Mon Sep 17 00:00:00 2001 From: Eoin Shaughnessy Date: Sun, 19 Apr 2026 20:32:28 +0100 Subject: [PATCH 1/6] gh-148765: Fix description of include_hidden parameter in glob docs --- Doc/library/glob.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 942f23d216fc07..aa068209e949c1 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -70,7 +70,8 @@ The :mod:`!glob` module defines the following functions: pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files will not match. - If *include_hidden* is true, "``**``" pattern will match hidden directories. + If *include_hidden* is true, patterns that do not begin with a dot (``.``) + may also match path components that begin with a dot. .. audit-event:: glob.glob pathname,recursive glob.glob .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.glob From e13d571d30900e4c6c683bd7119d7343f11c4cca Mon Sep 17 00:00:00 2001 From: Eoin Shaughnessy Date: Sun, 5 Jul 2026 18:43:54 +0100 Subject: [PATCH 2/6] Clarify include_hidden wording per review feedback --- Doc/library/glob.rst | 4 ++-- Lib/glob.py | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index aa068209e949c1..95a52f039baa44 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -70,8 +70,8 @@ The :mod:`!glob` module defines the following functions: pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files will not match. - If *include_hidden* is true, patterns that do not begin with a dot (``.``) - may also match path components that begin with a dot. + If *include_hidden* is true, wildcards can match path components that + begin with a dot (``.``). .. audit-event:: glob.glob pathname,recursive glob.glob .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.glob diff --git a/Lib/glob.py b/Lib/glob.py index 575e4bcba5be0d..55d35aa80c8755 100644 --- a/Lib/glob.py +++ b/Lib/glob.py @@ -34,8 +34,8 @@ def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, 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 `include_hidden` is true, wildcards can match path segments beginning + with a dot ('.'). If `recursive` is true, the pattern '**' will match any files and zero or more directories and subdirectories. @@ -64,8 +64,8 @@ def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, 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 `include_hidden` is true, wildcards can match path segments beginning + with a dot ('.'). If `recursive` is true, the pattern '**' will match any files and zero or more directories and subdirectories. From 9f5d4fe2496400941af2240ee41891fd601c9a39 Mon Sep 17 00:00:00 2001 From: Eoin Shaughnessy Date: Sun, 5 Jul 2026 18:54:33 +0100 Subject: [PATCH 3/6] Add NEWS entry for include_hidden docs fix --- .../2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst diff --git a/Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst b/Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst new file mode 100644 index 00000000000000..11a82f47990b41 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst @@ -0,0 +1,3 @@ +Clarify the description of the *include_hidden* parameter in +:func:`glob.glob`, :func:`glob.iglob`, and the :mod:`glob` module +documentation. From 94089bf2efddb2e993f0636c679706b3a0e849cb Mon Sep 17 00:00:00 2001 From: Eoin Shaughnessy <45000144+EoinTrial@users.noreply.github.com> Date: Sun, 5 Jul 2026 19:17:15 +0100 Subject: [PATCH 4/6] Update Doc/library/glob.rst Co-authored-by: Stan Ulbrych --- Doc/library/glob.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 95a52f039baa44..d3acda3b5eb527 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -70,7 +70,7 @@ The :mod:`!glob` module defines the following functions: pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files will not match. - If *include_hidden* is true, wildcards can match path components that + If *include_hidden* is true, wildcards can match path segments that begin with a dot (``.``). .. audit-event:: glob.glob pathname,recursive glob.glob From 05b70cc52c03386f02fc63accb8daed806201839 Mon Sep 17 00:00:00 2001 From: Eoin Shaughnessy Date: Sun, 5 Jul 2026 19:21:00 +0100 Subject: [PATCH 5/6] Address review feedback: reword dot-file note and e.g. -> for example --- Doc/library/glob.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 95a52f039baa44..ef461e3329e834 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -29,7 +29,7 @@ not by actually invoking a subshell. 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 +By default, 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 @@ -132,7 +132,7 @@ The :mod:`!glob` module defines the following functions: Escape all special characters (``'?'``, ``'*'`` and ``'['``). This is useful if you want to match an arbitrary literal string that may have special characters in it. Special characters in drive/UNC - sharepoints are not escaped, e.g. on Windows + sharepoints are not escaped, for example on Windows ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/c:/Quo vadis[?].txt'``. .. versionadded:: 3.4 From 8ad74a110eb2adafc9e79ec6c4dec84e45801060 Mon Sep 17 00:00:00 2001 From: Eoin Shaughnessy Date: Sun, 5 Jul 2026 21:52:41 +0100 Subject: [PATCH 6/6] Remove NEWS entry per review, add self to Misc/ACKS --- Misc/ACKS | 1 + .../2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst | 3 --- 2 files changed, 1 insertion(+), 3 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst diff --git a/Misc/ACKS b/Misc/ACKS index 1f2049da56c2da..21365c39405343 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1755,6 +1755,7 @@ Ha Shao Richard Shapiro Soumya Sharma Varun Sharma +Eoin Shaughnessy Daniel Shaulov Vlad Shcherbina Justin Sheehy diff --git a/Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst b/Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst deleted file mode 100644 index 11a82f47990b41..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2026-07-05-19-00-00.gh-issue-148765.fixglob1.rst +++ /dev/null @@ -1,3 +0,0 @@ -Clarify the description of the *include_hidden* parameter in -:func:`glob.glob`, :func:`glob.iglob`, and the :mod:`glob` module -documentation.