Switch to setuptools_scm.

A few noteworthy points:

- The contents in the sdist now exactly match what `git archive` would
  include; this avoids having to additionally keep track of things in
  MANIFEST.in (as noted in contributing.rst).

- The `__version__` of an editable install is no longer recomputed at
  each import (as was done with `versioneer`, but only whenever the
  project is (re)installed; this can actually save quite a bit of time
  when working with many editable installs as each version recomputation
  requires shelling out a subprocess.  (If really wanted we could
  keep the old behavior by optionally adding a runtime dependency
  on setuptools_scm and calling `setuptools_scm.get_version` in
  `matplotlib/__init__.py`.)

.flake8

@@ -35,7 +35,6 @@ exclude =
     doc/gallery
     doc/tutorials
     # External files.
-    versioneer.py
     tools/gh_api.py
     tools/github_stats.py
     .tox

.git_archival.txt

@@ -0,0 +1 @@
+ref-names: $Format:%D$

.gitattributes

@@ -2,4 +2,4 @@
 *.ppm binary
 *.svg binary
 *.svg linguist-language=true
-lib/matplotlib/_version.py export-subst
+.git_archival.txt export-subst

.github/workflows/tests.yml

@@ -141,7 +141,7 @@ jobs:
 
           # Install dependencies from PyPI.
           python -m pip install --upgrade $PRE \
-            cycler kiwisolver numpy pillow pyparsing python-dateutil \
+            cycler kiwisolver numpy pillow pyparsing python-dateutil setuptools-scm \
             -r requirements/testing/all.txt \
             ${{ matrix.extra-requirements }}
 

.gitignore

@@ -42,6 +42,8 @@ pip-wheel-metadata/*
 # tox testing tool
 .tox
 setup.cfg
+# generated by setuptools_scm
+lib/matplotlib/_version.py
 
 # OS generated files #
 ######################

doc/conf.py

@@ -198,7 +198,7 @@ def _check_dependencies():
 try:
     SHA = subprocess.check_output(
         ['git', 'describe', '--dirty']).decode('utf-8').strip()
-# Catch the case where git is not installed locally, and use the versioneer
+# Catch the case where git is not installed locally, and use the setuptools_scm
 # version number instead
 except (subprocess.CalledProcessError, FileNotFoundError):
     SHA = matplotlib.__version__

doc/devel/contributing.rst

@@ -323,7 +323,7 @@ New modules and files: installation
 
 * If you have added new files or directories, or reorganized existing
   ones, make sure the new files are included in the match patterns in
-  :file:`MANIFEST.in`, and/or in *package_data* in :file:`setup.py`.
+  in *package_data* in :file:`setupext.py`.
 
 C/C++ extensions
 ----------------

doc/devel/release_guide.rst

@@ -176,14 +176,12 @@ Finally, push the tag to GitHub::
 
 Congratulations, the scariest part is done!
 
-.. [#] The tarball that is provided by GitHub is produced using `git
-       archive <https://git-scm.com/docs/git-archive>`__.  We use
-       `versioneer <https://github.com/warner/python-versioneer>`__
-       which uses a format string in
+.. [#] The tarball that is provided by GitHub is produced using `git archive`_.
+       We use setuptools_scm_ which uses a format string in
        :file:`lib/matplotlib/_version.py` to have ``git`` insert a
        list of references to exported commit (see
        :file:`.gitattributes` for the configuration).  This string is
-       then used by ``versioneer`` to produce the correct version,
+       then used by ``setuptools_scm`` to produce the correct version,
        based on the git tag, when users install from the tarball.
        However, if there is a branch pointed at the tagged commit,
        then the branch name will also be included in the tarball.
@@ -195,6 +193,8 @@ Congratulations, the scariest part is done!
 
           git archive v2.0.0 -o matplotlib-2.0.0.tar.gz --prefix=matplotlib-2.0.0/
 
+.. _git archive: https://git-scm.com/docs/git-archive
+.. _setuptools_scm: https://github.com/pypa/setuptools_scm
 
 If this is a final release, also create a 'doc' branch (this is not
 done for pre-releases)::

lib/matplotlib/__init__.py

@@ -102,20 +102,15 @@
 import tempfile
 import warnings
 
+import numpy
+
 # cbook must import matplotlib only within function
 # definitions, so it is safe to import from it here.
-from . import _api, cbook, docstring, rcsetup
+from . import _api, _version, cbook, docstring, rcsetup
 from matplotlib.cbook import MatplotlibDeprecationWarning, sanitize_sequence
 from matplotlib.cbook import mplDeprecation  # deprecated
 from matplotlib.rcsetup import validate_backend, cycler
 
-import numpy
-
-# Get the version from the _version.py versioneer file. For a git checkout,
-# this is computed based on the number of commits since the last tag.
-from ._version import get_versions
-__version__ = str(get_versions()['version'])
-del get_versions
 
 _log = logging.getLogger(__name__)
 
@@ -135,6 +130,27 @@
 }"""
 
 
+def __getattr__(name):
+    if name == "__version__":
+        import setuptools_scm
+        global __version__  # cache it.
+        # Only shell out to a git subprocess if really needed, and not on a
+        # shallow clone, such as those used by CI, as the latter would trigger
+        # a warning from setuptools_scm.
+        root = Path(__file__).resolve().parents[2]
+        if (root / ".git").exists() and not (root / ".git/shallow").exists():
+            __version__ = setuptools_scm.get_version(
+                root=root,
+                version_scheme="post-release",
+                local_scheme="node-and-date",
+                fallback_version=_version.version,
+            )
+        else:  # Get the version from the _version.py setuptools_scm file.
+            __version__ = _version.version
+        return __version__
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 def _check_versions():
 
     # Quickfix to ensure Microsoft Visual C++ redistributable
@@ -724,6 +740,7 @@ def _rc_params_in_file(fname, transform=lambda x: x, fail_on_error=False):
     fail_on_error : bool, default: False
         Whether invalid entries should result in an exception or a warning.
     """
+    import matplotlib as mpl
     rc_temp = {}
     with _open_file_or_url(fname) as fd:
         try:
@@ -770,7 +787,10 @@ def _rc_params_in_file(fname, transform=lambda x: x, fail_on_error=False):
                 version, name=key, alternative=alt_key, obj_type='rcparam',
                 addendum="Please update your matplotlibrc.")
         else:
-            version = 'master' if '.post' in __version__ else f'v{__version__}'
+            # __version__ must be looked up as an attribute to trigger the
+            # module-level __getattr__.
+            version = ('master' if '.post' in mpl.__version__
+                       else f'v{mpl.__version__}')
             _log.warning("""
 Bad key %(key)s in file %(fname)s, line %(line_no)s (%(line)r)
 You probably need to get an updated matplotlibrc file from
@@ -1385,7 +1405,6 @@ def inner(ax, *args, data=None, **kwargs):
     return inner
 
 
-_log.debug('matplotlib version %s', __version__)
 _log.debug('interactive is %s', is_interactive())
 _log.debug('platform is %s', sys.platform)
 _log.debug('loaded modules: %s', list(sys.modules))