Introduce SelectableGroups, created for the 3.x line to provide forwa…

…rd compatibilty to the new interfaces without sacrificing backward compatibility.

CHANGES.rst

@@ -1,4 +1,4 @@
-v4.0.0
+v3.6.0
 ======
 
 * #284: Introduces new ``EntryPoints`` object, a tuple of
@@ -13,10 +13,18 @@ v4.0.0
   - Item access (e.g. ``eps[name]``) retrieves a single
     entry point by name.
 
-  ``entry_points()`` now returns an ``EntryPoints``
-  object, but provides for backward compatibility with
-  a ``__getitem__`` accessor by group and a ``get()``
-  method.
+  ``entry_points()`` now provides a future-compatible
+  ``SelectableGroups`` object that supplies the above interface
+  but remains a dict for compatibility.
+
+  In the future, ``entry_points()`` will return an
+  ``EntryPoints`` object, but provide for backward
+  compatibility with a deprecated  ``__getitem__``
+  accessor by group and a ``get()`` method.
+
+  If passing selection parameters to ``entry_points``, the
+  future behavior is invoked and an ``EntryPoints`` is the
+  result.
 
   Construction of entry points using
   ``dict([EntryPoint, ...])`` is now deprecated and raises

importlib_metadata/__init__.py

@@ -187,6 +187,37 @@ def _from_text_for(cls, text, dist):
         return cls(ep._for(dist) for ep in EntryPoint._from_text(text))
 
 
+class SelectableGroups(dict):
+    """
+    A backward- and forward-compatible result from
+    entry_points that fully implements the dict interface.
+    """
+
+    @classmethod
+    def load(cls, eps):
+        by_group = operator.attrgetter('group')
+        ordered = sorted(eps, key=by_group)
+        grouped = itertools.groupby(ordered, by_group)
+        return cls((group, EntryPoints(eps)) for group, eps in grouped)
+
+    @property
+    def groups(self):
+        return self.keys()
+
+    @property
+    def names(self):
+        return (ep.name for ep in self._all)
+
+    @property
+    def _all(self):
+        return itertools.chain.from_iterable(self.values())
+
+    def select(self, **params):
+        if not params:
+            return self
+        return EntryPoints(self._all).select(**params)
+
+
 class LegacyGroupedEntryPoints(EntryPoints):
     """
     Compatibility wrapper around EntryPoints to provide
@@ -722,7 +753,7 @@ def entry_points(**params):
     eps = itertools.chain.from_iterable(
         dist.entry_points for dist in unique(distributions())
     )
-    return LegacyGroupedEntryPoints(eps).select(**params)
+    return SelectableGroups.load(eps).select(**params)
 
 
 def files(distribution_name):