gh-116608: Apply style and compatibility changes from importlib_metadata.

[jaraco]

• Issue: Un-deprecate functional API for importlib resources & add subdirectory support #116608

[jaraco]

I applied some changes against importlib_resources 6.4 and then merged those with the cpython branch of importlib_resources, then copied the remaining diff over to CPython. These changes represent the re-synchronization of the two codebases, mainly getting the style to align with the linter/formatter's opinion, but also one change to the context managers to be compatible with Python 3.8 syntax.

[jaraco]

Since I believe these changes are largely uncontroversial and I was primarily looking to inform Petr of the changes, and because this PR is blocking another, I'm going to merge it, but happy to continue a review or even back out if needed.

[miss-islington-app]

Thanks @jaraco for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-123051 is a backport of this pull request to the 3.13 branch.

[jaraco]

I just noticed that "metadata" appears in the commit message. These changes pertain to "resources".

[bedevere-app]

GH-123051 is a backport of this pull request to the 3.13 branch.

[encukou]

Well, to me this looks like style fixes that are traditionally avoided in CPython, but it does look harmless.

[bedevere-app]

GH-123074 is a backport of this pull request to the 3.13 branch.

[jaraco]

Well, to me this looks like style fixes that are traditionally avoided in CPython, but it does look harmless.

The problem is that it's untenable given the constraints on the CPython repo to have divergent styles between the CPython implementation and the third-party package. Due to its shared maintenance with other skeleton projects, importlib_resources has a stricter standard for format, types, and lint. There's no VCS metadata to track the differences, so the process of contributing changes from importlib_resources (upstream) to importlib.resources will overwrite any changes that weren't applied upstream. This change does that overwriting so that it's not folded into a subsequent contribution.

[encukou]

Yeah, and from the other side, the custom tooling in importlib_resources makes it harder than it could be to properly contribute to importlib.resources.
I wonder if we should we add importlib.resources to PEP-360, or otherwise make importlib_resources's style requirements, or contribution instructions in general, more discoverable?

[jaraco]

I wonder if we should we add importlib.resources to PEP-360, or otherwise make importlib_resources's style requirements, or contribution instructions in general, more discoverable?

I don't think adding it to PEP 360 would help much, given that the external project already provides most of that context (who maintains it, which versions are compatible), and the two codebases are maintained jointly. I note also that importlib_metadata and zipp follow the same regime, and at least for those, the CPython docs to provide a link to the external mirror / backport. I note also that I run into similar issues with configparser, even though it follows a more conventional backport role, backports.tarfile, singledispatch, and probably others.

On several occasions, I've wanted to have a good place to document this regime, to include contribution instructions and maintenance instructions, but the main thing that's held me back is lack of an appropriate shared space (it felt awkward to put the docs in one project that apply equally to three). I seem to recall at one point I did document the process, but I'm unable to find it. Correction, I found it here. That guidance is still somewhat relevant, but also out of date and incomplete. I should probably just revive that doc in a maintained repo/wiki (probably importlib_metadata), and just link to it from the relevant projects. We should also update the importlib.resources docs to provide a reference to importlib_resources.

My preference is to accept changes in the external project first for several reasons, that I'll document in the contributing guide, but I'm happy to accept contributions in CPython as long as the contribution is amenable to a backport.