Skip to content

Commit ab1f568

Browse files
jugmac00barneygale
andcommitted
GH-101112: Provide pattern overview for Path.glob
Unlike previously stated, the patterns used for `Path.glob`, `Path.rglob` and `Path.match` do not behave like the ones for `fnmatch`. Remove the refernce to `fnmatch` and provide an overview of the available patterns. Co-authored-by: Barney Gale <[email protected]>
1 parent 3325f05 commit ab1f568

File tree

1 file changed

+22
-6
lines changed

1 file changed

+22
-6
lines changed

Doc/library/pathlib.rst

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -546,8 +546,10 @@ Pure paths provide the following methods and properties:
546546

547547
.. method:: PurePath.match(pattern)
548548

549-
Match this path against the provided glob-style pattern. Return ``True``
550-
if matching is successful, ``False`` otherwise.
549+
Match this path against the provided glob-style pattern. The pattern uses
550+
the same format as in :func:`Path.glob`, except that "``**``" wildcards
551+
behaves just like "``*``". Return ``True`` if matching is successful,
552+
``False`` otherwise.
551553

552554
If *pattern* is relative, the path can be either relative or absolute,
553555
and matching is done from the right::
@@ -574,7 +576,6 @@ Pure paths provide the following methods and properties:
574576
>>> PureWindowsPath('b.py').match('*.PY')
575577
True
576578

577-
578579
.. method:: PurePath.relative_to(other, walk_up=False)
579580

580581
Compute a version of this path relative to the path represented by
@@ -861,7 +862,7 @@ call fails (for example because the path doesn't exist).
861862
>>> sorted(Path('.').glob('*/*.py'))
862863
[PosixPath('docs/conf.py')]
863864

864-
Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``"
865+
Pattern segments are the same as for :mod:`fnmatch`, with the addition of "``**``"
865866
which means "this directory and all subdirectories, recursively". In other
866867
words, it enables recursive globbing::
867868

@@ -872,6 +873,22 @@ call fails (for example because the path doesn't exist).
872873
PosixPath('setup.py'),
873874
PosixPath('test_pathlib.py')]
874875

876+
The following wildcards are available:
877+
878+
+------------+----------------------------------------------------------+
879+
| Pattern | Meaning |
880+
+============+==========================================================+
881+
| ``**`` | matches any number of nested directories |
882+
+------------+----------------------------------------------------------+
883+
| ``*`` | matches any part of a file or directory name |
884+
+------------+----------------------------------------------------------+
885+
| ``?`` | matches any single character in a file or directory name |
886+
+------------+----------------------------------------------------------+
887+
| ``[seq]`` | matches any character in seq |
888+
+------------+----------------------------------------------------------+
889+
| ``[!seq]`` | matches any character not in seq |
890+
+------------+----------------------------------------------------------+
891+
875892
.. note::
876893
Using the "``**``" pattern in large directory trees may consume
877894
an inordinate amount of time.
@@ -1270,8 +1287,7 @@ call fails (for example because the path doesn't exist).
12701287
.. method:: Path.rglob(pattern)
12711288

12721289
Glob the given relative *pattern* recursively. This is like calling
1273-
:func:`Path.glob` with "``**/``" added in front of the *pattern*, where
1274-
*patterns* are the same as for :mod:`fnmatch`::
1290+
:func:`Path.glob` with "``**/``" added in front of the *pattern*::
12751291

12761292
>>> sorted(Path().rglob("*.py"))
12771293
[PosixPath('build/lib/pathlib.py'),

0 commit comments

Comments
 (0)