diff options
author | Ronny Pfannschmidt <opensource@ronnypfannschmidt.de> | 2020-01-08 21:03:51 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-01-08 21:03:51 +0100 |
commit | d9bc1adf88e8d4b22d5d7500563f8de9a95c66ed (patch) | |
tree | 105ce94f5f0cb8039c0c2e382b543cfc306a1576 | |
parent | fbaeaa947e403d78964654d3ab68cbc75caccfec (diff) | |
parent | 147857c0980ca0ae61ecab9225489801b5100db6 (diff) | |
download | setuptools-scm-d9bc1adf88e8d4b22d5d7500563f8de9a95c66ed.tar.gz |
Merge pull request #387 from layday/mention-importlib-metadata
Mention importlib.metadata as alternative to pkg_resources
-rw-r--r-- | README.rst | 57 |
1 files changed, 41 insertions, 16 deletions
@@ -15,6 +15,7 @@ Unwanted files must be excluded by discarding them via ``MANIFEST.in``. .. image:: https://tidelift.com/badges/package/pypi/setuptools-scm :target: https://tidelift.com/subscription/pkg/pypi-setuptools-scm?utm_source=pypi-setuptools-scm&utm_medium=readme + ``pyproject.toml`` usage ------------------------ @@ -103,20 +104,7 @@ Arguments to ``get_version()`` (see below) may be passed as a dictionary to ..., ) -Once configured, you can access the version number in your package via -``pkg_resources`` (`PEP-0396 <https://www.python.org/dev/peps/pep-0396>`_). For -example: - -.. code:: python - - from pkg_resources import get_distribution, DistributionNotFound - try: - __version__ = get_distribution(__name__).version - except DistributionNotFound: - # package is not installed - pass - -You can also confirm the version number locally via ``setup.py``: +You can confirm the version number locally via ``setup.py``: .. code-block:: shell @@ -129,8 +117,8 @@ You can also confirm the version number locally via ``setup.py``: not defined in ``setup.cfg``. -``setup.cfg`` -------------- +``setup.cfg`` usage +------------------- If using `setuptools 30.3.0 <https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files>`_ @@ -189,6 +177,43 @@ than the project's root, you can use: See `setup.py Usage`_ above for how to use this within ``setup.py``. +Retrieving package version at runtime +------------------------------------- + +If you have opted not to hardcode the version number inside the package, +you can retrieve it at runtime from PEP-0566_ metadata using +``importlib.metadata`` from the standard library +or the `importlib_metadata`_ backport: + +.. code:: python + + from importlib.metadata import version, PackageNotFoundError + + try: + __version__ = version(__name__) + except PackageNotFoundError: + # package is not installed + pass + +Alternatively, you can use ``pkg_resources`` which is included in +``setuptools``: + +.. code:: python + + from pkg_resources import get_distribution, DistributionNotFound + + try: + __version__ = get_distribution(__name__).version + except DistributionNotFound: + # package is not installed + pass + +This does place a runtime dependency on ``setuptools``. + +.. _PEP-0566: https://www.python.org/dev/peps/pep-0566/ +.. _importlib_metadata: https://pypi.org/project/importlib-metadata/ + + Usage from Sphinx ----------------- |