From 6fc4c850f5ef0e10c96c6420f8061f67f58cdbb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Gmach?= Date: Sat, 21 Jan 2023 16:28:13 +0100 Subject: [PATCH] GH-101112: Provide pattern overview for Path.glob Provide an overview of available patterns for `Path.glob` and reference it from `Path.rglob` and `Path.match`. Co-authored-by: Barney Gale --- Doc/library/pathlib.rst | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index f222745a2c56bc..e6be53496b0526 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -546,8 +546,10 @@ Pure paths provide the following methods and properties: .. method:: PurePath.match(pattern) - Match this path against the provided glob-style pattern. Return ``True`` - if matching is successful, ``False`` otherwise. + Match this path against the provided glob-style pattern. The pattern uses + the same format as in :func:`Path.glob`, except that "``**``" wildcards + behaves just like "``*``". Return ``True`` if matching is successful, + ``False`` otherwise. If *pattern* is relative, the path can be either relative or absolute, and matching is done from the right:: @@ -574,7 +576,6 @@ Pure paths provide the following methods and properties: >>> PureWindowsPath('b.py').match('*.PY') True - .. method:: PurePath.relative_to(other, walk_up=False) 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). >>> sorted(Path('.').glob('*/*.py')) [PosixPath('docs/conf.py')] - Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``" + Pattern segments are the same as for :mod:`fnmatch`, with the addition of "``**``" which means "this directory and all subdirectories, recursively". In other words, it enables recursive globbing:: @@ -872,6 +873,22 @@ call fails (for example because the path doesn't exist). PosixPath('setup.py'), PosixPath('test_pathlib.py')] + The following wildcards are available: + + +------------+----------------------------------------------------------+ + | 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 | + +------------+----------------------------------------------------------+ + .. note:: Using the "``**``" pattern in large directory trees may consume an inordinate amount of time. @@ -1270,8 +1287,7 @@ call fails (for example because the path doesn't exist). .. method:: Path.rglob(pattern) Glob the given relative *pattern* recursively. This is like calling - :func:`Path.glob` with "``**/``" added in front of the *pattern*, where - *patterns* are the same as for :mod:`fnmatch`:: + :func:`Path.glob` with "``**/``" added in front of the *pattern*:: >>> sorted(Path().rglob("*.py")) [PosixPath('build/lib/pathlib.py'),