setup.py: Use "git describe" to append a local version label

"superflore-gen-oe-recipes" generates a setting containing the version
of the program that was used to generate the recipes. So that it's
possible to know whether a released version has been used, automatically
append to the version a local version label based on the output from
"git describe --tags --dirty --broken".

setup.py

@@ -2,6 +2,51 @@
 
 import sys
 from setuptools import find_packages, setup
+import git
+from git import Repo
+
+"""
+Returns <public_version> appended with a PEP-440 compliant local version label
+(see https://www.python.org/dev/peps/pep-0440/#local-version-identifiers). The
+local version label is based on the output from
+"git describe --tags --dirty --broken". Nothing is appended if:
+- Git is not available, or
+- "git describe" might not be operating on a branch of superflore.git, or
+- there is no tag for <public_version>, or
+- the HEAD of the current branch is coincident with the tag for <public_version>.
+
+NB. Not using https://pypi.org/project/setuptools-git-version/ because it passes
+"--long" to "git describe" and doesn't pass "--broken".
+"""
+def append_local_version_label(public_version):
+    try:
+        from git import Repo
+        from os import getcwd
+        from os.path import join, samefile
+
+        repo = Repo()
+        """
+        If we're been copied under the working dir of some other Git repo,
+        "git describe" won't return what we're expecting, so don't append
+        anything. The test for this case will also fail if, say, we try to
+        invoke ../setup.py from a subdirectory, but it's better to err on the
+        side of "least surprises".
+        """
+        if not samefile(repo.git_dir, join(getcwd(), '.git')):
+            return public_version
+
+        # The tags have a "v" prefix.
+        val = repo.git.describe(
+            '--match', 'v' + public_version, '--tags', '--dirty', '--broken')
+        """
+        Output from "git describe --tags --dirty --broken" is
+            <TAG>[-<NR-OF-COMMITS>-g<ABBRE-HASH>][-dirty][-broken]
+        Convert to a legal Python local version label, dropping the "v" prefix
+        of the tag.
+        """
+        return val.replace('-', '+', 1).replace('-', '.')[1:]
+    except:
+        return public_version
 
 if sys.version_info < (3, 0):
     sys.exit('Sorry, Python < 3.0 is not supported')
@@ -24,7 +69,7 @@
 
 setup(
     name='superflore',
-    version='0.3.1',
+    version=append_local_version_label('0.3.1'),
     packages=find_packages(exclude=['tests', 'tests.*']),
     author='Hunter L. Allen',
     author_email='[email protected]',