From bb2437066473ed10dff16564d731917345251e88 Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Sun, 14 Mar 2021 09:57:53 -0400
Subject: [PATCH] Expand docs to explain more about the interfaces and to
 include a compatibility note.

---
 docs/using.rst | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/docs/using.rst b/docs/using.rst
index 18aa2fda..53d83959 100644
--- a/docs/using.rst
+++ b/docs/using.rst
@@ -72,15 +72,43 @@ 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::
+``.value`` attribute.
+
+Query all entry points::
 
     >>> eps = entry_points()
+
+The ``entry_points()`` function returns an ``EntryPoints`` object,
+a sequence of all ``EntryPoint`` objects with ``names`` and ``groups``
+attributes for convenience.
+
     >>> sorted(eps.groups)
     ['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
+
+``EntryPoints`` has a ``select`` method to select entry points
+matching specific properties. Select entry points in the
+``console_scripts`` group::
+
     >>> scripts = eps.select(group='console_scripts')
+
+Equivalently, since ``entry_points`` passes keyword arguments
+through to select::
+
+    >>> scripts = entry_points(group='console_scripts')
+
+Pick out a specific script named "wheel" (found in the wheel project)::
+
     >>> 'wheel' in scripts.names
     True
     >>> wheel = scripts['wheel']
+
+Equivalently, query for that entry point during selection::
+
+    >>> (wheel,) = entry_points(group='console_scripts', name='wheel')
+    >>> (wheel,) = entry_points().select(group='console_scripts', name='wheel')
+
+Inspect the resolved entry point::
+
     >>> wheel
     EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')
     >>> wheel.module
@@ -99,6 +127,17 @@ group.  Read `the setuptools docs
 <https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_
 for more information on entry points, their definition, and usage.
 
+*Compatibility Note*
+
+The "selectable" entry points were introduced in ``importlib_metadata``
+3.6 and Python 3.10. Prior to those changes, ``entry_points`` accepted
+no parameters and always returned a dictionary of entry points, keyed
+by group. For compatibility, if no parameters are passed to entry_points,
+a ``SelectableGroups`` object is returned, implementing that dict
+interface. In the future, calling ``entry_points`` with no parameters
+will return an ``EntryPoints`` object. Users should rely on the selection
+interface to retrieve entry points by group.
+
 
 .. _metadata: