Instead of presenting separate contexts for EntryPoints, unify into a single collection that can select on 'name' or 'group' or possibly other attributes. Expose that selection in the 'entry_points' function.

Author: jaraco

docs/using.rst

@@ -77,7 +77,7 @@ a ``.load()`` method to resolve the value.  There are also ``.module``,
     >>> eps = entry_points()
     >>> sorted(eps.groups)
     ['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
-    >>> scripts = eps['console_scripts']
+    >>> scripts = eps.select(group='console_scripts')
     >>> 'wheel' in scripts.names
     True
     >>> wheel = scripts['wheel']

importlib_metadata/__init__.py

@@ -130,10 +130,6 @@ def _from_text(cls, text):
         config.read_string(text)
         return cls._from_config(config)
 
-    @classmethod
-    def _from_text_for(cls, text, dist):
-        return (ep._for(dist) for ep in cls._from_text(text))
-
     def _for(self, dist):
         self.dist = dist
         return self
@@ -155,35 +151,42 @@ def __reduce__(self):
             (self.name, self.value, self.group),
         )
 
+    def matches(self, **params):
+        attrs = (getattr(self, param) for param in params)
+        return all(map(operator.eq, params.values(), attrs))
+
 
 class EntryPoints(tuple):
     """
-    An immutable collection of EntryPoint objects, retrievable by name.
+    An immutable collection of selectable EntryPoint objects.
     """
 
     __slots__ = ()
 
-    def __getitem__(self, name) -> EntryPoint:
+    def __getitem__(self, name) -> Union[EntryPoint, 'EntryPoints']:
         try:
-            return next(ep for ep in self if ep.name == name)
-        except Exception:
+            match = next(iter(self.select(name=name)))
+            return match
+        except StopIteration:
+            if name in self.groups:
+                return self._group_getitem(name)
             raise KeyError(name)
 
+    def _group_getitem(self, name):
+        """
+        For backward compatability, supply .__getitem__ for groups.
+        """
+        msg = "GroupedEntryPoints.__getitem__ is deprecated for groups. Use select."
+        warnings.warn(msg, DeprecationWarning)
+        return self.select(group=name)
+
+    def select(self, **params):
+        return EntryPoints(ep for ep in self if ep.matches(**params))
+
     @property
     def names(self):
         return set(ep.name for ep in self)
 
-
-class GroupedEntryPoints(tuple):
-    """
-    An immutable collection of EntryPoint objects, retrievable by group.
-    """
-
-    __slots__ = ()
-
-    def __getitem__(self, group) -> EntryPoints:
-        return EntryPoints(ep for ep in self if ep.group == group)
-
     @property
     def groups(self):
         return set(ep.group for ep in self)
