Merge branch 'master' into feature/pep517-metadata

Author: jaraco

.gitlab-ci.yml

@@ -41,6 +41,6 @@ codecov:
 release:
   stage: deploy
   only:
-    - /^\d+\.\d+(\.\d+)?([abc]\d*)?$/
+    - /^v\d+\.\d+(\.\d+)?([abc]\d*)?$/
   script:
     - tox -e release

importlib_metadata/__init__.py

@@ -27,7 +27,7 @@
     ModuleNotFoundError,
     MetaPathFinder,
     email_message_from_string,
-    ensure_is_path,
+    PyPy_repr,
     )
 from importlib import import_module
 from itertools import starmap
@@ -54,7 +54,9 @@ class PackageNotFoundError(ModuleNotFoundError):
     """The package was not found."""
 
 
-class EntryPoint(collections.namedtuple('EntryPointBase', 'name value group')):
+class EntryPoint(
+        PyPy_repr,
+        collections.namedtuple('EntryPointBase', 'name value group')):
     """An entry point as defined by Python packaging conventions.
 
     See `the packaging docs on entry points
@@ -124,6 +126,12 @@ def __iter__(self):
         """
         return iter((self.name, self))
 
+    def __reduce__(self):
+        return (
+            self.__class__,
+            (self.name, self.value, self.group),
+            )
+
 
 class PackagePath(pathlib.PurePosixPath):
     """A reference to a path in a package"""
@@ -211,7 +219,7 @@ def at(path):
         :param path: a string or path-like object
         :return: a concrete Distribution instance for the path
         """
-        return PathDistribution(ensure_is_path(path))
+        return PathDistribution(pathlib.Path(path))
 
     @staticmethod
     def _discover_resolvers():
@@ -362,10 +370,21 @@ class DistributionFinder(MetaPathFinder):
     """
 
     class Context:
+        """
+        Keyword arguments presented by the caller to
+        ``distributions()`` or ``Distribution.discover()``
+        to narrow the scope of a search for distributions
+        in all DistributionFinders.
+
+        Each DistributionFinder may expect any parameters
+        and should attempt to honor the canonical
+        parameters defined below when appropriate.
+        """
 
         name = None
         """
         Specific name for which a distribution finder should match.
+        A name of ``None`` matches all distributions.
         """
 
         def __init__(self, **kwargs):
@@ -375,6 +394,9 @@ def __init__(self, **kwargs):
         def path(self):
             """
             The path that a distribution finder should search.
+
+            Typically refers to Python package paths and defaults
+            to ``sys.path``.
             """
             return vars(self).get('path', sys.path)
 

importlib_metadata/_compat.py

@@ -115,10 +115,20 @@ def py2_message_from_string(text):  # nocoverpy3
 PYPY_OPEN_BUG = getattr(sys, 'pypy_version_info', (9, 9, 9))[:3] <= (7, 1, 1)
 
 
-def ensure_is_path(ob):
-    """Construct a Path from ob even if it's already one.
-    Specialized for Python 3.4.
+class PyPy_repr:
     """
