Document pathlib with_segments duck typing for path object arguments

[dimaqq]

Some pathlib methods use the presence of a with_segments attribute to decide whether an argument is already a path object.

This behavior was changed in gh-128520 / GH-130199 for Python 3.14. The main pathlib reference documents PurePath.with_segments(), but it does not currently mention that methods such as PurePath.match() and Path.rename() use with_segments as this duck-typed marker.

This can surprise authors of path-like or path-adjacent classes that define with_segments without implementing os.PathLike. The docs should describe the current behavior so subclass and third-party path authors have a clear contract to work from.

Linked PRs

• gh-153390: Document pathlib with_segments path duck typing #153394

[dimaqq]

I'm working on a PR: tiny doc update.