Add docstrings to the compatibility shim. Give primacy to group looku…

…p in compatibility shim.

importlib_metadata/__init__.py

@@ -188,27 +188,38 @@ def _from_text_for(cls, text, dist):
 
 
 class LegacyGroupedEntryPoints(EntryPoints):
+    """
+    Compatibility wrapper around EntryPoints to provide
+    much of the 'dict' interface previously returned by
+    entry_points.
+    """
+
     def __getitem__(self, name) -> Union[EntryPoint, 'EntryPoints']:
-        try:
-            return super().__getitem__(name)
-        except KeyError:
-            if name not in self.groups:
-                raise
+        """
+        When accessed by name that matches a group, return the group.
+        """
+        group = self.select(group=name)
+        if group:
+            msg = "GroupedEntryPoints.__getitem__ is deprecated for groups. Use select."
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
+            return group
 
-        msg = "GroupedEntryPoints.__getitem__ is deprecated for groups. Use select."
-        warnings.warn(msg, DeprecationWarning)
-        return self.select(group=name)
+        return super().__getitem__(name)
 
     def get(self, group, default=None):
         """
-        For backward compatibility, supply .get
+        For backward compatibility, supply .get.
         """
         is_flake8 = any('flake8' in str(frame) for frame in inspect.stack())
         msg = "GroupedEntryPoints.get is deprecated. Use select."
-        is_flake8 or warnings.warn(msg, DeprecationWarning)
+        is_flake8 or warnings.warn(msg, DeprecationWarning, stacklevel=2)
         return self.select(group=group) or default
 
     def select(self, **params):
+        """
+        Prevent transform to EntryPoints during call to entry_points if
+        no selection parameters were passed.
+        """
         if not params:
             return self
         return super().select(**params)