-    if (3,) < sys.version_info < (3, 5):
-        ob = str(ob)  # pragma: nocover
-    return pathlib.Path(ob)
+    Override repr for EntryPoint objects on PyPy to avoid __iter__ access.
+    Ref #97, #102.
+    """
+    affected = hasattr(sys, 'pypy_version_info')
+
+    def __compat_repr__(self):  # pragma: nocover
+        def make_param(name):
+            value = getattr(self, name)
+            return '{name}={value!r}'.format(**locals())
+        params = ', '.join(map(make_param, self._fields))
+        return 'EntryPoint({params})'.format(**locals())
+
+    if affected:  # pragma: nocover
+        __repr__ = __compat_repr__
+    del affected

importlib_metadata/docs/changelog.rst

@@ -2,10 +2,40 @@
  importlib_metadata NEWS
 =========================
 
+v1.3.0
+======
+
+* Improve custom finders documentation. Closes #105.
+
+v1.2.0
+======
+
+* Once again, drop support for Python 3.4. Ref #104.
+
+v1.1.3
+======
+
+* Restored support for Python 3.4 due to improper version
+  compatibility declarations in the v1.1.0 and v1.1.1
+  releases. Closes #104.
+
+v1.1.2
+======
+
+* Repaired project metadata to correctly declare the
+  ``python_requires`` directive. Closes #103.
+
+v1.1.1
+======
+
+* Fixed ``repr(EntryPoint)`` on PyPy 3 also. Closes #102.
+
 v1.1.0
 ======
 
 * Dropped support for Python 3.4.
+* EntryPoints are now pickleable. Closes #96.
+* Fixed ``repr(EntryPoint)`` on PyPy 2. Closes #97.
 
 v1.0.0
 ======

importlib_metadata/docs/conf.py

@@ -166,6 +166,9 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
+    'importlib_resources': (
+        'https://importlib-resources.readthedocs.io/en/latest/', None
+        ),
     }
 
 

importlib_metadata/docs/index.rst

@@ -3,15 +3,15 @@
 ===============================
 
 ``importlib_metadata`` is a library which provides an API for accessing an
-installed package's `metadata`_, such as its entry points or its top-level
+installed package's metadata (see :pep:`566`), such as its entry points or its top-level
 name.  This functionality intends to replace most uses of ``pkg_resources``
-`entry point API`_ and `metadata API`_.  Along with ``importlib.resources`` in
-`Python 3.7 and newer`_ (backported as `importlib_resources`_ for older
+`entry point API`_ and `metadata API`_.  Along with :mod:`importlib.resources` in
+Python 3.7 and newer (backported as :doc:`importlib_resources <importlib_resources:index>` for older
 versions of Python), this can eliminate the need to use the older and less
 efficient ``pkg_resources`` package.
 
 ``importlib_metadata`` is a backport of Python 3.8's standard library
-`importlib.metadata`_ module for Python 2.7, and 3.4 through 3.7.  Users of
+:doc:`importlib.metadata <library/importlib.metadata>` module for Python 2.7, and 3.4 through 3.7.  Users of
 Python 3.8 and beyond are encouraged to use the standard library module.
 When imported on Python 3.8 and later, ``importlib_metadata`` replaces the
 DistributionFinder behavior from the stdlib, but leaves the API in tact.
@@ -46,9 +46,5 @@ Indices and tables
 * :ref:`search`
 
 
-.. _`metadata`: https://www.python.org/dev/peps/pep-0566/
 .. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
 .. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api
-.. _`Python 3.7 and newer`: https://docs.python.org/3/library/importlib.html#module-importlib.resources
-.. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html
-.. _`importlib.metadata`: TBD

importlib_metadata/docs/using.rst

@@ -1,25 +1,25 @@
 .. _using:
 
-==========================
- Using importlib_metadata
-==========================
+=================================
+ Using :mod:`!importlib_metadata`
+=================================
 
 ``importlib_metadata`` is a library that provides for access to installed
 package metadata.  Built in part on Python's import system, this library
 intends to replace similar functionality in the `entry point
 API`_ and `metadata API`_ of ``pkg_resources``.  Along with
-``importlib.resources`` in `Python 3.7
-and newer`_ (backported as `importlib_resources`_ for older versions of
+:mod:`importlib.resources` in Python 3.7
+and newer (backported as :doc:`importlib_resources <importlib_resources:index>` for older versions of
 Python), this can eliminate the need to use the older and less efficient
 ``pkg_resources`` package.
 
 By "installed package" we generally mean a third-party package installed into
 Python's ``site-packages`` directory via tools such as `pip
 <https://pypi.org/project/pip/>`_.  Specifically,
 it means a package with either a discoverable ``dist-info`` or ``egg-info``
-directory, and metadata defined by `PEP 566`_ or its older specifications.
+directory, and metadata defined by :pep:`566` or its older specifications.
 By default, package metadata can live on the file system or in zip archives on
-``sys.path``.  Through an extension mechanism, the metadata can live almost
+:data:`sys.path`.  Through an extension mechanism, the metadata can live almost
 anywhere.
 
 
@@ -127,7 +127,7 @@ Distribution files
 You can also get the full set of files contained within a distribution.  The
 ``files()`` function takes a distribution package name and returns all of the
 files installed by this distribution.  Each file object returned is a
-``PackagePath``, a `pathlib.Path`_ derived object with additional ``dist``,
+``PackagePath``, a :class:`pathlib.Path` derived object with additional ``dist``,
 ``size``, and ``hash`` properties as indicated by the metadata.  For example::
 
     >>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]
@@ -196,18 +196,18 @@ instance::
     >>> d.metadata['License']
     'MIT'
 
-The full set of available metadata is not described here.  See `PEP 566
-<https://www.python.org/dev/peps/pep-0566/>`_ for additional details.
+The full set of available metadata is not described here.  See :pep:`566`
+for additional details.
 
 
 Extending the search algorithm
 ==============================
 
-Because package metadata is not available through ``sys.path`` searches, or
+Because package metadata is not available through :data:`sys.path` searches, or
 package loaders directly, the metadata for a package is found through import
 system `finders`_.  To find a distribution package's metadata,
-``importlib_metadata`` queries the list of `meta path finders`_ on
-`sys.meta_path`_.
+``importlib.metadata`` queries the list of :term:`meta path finders <meta path finder>` on
+:data:`sys.meta_path`.
 
 By default ``importlib_metadata`` installs a finder for distribution packages
 found on the file system.  This finder doesn't actually find any *packages*,
@@ -217,7 +217,7 @@ The abstract class :py:class:`importlib.abc.MetaPathFinder` defines the
 interface expected of finders by Python's import system.
 ``importlib_metadata`` extends this protocol by looking for an optional
 ``find_distributions`` callable on the finders from
-``sys.meta_path`` and presents this extended interface as the
+:data:`sys.meta_path` and presents this extended interface as the
 ``DistributionFinder`` abstract base class, which defines this abstract
 method::
 
@@ -232,28 +232,21 @@ properties indicating the path to search and names to match and may
 supply other relevant context.
 
 What this means in practice is that to support finding distribution package
-metadata in locations other than the file system, you should derive from
-``Distribution`` and implement the ``load_metadata()`` method. Then from
-your finder, return instances of this derived ``Distribution`` in the
+metadata in locations other than the file system, subclass
+``Distribution`` and implement the abstract methods. Then from
+a custom finder, return instances of this derived ``Distribution`` in the
 ``find_distributions()`` method.
 
 
 .. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
 .. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api
-.. _`Python 3.7 and newer`: https://docs.python.org/3/library/importlib.html#module-importlib.resources
-.. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html
-.. _`PEP 566`: https://www.python.org/dev/peps/pep-0566/
 .. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders
-.. _`meta path finders`: https://docs.python.org/3/glossary.html#term-meta-path-finder
-.. _`sys.meta_path`: https://docs.python.org/3/library/sys.html#sys.meta_path
-.. _`pathlib.Path`: https://docs.python.org/3/library/pathlib.html#pathlib.Path
 
 
 .. rubric:: Footnotes
 
 .. [#f1] Technically, the returned distribution metadata object is an
-         `email.message.Message
-         <https://docs.python.org/3/library/email.message.html#email.message.EmailMessage>`_
+         :class:`email.message.EmailMessage`
          instance, but this is an implementation detail, and not part of the
          stable API.  You should only use dictionary-like methods and syntax
          to access the metadata contents.

importlib_metadata/tests/test_main.py

@@ -2,6 +2,8 @@
 from __future__ import unicode_literals
 
 import re
+import json
+import pickle
 import textwrap
 import unittest
 import importlib
@@ -189,3 +191,34 @@ def test_egg(self):
         with self.add_sys_path(egg):
             with self.assertRaises(PackageNotFoundError):
                 version('foo')
+
+
+class TestEntryPoints(unittest.TestCase):
+    def __init__(self, *args):
+        super(TestEntryPoints, self).__init__(*args)
+        self.ep = importlib_metadata.EntryPoint('name', 'value', 'group')
+
+    def test_entry_point_pickleable(self):
+        revived = pickle.loads(pickle.dumps(self.ep))
+        assert revived == self.ep
+
+    def test_immutable(self):
+        """EntryPoints should be immutable"""
+        with self.assertRaises(AttributeError):
+            self.ep.name = 'badactor'
+
+    def test_repr(self):
+        assert 'EntryPoint' in repr(self.ep)
+        assert 'name=' in repr(self.ep)
+        assert "'name'" in repr(self.ep)
+
+    def test_hashable(self):
+        """EntryPoints should be hashable"""
+        hash(self.ep)
+
+    def test_json_dump(self):
+        """
+        json should not expect to be able to dump an EntryPoint
+        """
+        with self.assertRaises(Exception):
+            json.dumps(self.ep)

setup.cfg

@@ -15,7 +15,7 @@ classifiers =
     Programming Language :: Python :: 2
 
 [options]
-python_requires = >=2.7,!=3.0,!=3.1,!=3.2,!=3.3,!=3.4
+python_requires = >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*
 setup_requires = setuptools-scm
 install_requires =
     zipp>=0.5