gh-127337: Fix importlib.resources for legacy ResourceReader loaders

[pikammmmm]

CompatibilityFiles.SpecPath, .ChildPath and .OrphanPath each defined joinpath() with a single required argument, but importlib.resources.abc.Traversable declares joinpath(*descendants) and documents that passing no descendants returns self.

Since 3.13 the functional API is implemented on top of files(anchor).joinpath(*path_names), so any call that passes no path names reaches joinpath() with no arguments and raises TypeError for a package whose loader provides only a legacy ResourceReader:

	3.12.13	3.13.13 / 3.14.4 / 3.15.0b1	this PR
contents(FakeModule)	['NAME']	TypeError	['NAME']
is_resource(FakeModule)	n/a — required a name	TypeError	False

(measured with the reproducer from the issue; 3.12 predates _functional.py, whose one-name-per-call predecessor never routed through joinpath())

This is the fix @jaraco sketched in the issue, extended to ChildPath and OrphanPath as he suggested it might need to be. It also fixes the latent multi-argument case, broken ever since the protocol gained *descendants in 3.11 without _adapters.py being updated — as @FFY00 diagnosed, "the CompatibilityFiles implementation is bad, it can only ever take one argument, and now it needs to be able to take any number of arguments."

One deviation from the sketch: it used '/'.join(descendants) for SpecPath, which would make files.joinpath('a', 'b') a single ChildPath named a/b, while files / 'a' / 'b' is an OrphanPath('a', 'b'). The Traversable.joinpath docs present the chained single-argument form as the compatibility equivalent of the multi-argument form for implementations that predate it, so this PR applies descendants one at a time and the two forms agree. That also avoids '/'.join raising TypeError on a PathLike segment which single-argument joinpath() accepts today.

CompatibilityFiles still does not meaningfully support os.PathLike segments; that is unchanged here and out of scope.

Tests

Seven new tests in test_compatibilty_files.py: zero-argument joinpath() on all three path classes (with and without a reader), the multi-argument/chained equivalence, and contents()/is_resource() through the functional API.

• Negative control: with _adapters.py reverted, all seven new tests fail and the 16 pre-existing tests in the file still pass.
• All 221 tests in test_importlib.resources pass (1 skipped).
• I test without a local C build — checkout Lib/ on a matching installed interpreter — which yields 88 unrelated pre-existing failures in test_importlib.metadata/frozen/extension. That set is identical with and without this patch, and none of them are in resources.

Sibling fix for the same protocol violation in simple.py: #145263.

@FFY00 — @jaraco assigned this to you in December 2024; happy to close this if you would rather take it yourself.

• Issue: importlib.resources regression for custom ResourceReader #127337

[pikammmmm]

@jaraco this is the diff from your comment on the issue, plus the ChildPath bit you flagged as a maybe. SpecPath, ChildPath and OrphanPath all take *descendants now and return self when given none, which is the case gh-127337 actually hits.

One place I went a different way. You had ChildPath(self._reader, '/'.join(descendants)); I recursed instead, so joinpath('a', 'b') and joinpath('a').joinpath('b') produce the same thing, which is what Traversable.joinpath documents. There's a test for it (test_joinpath_multiple_descendants). Easy to switch to the join if you'd rather have that.

importlib_resources still has the same one-argument joinpath, so it needs this too. #333 looks like it went CPython-first and got ported over after, so I assumed that's fine here, but I'm glad to open it upstream first instead if that's easier for you.

@zooba this is the "make the automatic adaptation get it right" path you argued for on the issue, in case you want to weigh in.