gh-139580: Clarify pathlib full_match recursive pattern docs

[harjothkhara]

Documents how PurePath.full_match() handles a pattern ending in /**: /a/** matches /a/b but not /a, because the separator before ** must be present in the path and PurePath drops trailing slashes. Adds two doctest examples under full_match() and a note at the ** entry of the pattern language list contrasting it with Path.glob().

Docs-only; matches existing behavior.

Disclosure: AI-assisted wording; reviewed by me.

• Issue: /a/** is understood by Path.full_match as /a followed by multiple segments, at least one #139580

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33135752 | 📁 Comparing 303854b against main (a700732)

  🔍 Preview build  

1 file changed

± library/pathlib.html

[harjothkhara]

@barneygale this is the docs clarification you suggested on gh-139580 — it adds a worked full_match('/a/**') example and a note on trailing-slash normalization, following your explanation on the issue. Would you mind reviewing?

[github-actions]

This PR is stale because it has been open for 90 days with no activity.

[terryjreedy]

@picnixz On a previous issue, you said "I don't know how the docs could be improved though." This PR attempts an improvement. Merge? Modify (condense) and merge? I verified the new examples. The prose looks fine; maybe longer than needed, but I don't know what to cut. I do understand the 0-1 segment confusion and agree that it should be explained.

@macmarrum You posted the confusion this PR tries to solve. What do you think?

PS 'macmar', if you get a ping, my mistake for clicking too soon.

[macmarrum]

When I imagine I don't know anything about the issue, reading the docs I'd first want to know what ** means when I use it, and only later the reason for the different interpretations.

Suggested change

	Matches any number of file or directory segments, including zero. Note that
	In :meth:`~Path.glob` and :meth:`~Path.rglob`, matches any number of file or
	directory segments, including zero.
	In :meth:`~PurePath.full_match`, matches one or more such segments. See that
	method's documentation for examples and the reasoning behind its different
	interpretation.

[macmarrum]

Here's my take on it. I'm not sure about the formatting, though.

Suggested change

	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``")::
	Note that in :meth:`~Path.glob` and :meth:`~Path.rglob`, "``**``" matches zero
	or more segments, whereas in :meth:`~PurePath.full_match` it matches one or
	more. Although "``**``" can match zero segments, the internal logic, to
	recognize a segment, requires a trailing separator, but :class:`PurePath`
	objects do not preserve them (so "``/a/``" is normalized to "``/a``")::

[harjothkhara]

Thanks for the review. I have reworded the note at the ** entry so the difference is visible there: PurePath('a').full_match('a/**') is False, while Path.glob('a/**') yields a. I did not use "one or more", because ** still matches zero segments elsewhere in full_match(): PurePath('a/b').full_match('a/**/b') and PurePath('a.py').full_match('**/*.py') are both True. Only a trailing /** differs. I have also shortened the paragraph under full_match(), as Terry suggested.

[macmarrum]

Looks good 👍

[picnixz]

Suggested change

	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::
	A pattern ending in "``/**``" needs the separator before it to be present
	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::

[picnixz]

Suggested change

	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.

[harjothkhara]

Applied both suggestions in 6e95bef. Thanks picnixz and macmarrum.

[picnixz]

It's unfortunate that this behavior is like that but we can't change the implementation so I think this is the best we can do.

@terryjreedy Do you think it's good enough for nonfamiliar people?