From 303854b8270acbb8062adc809d38e64cc05cced4 Mon Sep 17 00:00:00 2001 From: harjoth Date: Sun, 14 Jun 2026 11:56:31 -0700 Subject: [PATCH 1/3] gh-139580: Clarify pathlib full_match recursive pattern docs Co-Authored-By: Claude Opus 4.8 --- Doc/library/pathlib.rst | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index ab92c142c37a4f6..7a2252fca1bf0c2 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -575,6 +575,21 @@ Pure paths provide the following methods and properties: >>> PurePath('/a/b/c.py').full_match('**/*.py') True + A pattern ending with "``/**``" matches any path that begins with the + pattern's prefix followed by a separator. For example "``/a/**``" matches + "``/a/b``" and "``/a/b/c``", but not "``/a``", because "``/a``" does not + begin with "``/a/``". The recursive wildcard "``**``" can match zero + segments, but the separator before it must still be present in the path, + and :class:`PurePath` objects do not preserve trailing slashes (so + "``/a/``" is normalized to "``/a``"):: + + >>> PurePath('/a/b').full_match('/a/**') + True + >>> PurePath('/a').full_match('/a/**') + False + >>> PurePath('/a/').full_match('/a/**') + False + .. seealso:: :ref:`pathlib-pattern-language` documentation. @@ -1795,7 +1810,10 @@ The following wildcards are supported in patterns for :meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: ``**`` (entire segment) - Matches any number of file or directory segments, including zero. + Matches any number of file or directory segments, including zero. Note that + in :meth:`~PurePath.full_match`, a pattern ending with "``/**``" requires the + separator before "``**``" to be present in the path; see that method for an + example. ``*`` (entire segment) Matches one file or directory segment. ``*`` (part of a segment) From bb17b3d53025f3650c00609c07fa15240bb4ac15 Mon Sep 17 00:00:00 2001 From: harjoth Date: Wed, 14 Oct 2026 21:07:44 -0700 Subject: [PATCH 2/3] gh-139580: Condense pathlib full_match recursive pattern docs Co-Authored-By: Claude Sonnet 5.5 --- Doc/library/pathlib.rst | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 7a2252fca1bf0c2..0f4601477dcaf56 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -575,20 +575,15 @@ Pure paths provide the following methods and properties: >>> PurePath('/a/b/c.py').full_match('**/*.py') True - A pattern ending with "``/**``" matches any path that begins with the - pattern's prefix followed by a separator. For example "``/a/**``" matches - "``/a/b``" and "``/a/b/c``", but not "``/a``", because "``/a``" does not - begin with "``/a/``". The recursive wildcard "``**``" can match zero - segments, but the separator before it must still be present in the path, - and :class:`PurePath` objects do not preserve trailing slashes (so - "``/a/``" is normalized to "``/a``"):: + A pattern ending in "``/**``" needs the separator before it to be present + in the path, even though "``**``" can match zero segments. So "``/a/**``" + matches "``/a/b``" but not "``/a``", and :class:`PurePath` drops trailing + slashes, so it does not match "``/a/``" either:: >>> PurePath('/a/b').full_match('/a/**') True >>> PurePath('/a').full_match('/a/**') False - >>> PurePath('/a/').full_match('/a/**') - False .. seealso:: :ref:`pathlib-pattern-language` documentation. @@ -1810,10 +1805,9 @@ The following wildcards are supported in patterns for :meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: ``**`` (entire segment) - Matches any number of file or directory segments, including zero. Note that - in :meth:`~PurePath.full_match`, a pattern ending with "``/**``" requires the - separator before "``**``" to be present in the path; see that method for an - example. + Matches any number of file or directory segments, including zero. But in + :meth:`~PurePath.full_match`, "``a/**``" does not match "``a``", although + :meth:`~Path.glob` yields "``a``" for that pattern. ``*`` (entire segment) Matches one file or directory segment. ``*`` (part of a segment) From 6e95befb111025eb0e05b56ba62958521c62d66e Mon Sep 17 00:00:00 2001 From: harjoth Date: Thu, 15 Oct 2026 14:28:55 -0700 Subject: [PATCH 3/3] gh-139580: Apply review wording suggestions Co-Authored-By: Claude Sonnet 5.5 --- Doc/library/pathlib.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index 0f4601477dcaf56..e265f633c4f38a2 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -576,9 +576,9 @@ Pure paths provide the following methods and properties: True A pattern ending in "``/**``" needs the separator before it to be present - in the path, even though "``**``" can match zero segments. So "``/a/**``" - matches "``/a/b``" but not "``/a``", and :class:`PurePath` drops trailing - slashes, so it does not match "``/a/``" either:: + in the path, even though "``**``" can match zero segments. For instance, + "``/a/**``" matches "``/a/b``" but not "``/a``", and since :class:`PurePath` + drops trailing slashes, it does not match "``/a/``" either:: >>> PurePath('/a/b').full_match('/a/**') True @@ -1805,9 +1805,9 @@ The following wildcards are supported in patterns for :meth:`~PurePath.full_match`, :meth:`~Path.glob` and :meth:`~Path.rglob`: ``**`` (entire segment) - Matches any number of file or directory segments, including zero. But in - :meth:`~PurePath.full_match`, "``a/**``" does not match "``a``", although - :meth:`~Path.glob` yields "``a``" for that pattern. + Matches any number of file or directory segments, including zero. + Note that in :meth:`~PurePath.full_match`, "``a/**``" does not match + "``a``", whereas :meth:`~Path.glob` yields "``a``" for that pattern. ``*`` (entire segment) Matches one file or directory segment. ``*`` (part of a segment)