Path.rglob -> documentation does not specify what pattern is

[jugmac00]

Documentation

Today I came across Path.rglob in our codebase.

I went to https://docs.python.org/3/library/pathlib.html#pathlib.Path.rglob and tried to find out what pattern actually is. While the current documentation links to Path.glob(), I would like to add a note similar you can find at https://docs.python.org/3/library/pathlib.html#pathlib.Path.glob, ie

Patterns are the same as for fnmatch

Would a PR be welcome to add this kind of information?

Linked PRs

• GH-101112: Specify type of pattern for Path.rglob #101132
• GH-101112: Provide pattern overview for Path.glob #101223
• GH-101112: Add "pattern language" section to pathlib docs #114030

[barneygale]

The documentation for glob() is wrong - the pattern is interpreted differently by fnmatch. In fnmatch(), the * wildcard can match directory separators, but in glob() it can't. The ** wildcard matches separators in glob(), but it can only appear in its own path segment.

It should probably say "patterns are the same as for glob.glob()"

[jugmac00]

Thanks!

I will update my current PR, and I will also fix the documentation for Path.glob.

[jugmac00]

On a second thought, and after reading the documentation for glob.glob(), I am not sure whether linking to it directly would be very helpful.

• unlike the fnmatch documentation there is no syntax overview
• unlike the fnmatch documentation there are no explanations (there are some above that paragraph)
• glob.glob() has options to change its scope, ie include subdirectories and hidden directories; Path.glob does not have any options; just linking to glob.glob() would leave the reader in the dark whether Path.glob include these or not
• the introductory paragraph mentions (emphasis on unlike)

Note that files beginning with a dot (.) can only be matched by patterns that also start with a dot, unlike fnmatch.fnmatch() or pathlib.Path.glob()

I think linking to glob.glob() would cause more confusion - at least as it is now.

@barneygale What do you think of adding a pattern syntax table (similar to the one for fnmatch) to Path.glob and then link from Path.rglob to Path.glob? Or would that overstate the case? Or maybe I miss something.

[barneygale]

@barneygale What do you think of adding a pattern syntax table (similar to the one for fnmatch) to Path.glob and then link from Path.rglob to Path.glob? Or would that overstate the case? Or maybe I miss something.

I think that's an excellent idea. Perhaps something like:

Pattern	Meaning
**	matches any number of nested directories
*	matches any part of a file or directory name
?	matches any single character in a file or directory name
[seq]	matches any character in seq
[!seq]	matches any character not in seq

[barneygale]

The docs for PurePath.match() should also link to the table, but should note that ** is unsupported and works just like *.

[barneygale]

Sorted in the 3.13 docs. Can backport if folks are interested, but it'll need to be a little different due to the introduction of full_match() in 3.13, and the fix for patterns ending **. Thanks for reporting @jugmac00.