Feature/entry points by group and name

CHANGES.rst

@@ -1,3 +1,16 @@
+v3.5.0
+======
+
+* ``entry_points()`` now returns an ``GroupedEntryPoints``
+  object, a tuple of all entry points but with a convenience
+  property ``groups`` and ``__getitem__`` accessor. Further,
+  accessing a group returns an ``EntryPoints`` object,
+  another tuple of entry points in the group, accessible by
+  name. Construction of entry points using
+  ``dict([EntryPoint, ...])`` is now deprecated and raises
+  an appropriate DeprecationWarning and will be removed in
+  a future version.
+
 v3.4.0
 ======
 

docs/using.rst

@@ -67,18 +67,20 @@ This package provides the following functionality via its public API.
 Entry points
 ------------
 
-The ``entry_points()`` function returns a dictionary of all entry points,
+The ``entry_points()`` function returns a sequence of all entry points,
 keyed by group.  Entry points are represented by ``EntryPoint`` instances;
 each ``EntryPoint`` has a ``.name``, ``.group``, and ``.value`` attributes and
 a ``.load()`` method to resolve the value.  There are also ``.module``,
 ``.attr``, and ``.extras`` attributes for getting the components of the
 ``.value`` attribute::
 
     >>> eps = entry_points()
-    >>> list(eps)
+    >>> sorted(eps.groups)
     ['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
     >>> scripts = eps['console_scripts']
-    >>> wheel = [ep for ep in scripts if ep.name == 'wheel'][0]
+    >>> 'wheel' in scripts.names
+    True
+    >>> wheel = scripts['wheel']
     >>> wheel
     EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')
     >>> wheel.module

importlib_metadata/__init__.py

@@ -7,6 +7,7 @@
 import email
 import pathlib
 import operator
+import warnings
 import functools
 import itertools
 import posixpath
@@ -139,11 +140,12 @@ def _for(self, dist):
     def __iter__(self):
         """
         Supply iter so one may construct dicts of EntryPoints by name.
-
-        >>> eps = [EntryPoint('a', 'b', 'c'), EntryPoint('d', 'e', 'f')]
-        >>> dict(eps)['a']
-        EntryPoint(name='a', value='b', group='c')
         """
+        msg = (
+            "Construction of dict of EntryPoints is deprecated in "
+            "favor of EntryPoints."
+        )
+        warnings.warn(msg, DeprecationWarning)
         return iter((self.name, self))
 
     def __reduce__(self):
@@ -153,6 +155,43 @@ def __reduce__(self):
         )
 
 
+class EntryPoints(tuple):
+    """
+    A collection of EntryPoint objects, retrievable by name.
+    """
+
+    def __getitem__(self, name) -> EntryPoint:
+        try:
+            return next(ep for ep in self if ep.name == name)
+        except Exception:
+            raise KeyError(name)
+
+    @property
+    def names(self):
+        return set(ep.name for ep in self)
+
+
+class GroupedEntryPoints(tuple):
+    """
+    A collection of EntryPoint objects, retrievable by group.
+    """
+
+    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)
+
+    def get(self, group, default=None):
+        """
+        For backward compatibility, supply .get
+        """
+        msg = "GroupedEntryPoints.get is deprecated. Just use __getitem__."
+        warnings.warn(msg, DeprecationWarning)
+        return self[group] or default
+
+
 class PackagePath(pathlib.PurePosixPath):
     """A reference to a path in a package"""
 
@@ -308,7 +347,8 @@ def version(self):
 
     @property
     def entry_points(self):
-        return list(EntryPoint._from_text_for(self.read_text('entry_points.txt'), self))
+        eps = EntryPoint._from_text_for(self.read_text('entry_points.txt'), self)
+        return GroupedEntryPoints(eps)
 
     @property
     def files(self):
@@ -647,10 +687,7 @@ def entry_points():
     :return: EntryPoint objects for all installed packages.
     """
     eps = itertools.chain.from_iterable(dist.entry_points for dist in distributions())
-    by_group = operator.attrgetter('group')
-    ordered = sorted(eps, key=by_group)
-    grouped = itertools.groupby(ordered, by_group)
-    return {group: tuple(eps) for group, eps in grouped}
+    return GroupedEntryPoints(eps)
 
 
 def files(distribution_name):

tests/test_api.py

@@ -1,6 +1,7 @@
 import re
 import textwrap
 import unittest
+import warnings
 
 from . import fixtures
 from importlib_metadata import (
@@ -64,18 +65,56 @@ def test_read_text(self):
         self.assertEqual(top_level.read_text(), 'mod\n')
 
     def test_entry_points(self):
-        entries = dict(entry_points()['entries'])
+        eps = entry_points()
+        assert 'entries' in eps.groups
+        entries = eps['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 = dict(entry_points()['entries'])
+        entries = entry_points()['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']
+
+    def test_entry_points_missing_group(self):
+        assert entry_points()['missing'] == ()
+
+    def test_entry_points_dict_construction(self):
+        """
+        Prior versions of entry_points() returned simple lists and
+        allowed casting those lists into maps by name using ``dict()``.
+        Capture this now deprecated use-case.
+        """
+        with warnings.catch_warnings(record=True) as caught:
+            eps = dict(entry_points()['entries'])
+
+        assert 'main' in eps
+        assert eps['main'] == entry_points()['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_get(self):
+        """
+        Prior versions of entry_points() returned a dict. Ensure
+        that callers using '.get()' are supported but warned to
+        migrate.
+        """
+        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']
+
     def test_metadata_for_this_package(self):
         md = metadata('egginfo-pkg')
         assert md['author'] == 'Steven Ma'

tests/test_main.py

@@ -3,6 +3,7 @@
 import pickle
 import textwrap
 import unittest
+import warnings
 import importlib
 import importlib_metadata
 import pyfakefs.fake_filesystem_unittest as ffs
@@ -57,13 +58,11 @@ def test_import_nonexistent_module(self):
             importlib.import_module('does_not_exist')
 
     def test_resolve(self):
-        entries = dict(entry_points()['entries'])
-        ep = entries['main']
+        ep = entry_points()['entries']['main']
         self.assertEqual(ep.load().__name__, "main")
 
     def test_entrypoint_with_colon_in_name(self):
-        entries = dict(entry_points()['entries'])
-        ep = entries['ns:sub']
+        ep = entry_points()['entries']['ns:sub']
         self.assertEqual(ep.value, 'mod:main')
 
     def test_resolve_without_attr(self):
@@ -249,7 +248,8 @@ def test_json_dump(self):
         json should not expect to be able to dump an EntryPoint
         """
         with self.assertRaises(Exception):
-            json.dumps(self.ep)
+            with warnings.catch_warnings(record=True):
+                json.dumps(self.ep)
 
     def test_module(self):
         assert self.ep.module == 'value'

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 = dict(entry_points()['console_scripts'])
+        scripts = entry_points()['console_scripts']
         entry_point = scripts['example']
         self.assertEqual(entry_point.value, 'example:main')
         entry_point = scripts['Example']