From 3c7c07f135303896a8c13a14697e136c99d4237b Mon Sep 17 00:00:00 2001 From: "John T. Wodder II" Date: Thu, 12 Mar 2020 17:53:55 +0000 Subject: [PATCH 1/2] Describe using importlib-metadata as an alternative to pkg_resources for single-sourcing versions --- .../single-sourcing-package-version.rst | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst index acab9358e..819061e79 100644 --- a/source/guides/single-sourcing-package-version.rst +++ b/source/guides/single-sourcing-package-version.rst @@ -86,8 +86,38 @@ number of your project: installation metadata, which is not necessarily the code that's currently imported. + Note that if the project uses ``pkg_resources`` to fetch its own version at + runtime, then ``setuptools`` (the project that provides ``pkg_resources``) + must be added to the project's ``install_requires`` list. + Example using this technique: `setuptools `_. + A more efficient alternative to ``pkg_resources`` is the + ``importlib.metadata`` package introduced in Python 3.8 and available to + older versions as the ``importlib-metadata`` project. An installed + project's version can be fetched with it as follows:: + + try: + from importlib import metadata + except ImportError: + import importlib_metadata as metadata + + assert metadata.version('pip') == '1.2.0' + + If a project uses this method to fetch its version at runtime, then its + ``install_requires`` value needs to be edited to install + ``importlib-metadata`` on pre-3.8 versions of Python like so:: + + setup( + ... + install_requires=[ + ... + 'importlib-metadata ~= 1.0 ; python_version < "3.8"', + ... + ], + ... + ) + #. Set the value to ``__version__`` in ``sample/__init__.py`` and import ``sample`` in :file:`setup.py`. From c12f84788933319c976981bfe9eb09e11e610f7a Mon Sep 17 00:00:00 2001 From: "John T. Wodder II" Date: Fri, 13 Mar 2020 16:22:28 +0000 Subject: [PATCH 2/2] Move importlib-metadata section before pkg_resources section --- .../single-sourcing-package-version.rst | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst index 819061e79..b6555d8c0 100644 --- a/source/guides/single-sourcing-package-version.rst +++ b/source/guides/single-sourcing-package-version.rst @@ -75,35 +75,23 @@ number of your project: :file:`MANIFEST.in`). #. Set the value in :file:`setup.py`, and have the project code use the - ``pkg_resources`` API. - - :: - - import pkg_resources - assert pkg_resources.get_distribution('pip').version == '1.2.0' - - Be aware that the ``pkg_resources`` API only knows about what's in the - installation metadata, which is not necessarily the code that's currently - imported. - - Note that if the project uses ``pkg_resources`` to fetch its own version at - runtime, then ``setuptools`` (the project that provides ``pkg_resources``) - must be added to the project's ``install_requires`` list. - - Example using this technique: `setuptools `_. - - A more efficient alternative to ``pkg_resources`` is the - ``importlib.metadata`` package introduced in Python 3.8 and available to - older versions as the ``importlib-metadata`` project. An installed - project's version can be fetched with it as follows:: + ``importlib.metadata`` API to fetch the value at runtime. + (``importlib.metadata`` was introduced in Python 3.8 and is available to + older versions as the ``importlib-metadata`` project.) An installed + project's version can be fetched with the API as follows:: try: from importlib import metadata except ImportError: + # Running on pre-3.8 Python; use importlib-metadata package import importlib_metadata as metadata assert metadata.version('pip') == '1.2.0' + Be aware that the ``importlib.metadata`` API only knows about what's in the + installation metadata, which is not necessarily the code that's currently + imported. + If a project uses this method to fetch its version at runtime, then its ``install_requires`` value needs to be edited to install ``importlib-metadata`` on pre-3.8 versions of Python like so:: @@ -118,6 +106,18 @@ number of your project: ... ) + An older (and less efficient) alternative to ``importlib.metadata`` is the + ``pkg_resources`` API provided by ``setuptools``:: + + import pkg_resources + assert pkg_resources.get_distribution('pip').version == '1.2.0' + + If a project uses ``pkg_resources`` to fetch its own version at runtime, + then ``setuptools`` must be added to the project's ``install_requires`` + list. + + Example using this technique: `setuptools `_. + #. Set the value to ``__version__`` in ``sample/__init__.py`` and import ``sample`` in :file:`setup.py`.