Merge branch 'main' into epp

Author: jaraco

.coveragerc

@@ -1,5 +1,6 @@
 [run]
 omit =
+	# leading `*/` for pytest-dev/pytest-cov#456
 	*/.tox/*
 	tests/*
 	prepare/*

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = tab
+indent_size = 4
+insert_final_newline = true
+end_of_line = lf
+
+[*.py]
+indent_style = space
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

CHANGES.rst

@@ -1,3 +1,83 @@
+v3.9.0
+======
+
+* Use of Mapping (dict) interfaces on ``SelectableGroups``
+  is now flagged as deprecated. Instead, users are advised
+  to use the select interface for future compatibility.
+
+  Suppress the warning with this filter:
+  ``ignore:SelectableGroups dict interface``.
+
+  Or with this invocation in the Python environment:
+  ``warnings.filterwarnings('ignore', 'SelectableGroups dict interface')``.
+
+  Preferably, switch to the ``select`` interface introduced
+  in 3.7.0.
+
+v3.8.0
+======
+
+* #290: Add mtime-based caching for ``FastPath`` and its
+  lookups, dramatically increasing performance for repeated
+  distribution lookups.
+
+v3.7.3
+======
+
+* Docs enhancements and cleanup following review in
+  `GH-24782 <https://github.com/python/cpython/pull/24782>`_.
+
+v3.7.2
+======
+
+* Cleaned up cruft in entry_points docstring.
+
+v3.7.1
+======
+
+* Internal refactoring to facilitate ``entry_points() -> dict``
+  deprecation.
+
+v3.7.0
+======
+
+* #131: Added ``packages_distributions`` to conveniently
+  resolve a top-level package or module to its distribution(s).
+
+v3.6.0
+======
+
+* #284: Introduces new ``EntryPoints`` object, a tuple of
+  ``EntryPoint`` objects but with convenience properties for
+  selecting and inspecting the results:
+
+  - ``.select()`` accepts ``group`` or ``name`` keyword
+    parameters and returns a new ``EntryPoints`` tuple
+    with only those that match the selection.
+  - ``.groups`` property presents all of the group names.
+  - ``.names`` property presents the names of the entry points.
+  - Item access (e.g. ``eps[name]``) retrieves a single
+    entry point by name.
+
+  ``entry_points`` now accepts "selection parameters",
+  same as ``EntryPoint.select()``.
+
+  ``entry_points()`` now provides a future-compatible
+  ``SelectableGroups`` object that supplies the above interface
+  (except item access) but remains a dict for compatibility.
+
+  In the future, ``entry_points()`` will return an
+  ``EntryPoints`` object for all entry points.
+
+  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
+  an appropriate DeprecationWarning and will be removed in
+  a future version.
+
 v3.5.0
 ======
 

docs/using.rst

@@ -67,18 +67,48 @@ This package provides the following functionality via its public API.
 Entry points
 ------------
 
-The ``entry_points()`` function returns a dictionary of all entry points,
-keyed by group.  Entry points are represented by ``EntryPoint`` instances;
+The ``entry_points()`` function returns a collection of entry points.
+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()
-    >>> list(eps)
+
+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']
-    >>> scripts = eps['console_scripts']
-    >>> wheel = [ep for ep in scripts if ep.name == 'wheel'][0]
+
+``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
@@ -97,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:
 
@@ -180,6 +221,17 @@ function::
     ["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]
 
 
+Package distributions
+---------------------
+
+A convience method to resolve the distribution or
+distributions (in the case of a namespace package) for top-level
+Python packages or modules::
+
+    >>> packages_distributions()
+    {'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}
+
+
 Distributions
 =============