Skip to content

gh-144835: Added missing explanations for some parameters in glob and iglob. #144836

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
facundobatista wants to merge 4 commits into
base: main
Choose a base branch
from
+21 −0
Open

gh-144835: Added missing explanations for some parameters in glob and iglob. #144836

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
abb4ca7
Added missing explanations for some parameters in glob and iglob.
facundobatista Feb 15, 2026
7c16dc8
News entry.
facundobatista Feb 15, 2026
1aa3725
Merge branch 'main' into improve-globglob-docstrings
facundobatista Feb 15, 2026
917fc00
Added proper 'func' indication in News file.
facundobatista Feb 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions Lib/glob.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,14 @@ 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. 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.
Comment on lines +28 to +34
Copy link
Member

@hugovk hugovk Feb 15, 2026

Choose a reason for hiding this comment

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

Suggested change
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. 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 `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. 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.

Copy link
Member

@gpshead gpshead Feb 16, 2026

Choose a reason for hiding this comment

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

I'm wary of "It has the same effect as changing the current directory before calling it" phrasing as we don't want anyone to think that the process wide global cwd is changed by these API calls. I think it may be better to state what the default behavior is when not specified or None. ie "if not specified or None, the search will be conducted from the processes current working directory and returned paths will be relative to that" (Q: is that accurate?)


If `include_hidden` is true, the patterns '*', '?', '**' will match hidden
directories.

Expand All @@ -46,6 +54,17 @@ 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 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. 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.
Comment on lines +57 to +66
Copy link
Member

@hugovk hugovk Feb 15, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

We should be consistent with backticks for args, either use for all or none.

I do see that PyCharm shows them in italics, so there is a benefit to using them as it makes the text more readable:

Image
Suggested change
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. 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 `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. 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.
"""
Expand Down
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Library/2026-02-15-12-02-20.gh-issue-144835.w_oS_J.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Added missing explanations for some parameters in :func:`glob.glob` and
:func:`glob.iglob`.
Loading