Thanks for the report. Happy to explore the issue here.

I'm not at all confident that equality by name is correct, because it's possible for multiple distributions of the same name to exist in the environment. For example:

 ~ @ pip-run 'importlib_metadata<5' -- -m pip-run 'importlib_metadata>5' -- -q
>>> import importlib.metadata as md
>>> ds = [dist for dist in md.distributions() if dist.name == 'importlib-metadata']
>>> ds
[<importlib.metadata.PathDistribution object at 0x10305aed0>, <importlib.metadata.PathDistribution object at 0x10306f5d0>]
>>> ds[0].version
'6.8.0'
>>> ds[1].version
'4.13.0'

This example uses pip-run to install two different versions of importlib_metadata (I could have used any PyPI package) onto two different places in sys.path and then filters on those two distribution objects.

In this case, I wouldn't expect these two distributions to compare equal, even though they have the same name. Moreover, if two distributions had the same name and version but were located in different places on sys.path, those also should probably not necessarily compare equal.

Moreover, metadata providers are expected to implement their own Distribution subclasses, so it's conceivable that two Distribution might be distinguished by some factor not yet known.

Another thing to consider - should a distribution compare equal to a string of the name? In one example, you imply that's expected:

entry_points(group='console_scripts', dist='pip')  # empty EntryPoints list

That suggests that distribution('pip') == 'pip' should evaluate to True. That's possible, but I'm not sure it's desirable. What if someone wants instead to compare for a specific version (e.g. distribution('pip') == 'pip==23.1')? That gets messy and isn't even implementable without behavior only available outside the stdlib (packaging).

I agree that entry point selection is a compelling use case for such a comparison.

I wouldn't characterize the described behavior as a bug, but rather an unaddressed feature.

Thanks for looking at this @jaraco

because it's possible for multiple distributions of the same name to exist in the environment

Seems weird to me, at least I have never seen or heard of anything like that.
But then again, if the consensus is that filtering by distribution name is too ambiguous so that it might actually be harmful, I'd argue that still the current implementation should still change or at least this behavior for dist kwarg as a filter should be mentioned in docs, since currently filtering/matching by dist will always result in an empty result for reasons laid out above.
If there is too much concern for ambiguous behavior doing proper "equal" comparisons, then I would propose to either..

• raise an exception if user tries to use dist for filtering entry points or..
• at least show a warning that using dist in filtering will always result in empty results

Currently dist is accepted for filtering, which results in users assuming it can be used and leading to time spent trying to figure out why it isn't working.

To be constructive, I set up a quick PR with what I would've wished to see in the docs at the time when I was transitioning our package from pgk_resources to this new recommended stdlib API.

Sorry for the delay in reviewing this. Can you share more about how pkg_resources previously supported your use-case?

What we did (still do actually) with pkg_resources (using pip just as an example here):

from pkg_resources import load_entry_point
load_entry_point('pip', 'console_scripts', 'pip')

What I thought would do the trick with importlib.metadata, doesn't work though and took quite some time to figure out why:

import importlib.metadata
# doesn't work, returns an empty list
importlib.metadata.entry_points(dist='pip', group='console_scripts', name='pip')[0].load()

Only way I could get this replicated with importlib.metadata:

import importlib.metadata
list(ep for ep in importlib.metadata.entry_points(group='console_scripts', name='pip') if ep.dist.name == 'pip')[0].load()

Like mentioned above, my main issue with it is that dist is allowed as a kwarg to filter for (as opposed to using some arbitrary other kwarg which raises an exception), implying that it can be used to filter by distribution name or at least filter with a Distribution object. It is fairly easy to work around this once one has figured out whats going on, but it takes time debugging. I can just imagine that more people spend time trying to figure out what is happening and that dist kwarg right now is just unusable as a filter.

It's been quite a year, and I'm just now digging deep enough into my emails to follow up on this. Sorry for the delay.

I can't recall, but I may have failed to connect the dots on the PR until just now. Thanks for that proposal.

Thinking about the use-case, I believe the recommended approach for getting entry points for a specific distribution would be done like so:

importlib.metadata.distribution('pip').entry_points.select(name='pip', group='console_scripts')

e.g.:

 🐚 py -c "import importlib.metadata; ep, = importlib.metadata.distribution('pip').entry_points.select(name='pip', group='console_scripts'); print(ep)"
EntryPoint(name='pip', value='pip._internal.cli.main:main', group='console_scripts')

my main issue with it is that dist is allowed as a kwarg to filter

I think I agree we should update the guidance or maybe issue warnings to reduce the risk of this unintended use, though I'd also consider adding support for it if we can figure out how richly to do so.

Another option, now that I think about it, is to simply query for the "pip" "console_scripts":

importlib.metadata.entry_points().select(name='pip', group='console_scripts')

And not bother filtering by distribution at all, since it's unlikely another package would implement the pip console script (and if they did, you have bigger problems).