[issue38594] importlib.metadata documentation deficiencies

[Jason R. Coombs]

Jason R. Coombs <jaraco at jaraco.com> added the comment:

Good suggestions. Thanks for taking the time to articulate in such a friendly way the shortcomings you encountered. I'm happy to help.

In [this ticket](https://gitlab.com/python-devs/importlib_metadata/issues/105), I've mirrored this ticket in the backport project, where I can iterate much faster.

I'll provide brief answers to some of your questions/concerns here and then work out the wording for the documentation (and code changes) necessary to communicate that effectively.

> The reference to `load_metadata()` is the only occurrence of the string `load_metadata` in the CPython and importlib_metadata code bases. I therefore believe the documentation in both CPython and the importlib_metadata standalone package are wrong because they are referring to a method that is never implemented nor called.

That's right. The documentation is wrong. It should say to implement a `Distribution` subclass (especially its abstract methods). Nothing more should be necessary.

> I see that certain APIs return Path-like objects (which I will need to implement)

Are you sure about that? The only code I see in the `Distribution` class that references a `Path` object is `.at()`, a static method that we decided to add to the `Distribution` class even though it would be more appropriate in the `PathDistribution` class in order to make that method readily available to projects that wished to construct the Path-based distribution objects from a file system (or zipfile) path. I'm pretty sure everything else in the Distribution class relies on the two abstract methods. If you disregard `at` (and I recommend you do) and focus on implementing the abstract methods, I think things will work. Let me know if you find otherwise.

> why the Context is optional and how Context could be used?

The interface is intentionally vague in order not to be too prescriptive, because as you point out, name or path may not be relevant in some contexts. It's meant to narrow the scope of any search.

So if a path is present, that means the query is looking in a specific 'sys.path' entry. And if the name is present, that means it's looking for a distribution having a specific name. But basically, you can solicit any properties you like. You could expect a `size='max(100)'` parameter and only return distributions smaller than 100 (for whatever interpretation of `size` you wish to implement. Your DistributionFinder should do its best to honor whatever context might be relevant to the Distributions you provide.

Does PyOxidizer interact with `sys.path` at all? If not, it can disregard `Context.path`.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38594>
_______________________________________