@@ -193,9 +196,13 @@ def get(self, group, default=None):
         For backward compatibility, supply .get
         """
         is_flake8 = any('flake8' in str(frame) for frame in inspect.stack())
-        msg = "GroupedEntryPoints.get is deprecated. Just use __getitem__."
+        msg = "GroupedEntryPoints.get is deprecated. Use select."
         is_flake8 or warnings.warn(msg, DeprecationWarning)
-        return self[group] or default
+        return self.select(group=group) or default
+
+    @classmethod
+    def _from_text_for(cls, text, dist):
+        return cls(ep._for(dist) for ep in EntryPoint._from_text(text))
 
 
 class PackagePath(pathlib.PurePosixPath):
@@ -353,8 +360,7 @@ def version(self):
 
     @property
     def entry_points(self):
-        eps = EntryPoint._from_text_for(self.read_text('entry_points.txt'), self)
-        return GroupedEntryPoints(eps)
+        return EntryPoints._from_text_for(self.read_text('entry_points.txt'), self)
 
     @property
     def files(self):
@@ -687,13 +693,13 @@ def version(distribution_name):
     return distribution(distribution_name).version
 
 
-def entry_points():
+def entry_points(**params):
     """Return EntryPoint objects for all installed packages.
 
     :return: EntryPoint objects for all installed packages.
     """
     eps = itertools.chain.from_iterable(dist.entry_points for dist in distributions())
-    return GroupedEntryPoints(eps)
+    return EntryPoints(eps).select(**params)
 
 
 def files(distribution_name):

tests/test_api.py

@@ -67,25 +67,25 @@ def test_read_text(self):
     def test_entry_points(self):
         eps = entry_points()
         assert 'entries' in eps.groups
-        entries = eps['entries']
+        entries = eps.select(group='entries')
         assert 'main' in entries.names
         ep = entries['main']
         self.assertEqual(ep.value, 'mod:main')
         self.assertEqual(ep.extras, [])
 
     def test_entry_points_distribution(self):
-        entries = entry_points()['entries']
+        entries = entry_points(group='entries')
         for entry in ("main", "ns:sub"):
             ep = entries[entry]
             self.assertIn(ep.dist.name, ('distinfo-pkg', 'egginfo-pkg'))
             self.assertEqual(ep.dist.version, "1.0.0")
 
     def test_entry_points_missing_name(self):
         with self.assertRaises(KeyError):
-            entry_points()['entries']['missing']
+            entry_points(group='entries')['missing']
 
     def test_entry_points_missing_group(self):
-        assert entry_points()['missing'] == ()
+        assert entry_points(group='missing') == ()
 
     def test_entry_points_dict_construction(self):
         """
@@ -94,16 +94,28 @@ def test_entry_points_dict_construction(self):
         Capture this now deprecated use-case.
         """
         with warnings.catch_warnings(record=True) as caught:
-            eps = dict(entry_points()['entries'])
+            eps = dict(entry_points(group='entries'))
 
         assert 'main' in eps
-        assert eps['main'] == entry_points()['entries']['main']
+        assert eps['main'] == entry_points(group='entries')['main']
 
         # check warning
         expected = next(iter(caught))
         assert expected.category is DeprecationWarning
         assert "Construction of dict of EntryPoints is deprecated" in str(expected)
 
+    def test_entry_points_groups_getitem(self):
+        """
+        Prior versions of entry_points() returned a dict. Ensure
+        that callers using '.__getitem__()' are supported but warned to
+        migrate.
+        """
+        with warnings.catch_warnings(record=True):
+            entry_points()['entries'] == entry_points(group='entries')
+
+        with self.assertRaises(KeyError):
+            entry_points()['missing']
+
     def test_entry_points_groups_get(self):
         """
         Prior versions of entry_points() returned a dict. Ensure
@@ -113,7 +125,7 @@ def test_entry_points_groups_get(self):
         with warnings.catch_warnings(record=True):
             entry_points().get('missing', 'default') == 'default'
             entry_points().get('entries', 'default') == entry_points()['entries']
-            entry_points().get('missing', ()) == entry_points()['missing']
+            entry_points().get('missing', ()) == ()
 
     def test_metadata_for_this_package(self):
         md = metadata('egginfo-pkg')

tests/test_main.py

@@ -58,11 +58,11 @@ def test_import_nonexistent_module(self):
             importlib.import_module('does_not_exist')
 
     def test_resolve(self):
-        ep = entry_points()['entries']['main']
+        ep = entry_points(group='entries')['main']
         self.assertEqual(ep.load().__name__, "main")
 
     def test_entrypoint_with_colon_in_name(self):
-        ep = entry_points()['entries']['ns:sub']
+        ep = entry_points(group='entries')['ns:sub']
         self.assertEqual(ep.value, 'mod:main')
 
     def test_resolve_without_attr(self):

tests/test_zip.py

@@ -45,7 +45,7 @@ def test_zip_version_does_not_match(self):
             version('definitely-not-installed')
 
     def test_zip_entry_points(self):
-        scripts = entry_points()['console_scripts']
+        scripts = entry_points(group='console_scripts')
         entry_point = scripts['example']
         self.assertEqual(entry_point.value, 'example:main')
         entry_point = scripts['Example']