pFad - Phone/Frame/Anonymizer/Declutterfier! Saves Data!


--- a PPN by Garber Painting Akron. With Image Size Reduction included!

URL: http://github.com/python/cpython/commit/e921f09c8a7eb2ab24e8a782b65531ee5afb291a

9241e157469407.css" /> GH-101112: Add "pattern language" section to pathlib docs (#114030) · python/cpython@e921f09 · GitHub
Skip to content

Commit e921f09

Browse files
barneygalebarneygale
authored
GH-101112: Add "pattern language" section to pathlib docs (#114030)
Explain the `full_match()` / `glob()` / `rglob()` pattern language in its own section. Move `rglob()` documentation under `glob()` and reduce duplicated text.
1 parent 92ce41c commit e921f09

File tree

1 file changed

+103
-56
lines changed

1 file changed

+103
-56
lines changed

‎Doc/library/pathlib.rst‎

Lines changed: 103 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -572,6 +572,9 @@ Pure paths provide the following methods and properties:
572572
>>> PurePath('/a/b/c.py').full_match('**/*.py')
573573
True
574574

575+
.. seealso::
576+
:ref:`pathlib-pattern-language` documentation.
577+
575578
As with other methods, case-sensitivity follows platform defaults::
576579

577580
>>> PurePosixPath('b.py').full_match('*.PY')
@@ -991,25 +994,15 @@ call fails (for example because the path doesn't exist).
991994
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
992995
>>> sorted(Path('.').glob('*/*.py'))
993996
[PosixPath('docs/conf.py')]
994-
995-
Patterns are the same as for :mod:`fnmatch`, with the addition of "``**``"
996-
which means "this directory and all subdirectories, recursively". In other
997-
words, it enables recursive globbing::
998-
999997
>>> sorted(Path('.').glob('**/*.py'))
1000998
[PosixPath('build/lib/pathlib.py'),
1001999
PosixPath('docs/conf.py'),
10021000
PosixPath('pathlib.py'),
10031001
PosixPath('setup.py'),
10041002
PosixPath('test_pathlib.py')]
10051003

1006-
.. note::
1007-
Using the "``**``" pattern in large directory trees may consume
1008-
an inordinate amount of time.
1009-
1010-
.. tip::
1011-
Set *follow_symlinks* to ``True`` or ``False`` to improve performance
1012-
of recursive globbing.
1004+
.. seealso::
1005+
:ref:`pathlib-pattern-language` documentation.
10131006

10141007
This method calls :meth:`Path.is_dir` on the top-level directory and
10151008
propagates any :exc:`OSError` exception that is raised. Subsequent
@@ -1025,11 +1018,11 @@ call fails (for example because the path doesn't exist).
10251018
wildcards. Set *follow_symlinks* to ``True`` to always follow symlinks, or
10261019
``False`` to treat all symlinks as files.
10271020

1028-
.. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
1021+
.. tip::
1022+
Set *follow_symlinks* to ``True`` or ``False`` to improve performance
1023+
of recursive globbing.
10291024

1030-
.. versionchanged:: 3.11
1031-
Return only directories if *pattern* ends with a pathname components
1032-
separator (:data:`~os.sep` or :data:`~os.altsep`).
1025+
.. audit-event:: pathlib.Path.glob self,pattern pathlib.Path.glob
10331026

10341027
.. versionchanged:: 3.12
10351028
The *case_sensitive* parameter was added.
@@ -1038,12 +1031,29 @@ call fails (for example because the path doesn't exist).
10381031
The *follow_symlinks* parameter was added.
10391032

10401033
.. versionchanged:: 3.13
1041-
Return files and directories if *pattern* ends with "``**``". In
1042-
previous versions, only directories were returned.
1034+
The *pattern* parameter accepts a :term:`path-like object`.
1035+
1036+
1037+
.. method:: Path.rglob(pattern, *, case_sensitive=None, follow_symlinks=None)
1038+
1039+
Glob the given relative *pattern* recursively. This is like calling
1040+
:func:`Path.glob` with "``**/``" added in front of the *pattern*.
1041+
1042+
.. seealso::
1043+
:ref:`pathlib-pattern-language` and :meth:`Path.glob` documentation.
1044+
1045+
.. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob
1046+
1047+
.. versionchanged:: 3.12
1048+
The *case_sensitive* parameter was added.
1049+
1050+
.. versionchanged:: 3.13
1051+
The *follow_symlinks* parameter was added.
10431052

10441053
.. versionchanged:: 3.13
10451054
The *pattern* parameter accepts a :term:`path-like object`.
10461055

1056+
10471057
.. method:: Path.group(*, follow_symlinks=True)
10481058

10491059
Return the name of the group owning the file. :exc:`KeyError` is raised
@@ -1471,44 +1481,6 @@ call fails (for example because the path doesn't exist).
14711481
strict mode, and no exception is raised in non-strict mode. In previous
14721482
versions, :exc:`RuntimeError` is raised no matter the value of *strict*.
14731483

1474-
.. method:: Path.rglob(pattern, *, case_sensitive=None, follow_symlinks=None)
1475-
1476-
Glob the given relative *pattern* recursively. This is like calling
1477-
:func:`Path.glob` with "``**/``" added in front of the *pattern*, where
1478-
*patterns* are the same as for :mod:`fnmatch`::
1479-
1480-
>>> sorted(Path().rglob("*.py"))
1481-
[PosixPath('build/lib/pathlib.py'),
1482-
PosixPath('docs/conf.py'),
1483-
PosixPath('pathlib.py'),
1484-
PosixPath('setup.py'),
1485-
PosixPath('test_pathlib.py')]
1486-
1487-
By default, or when the *case_sensitive* keyword-only argument is set to
1488-
``None``, this method matches paths using platform-specific casing rules:
1489-
typically, case-sensitive on POSIX, and case-insensitive on Windows.
1490-
Set *case_sensitive* to ``True`` or ``False`` to override this behaviour.
1491-
1492-
By default, or when the *follow_symlinks* keyword-only argument is set to
1493-
``None``, this method follows symlinks except when expanding "``**``"
1494-
wildcards. Set *follow_symlinks* to ``True`` to always follow symlinks, or
1495-
``False`` to treat all symlinks as files.
1496-
1497-
.. audit-event:: pathlib.Path.rglob self,pattern pathlib.Path.rglob
1498-
1499-
.. versionchanged:: 3.11
1500-
Return only directories if *pattern* ends with a pathname components
1501-
separator (:data:`~os.sep` or :data:`~os.altsep`).
1502-
1503-
.. versionchanged:: 3.12
1504-
The *case_sensitive* parameter was added.
1505-
1506-
.. versionchanged:: 3.13
1507-
The *follow_symlinks* parameter was added.
1508-
1509-
.. versionchanged:: 3.13
1510-
The *pattern* parameter accepts a :term:`path-like object`.
1511-
15121484
.. method:: Path.rmdir()
15131485

15141486
Remove this directory. The directory must be empty.
@@ -1639,6 +1611,81 @@ call fails (for example because the path doesn't exist).
16391611
.. versionchanged:: 3.10
16401612
The *newline* parameter was added.
16411613

1614+
1615+
.. _pathlib-pattern-language:
1616+
1617+
Pattern language
1618+
----------------
1619+
1620+
The following wildcards are supported in patterns for
1621+
:meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`:
1622+
1623+
``**`` (entire segment)
1624+
Matches any number of file or directory segments, including zero.
1625+
``*`` (entire segment)
1626+
Matches one file or directory segment.
1627+
``*`` (part of a segment)
1628+
Matches any number of non-separator characters, including zero.
1629+
``?``
1630+
Matches one non-separator character.
1631+
``[seq]``
1632+
Matches one character in *seq*.
1633+
``[!seq]``
1634+
Matches one character not in *seq*.
1635+
1636+
For a literal match, wrap the meta-characters in brackets.
1637+
For example, ``"[?]"`` matches the character ``"?"``.
1638+
1639+
The "``**``" wildcard enables recursive globbing. A few examples:
1640+
1641+
========================= ===========================================
1642+
Pattern Meaning
1643+
========================= ===========================================
1644+
"``**/*``" Any path with at least one segment.
1645+
"``**/*.py``" Any path with a final segment ending "``.py``".
1646+
"``assets/**``" Any path starting with "``assets/``".
1647+
"``assets/**/*``" Any path starting with "``assets/``", excluding "``assets/``" itself.
1648+
========================= ===========================================
1649+
1650+
.. note::
1651+
Globbing with the "``**``" wildcard visits every directory in the tree.
1652+
Large directory trees may take a long time to search.
1653+
1654+
.. versionchanged:: 3.13
1655+
Globbing with a pattern that ends with "``**``" returns both files and
1656+
directories. In previous versions, only directories were returned.
1657+
1658+
In :meth:`Path.glob` and :meth:`~Path.rglob`, a trailing slash may be added to
1659+
the pattern to match only directories.
1660+
1661+
.. versionchanged:: 3.11
1662+
Globbing with a pattern that ends with a pathname components separator
1663+
(:data:`~os.sep` or :data:`~os.altsep`) returns only directories.
1664+
1665+
1666+
Comparison to the :mod:`glob` module
1667+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1668+
1669+
The patterns accepted and results generated by :meth:`Path.glob` and
1670+
:meth:`Path.rglob` differ slightly from those by the :mod:`glob` module:
1671+
1672+
1. Files beginning with a dot are not special in pathlib. This is
1673+
like passing ``include_hidden=True`` to :func:`glob.glob`.
1674+
2. "``**``" pattern components are always recursive in pathlib. This is like
1675+
passing ``recursive=True`` to :func:`glob.glob`.
1676+
3. "``**``" pattern components do not follow symlinks by default in pathlib.
1677+
This behaviour has no equivalent in :func:`glob.glob`, but you can pass
1678+
``follow_symlinks=True`` to :meth:`Path.glob` for compatible behaviour.
1679+
4. Like all :class:`PurePath` and :class:`Path` objects, the values returned
1680+
from :meth:`Path.glob` and :meth:`Path.rglob` don't include trailing
1681+
slashes.
1682+
5. The values returned from pathlib's ``path.glob()`` and ``path.rglob()``
1683+
include the *path* as a prefix, unlike the results of
1684+
``glob.glob(root_dir=path)``.
1685+
6. ``bytes``-based paths and :ref:`paths relative to directory descriptors
1686+
<dir_fd>` are not supported by pathlib.
1687+
1688+
16421689
Correspondence to tools in the :mod:`os` module
16431690
-----------------------------------------------
16441691

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad © 2024 Your Company Name. All rights reserved.




Check this box to remove all script contents from the fetched content.



Check this box to remove all images from the fetched content.


Check this box to remove all CSS styles from the fetched content.


Check this box to keep images inefficiently compressed and original size.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy