gh-144835: Added missing explanations for some parameters in glob and iglob.#144836
Open
facundobatista wants to merge 4 commits intopython:mainfrom
Open
gh-144835: Added missing explanations for some parameters in glob and iglob.#144836facundobatista wants to merge 4 commits intopython:mainfrom
facundobatista wants to merge 4 commits intopython:mainfrom
Conversation
hugovk
reviewed
Feb 15, 2026
Comment on lines
+57
to
+66
| 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. |
Member
There was a problem hiding this comment.
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:
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. |
|
|
||
| def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, | ||
| include_hidden=False): | ||
| """Return an iterator which yields the paths matching a pathname pattern. |
Member
There was a problem hiding this comment.
Suggested change
| """Return an iterator which yields the paths matching a `pathname` pattern. |
Comment on lines
+28
to
+34
| 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. |
Member
There was a problem hiding this comment.
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. |
Member
There was a problem hiding this comment.
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?)
terryjreedy
requested changes
Feb 15, 2026
Member
terryjreedy
left a comment
There was a problem hiding this comment.
I agree with Hugo's suggestions, and yes, backport.
|
When you're done making the requested changes, leave the comment: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I took the explanations for the missing parameters from the documentation itself (slightly edited for brevity) for the cases of
root_diranddir_fdin bothglobandiglob.For the case of
iglob'sinclude_hidden, I just copied it fromglob.