From 9f88a5e5fc089f693e7b0c7c5a63921433ff793e Mon Sep 17 00:00:00 2001 From: WYSIATI Date: Wed, 8 Apr 2026 18:34:44 +0800 Subject: [PATCH 1/2] gh-146646: Document that glob functions suppress OSError --- Doc/library/glob.rst | 10 ++++++++++ Doc/library/pathlib.rst | 10 ++++++++++ .../2026-04-02-07-20-00.gh-issue-146646.GlobDoc1.rst | 3 +++ 3 files changed, 23 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2026-04-02-07-20-00.gh-issue-146646.GlobDoc1.rst diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 52c44928153337..b24e4da7bc8c07 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 2b4aa1ee209997..708a1e8e0dda42 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1351,6 +1351,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 @@ -1380,6 +1385,11 @@ Reading directories .. seealso:: :ref:`pathlib-pattern-language` and :meth:`Path.glob` documentation. + .. 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.rglob self,pattern pathlib.Path.rglob .. versionchanged:: 3.12 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 00000000000000..4e89270442a33b --- /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. From 5912abc959fe7e6befadff84ab34bfb89f477091 Mon Sep 17 00:00:00 2001 From: WYSIATI Date: Thu, 9 Apr 2026 10:58:25 +0800 Subject: [PATCH 2/2] Move OSError note above seealso in Path.rglob() per review --- Doc/library/pathlib.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 708a1e8e0dda42..2867015042ee16 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1382,14 +1382,14 @@ Reading directories The paths are returned in no particular order. If you need a specific order, sort the results. - .. seealso:: - :ref:`pathlib-pattern-language` and :meth:`Path.glob` documentation. - .. 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. + .. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob .. versionchanged:: 3.12