From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Thu, 9 Apr 2026 10:51:12 +0000 (+0200)
Subject: [3.13] gh-146646: Document that glob functions suppress OSError (GH-147996) (#148289)
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0438467b2d7faa66b3c90f76e2d15c6c3b8456ff;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-146646: Document that glob functions suppress OSError (GH-147996) (#148289)

gh-146646: Document that glob functions suppress OSError (GH-147996)
(cherry picked from commit 8000a9de3c0b22f8202898a424c1008e13bd16ce)

Co-authored-by: WYSIATI <chester.lee.cold@gmail.com>
---

diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst
index 7580c564494e..9ce031b0133d 100644
--- a/Doc/library/glob.rst
+++ b/Doc/library/glob.rst
@@ -83,6 +83,11 @@ The :mod:`!glob` module defines the following functions:
       This function may return duplicate path names if *pathname*
       contains multiple "``**``" patterns and *recursive* is true.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. versionchanged:: 3.5
       Support for recursive globs using "``**``".
 
@@ -106,6 +111,11 @@ The :mod:`!glob` module defines the following functions:
       This function may return duplicate path names if *pathname*
       contains multiple "``**``" patterns and *recursive* is true.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. versionchanged:: 3.5
       Support for recursive globs using "``**``".
 
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index cfb9971cec8c..11ff4c4bbd44 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1303,6 +1303,11 @@ Reading directories
    ``False``, this method follows symlinks except when expanding "``**``"
    wildcards. Set *recurse_symlinks* to ``True`` to always follow symlinks.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
 
    .. versionchanged:: 3.12
@@ -1329,6 +1334,11 @@ Reading directories
       The paths are returned in no particular order.
       If you need a specific order, sort the results.
 
+   .. note::
+      Any :exc:`OSError` exceptions raised from scanning the filesystem are
+      suppressed. This includes :exc:`PermissionError` when accessing
+      directories without read permission.
+
    .. seealso::
       :ref:`pathlib-pattern-language` and :meth:`Path.glob` documentation.
 
diff --git a/Misc/NEWS.d/next/Documentation/2026-04-02-07-20-00.gh-issue-146646.GlobDoc1.rst b/Misc/NEWS.d/next/Documentation/2026-04-02-07-20-00.gh-issue-146646.GlobDoc1.rst
new file mode 100644
index 000000000000..4e89270442a3
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-04-02-07-20-00.gh-issue-146646.GlobDoc1.rst
@@ -0,0 +1,3 @@
+Document that :func:`glob.glob`, :func:`glob.iglob`,
+:meth:`pathlib.Path.glob`, and :meth:`pathlib.Path.rglob` silently suppress
+:exc:`OSError` exceptions raised from scanning the filesystem.