Skip to content

gh-146646: Document that glob functions suppress OSError#147996

Merged
vstinner merged 2 commits intopython:mainfrom
WYSIATI:doc-glob-oserror-suppression
Apr 9, 2026
Merged

gh-146646: Document that glob functions suppress OSError#147996
vstinner merged 2 commits intopython:mainfrom
WYSIATI:doc-glob-oserror-suppression

Conversation

@WYSIATI
Copy link
Copy Markdown
Contributor

@WYSIATI WYSIATI commented Apr 2, 2026 •
edited by github-actions bot
Loading

Summary

  • Add notes to glob.glob() and glob.iglob() documentation that OSError exceptions raised from scanning the filesystem are silently suppressed
  • This includes PermissionError when accessing directories without read permission
  • The pathlib.Path.glob() docs already document this behavior (added in 3.13 via a versionchanged note), but the glob module docs did not mention it

As @vstinner noted in the issue, the glob module ignores all OSError errors (not just access errors) — for example, _iterdir() wraps its scanner in except OSError: return.

📚 Documentation preview 📚: https://cpython-previews--147996.org.readthedocs.build/

@bedevere-app bedevere-app bot added awaiting review docs Documentation in the Doc dir labels Apr 2, 2026
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Apr 2, 2026
@bedevere-app bedevere-app bot mentioned this pull request Apr 2, 2026
Closed
vstinner
vstinner reviewed Apr 7, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue is about pathlib.Path.glob() and pathlib.Path.rglob(). Can you also update their documentation?

@WYSIATI
Copy link
Copy Markdown
Contributor Author

WYSIATI commented Apr 8, 2026

The issue is about pathlib.Path.glob() and pathlib.Path.rglob(). Can you also update their documentation?

Thanks @vstinner for the review, pathlib.Path.glob() already has this documented as a versionchanged:: 3.13 note. Path.rglob() doesn't though — I'll add a matching note there and update the NEWS entry.

@WYSIATI WYSIATI requested a review from barneygale as a code owner April 8, 2026 02:06
vstinner
vstinner reviewed Apr 8, 2026
View reviewed changes
Doc/library/pathlib.rst Outdated
.. versionchanged:: 3.13
Any :exc:`OSError` exceptions raised from scanning the filesystem are
suppressed. In previous versions, such exceptions are suppressed in many
cases, but not all.
Copy link
Copy Markdown
Member

@vstinner vstinner Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you copy the note from the glob module to pathlib .glob() and .rglob() methods? IMO it's worth it to repeat the information (and mention PermissionError).

Copy link
Copy Markdown
Contributor Author

@WYSIATI WYSIATI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, let me do a quick update

vstinner
vstinner reviewed Apr 8, 2026
View reviewed changes
Doc/library/pathlib.rst Outdated
The paths are returned in no particular order.
If you need a specific order, sort the results.

.. note::
Copy link
Copy Markdown
Member

@vstinner vstinner Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer to move the note below, just before "audit-event".

Copy link
Copy Markdown
Contributor Author

@WYSIATI WYSIATI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed, is current doc looking good to you?

@WYSIATI WYSIATI force-pushed the doc-glob-oserror-suppression branch from 4a8f892 to 9f88a5e Compare April 8, 2026 10:34
vstinner
vstinner reviewed Apr 8, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please avoid git push --force, it makes reviews harder to follow.

@WYSIATI
Copy link
Copy Markdown
Contributor Author

WYSIATI commented Apr 9, 2026

Please avoid git push --force, it makes reviews harder to follow.

Thanks for suggesting, I will avoid force push

vstinner
vstinner approved these changes Apr 9, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@vstinner vstinner added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Apr 9, 2026
@vstinner vstinner merged commit 8000a9d into python:main Apr 9, 2026
38 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Apr 9, 2026
@miss-islington-app
Copy link
Copy Markdown

miss-islington-app bot commented Apr 9, 2026

Thanks @WYSIATI for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Apr 9, 2026
@WYSIATI @miss-islington
pythongh-146646: Document that glob functions suppress OSError (pytho…
6d71c4f 
…nGH-147996)

(cherry picked from commit 8000a9de3c0b22f8202898a424c1008e13bd16ce)

Co-authored-by: WYSIATI <chester.lee.cold@gmail.com>
@bedevere-app
Copy link
Copy Markdown

bedevere-app bot commented Apr 9, 2026

GH-148288 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Apr 9, 2026
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Apr 9, 2026
@WYSIATI @miss-islington
pythongh-146646: Document that glob functions suppress OSError (pytho…
fb3865e 
…nGH-147996)

(cherry picked from commit 8000a9d)

Co-authored-by: WYSIATI <chester.lee.cold@gmail.com>
@bedevere-app
Copy link
Copy Markdown

bedevere-app bot commented Apr 9, 2026

GH-148289 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Apr 9, 2026
@vstinner
Copy link
Copy Markdown
Member

vstinner commented Apr 9, 2026

Merged, thanks.

vstinner pushed a commit that referenced this pull request Apr 9, 2026
@miss-islington @WYSIATI
[3.13] gh-146646: Document that glob functions suppress OSError (GH-1…
0438467 
…47996) (#148289)

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

Co-authored-by: WYSIATI <chester.lee.cold@gmail.com>
vstinner pushed a commit that referenced this pull request Apr 9, 2026
@miss-islington @WYSIATI
[3.14] gh-146646: Document that glob functions suppress OSError (GH-1…
d31a16e 
…47996) (#148288)

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

Co-authored-by: WYSIATI <chester.lee.cold@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vstinner vstinner vstinner approved these changes

@barneygale barneygale Awaiting requested review from barneygale barneygale is a code owner

Assignees

No one assigned

Labels

docs Documentation in the Doc dir

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@WYSIATI @vstinner