Skip to content

Commit

Permalink
pythonGH-101112: Provide pattern overview for Path.glob
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
jugmac00 committed Jan 21, 2023
1 parent 3325f05 commit 23b12d4
Showing 1 changed file with 22 additions and 5 deletions.
27 changes: 22 additions & 5 deletions Doc/library/pathlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -574,6 +574,8 @@ Pure paths provide the following methods and properties:
>>> PureWindowsPath('b.py').match('*.PY')
True

For an overview of available patterns see :meth:`Path.glob`, with the
exception that "``**``" behaves just like "``*``".

.. method:: PurePath.relative_to(other, walk_up=False)

Expand Down Expand Up @@ -861,9 +863,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 "``**``"
which means "this directory and all subdirectories, recursively". In other
words, it enables recursive globbing::
"``**``" enables recursive globbing::

>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
Expand All @@ -872,6 +872,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.
Expand Down Expand Up @@ -1270,8 +1286,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'),
Expand All @@ -1280,6 +1295,8 @@ call fails (for example because the path doesn't exist).
PosixPath('setup.py'),
PosixPath('test_pathlib.py')]

For an overview of available patterns see :meth:`Path.glob`.

.. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob

.. versionchanged:: 3.11
Expand Down

0 comments on commit 23b12d4

Please sign in to comment.