Store precise version number, and append suffixes as-needed to ensure exact version of code can be known: release[+gitsha]+localmod

[+gitsha] will be ignored if this is exactly a release. +localmod will be dropped if there are no uncommitted modifications to the code.

Author: josiahjohnston

.gitignore

@@ -8,3 +8,4 @@ venv
 build*/
 dist*/
 autodoc*
+switch_model/installed_version.py

get_and_record_version.py

@@ -0,0 +1,72 @@
+from __future__ import print_function
+import logging
+import os
+import subprocess
+
+"""
+Define a precise package version that includes any git digests for any commits
+made subsequently to a package release. 
+
+Example: 
+1) Some commits have been made subsequent to an official release (possibly on
+a branch), plus some uncommitted modifications. The version would be:
+v1.0.4+{gitsha}+localmod
+2) Same scenario, but no uncommitted modifications: v1.0.4+{gitsha}
+3) No commits since the last official release: v1.0.4
+
+These functions are encoded into a separate file from setup.py to support
+including precise versions in docker tags.
+"""
+
+def get_git_version():
+	"""
+	Try to get git version like '{tag}+{gitsha}', with the added suffix
+	"+localmod" if the git repo has had any uncommitted modifications. 
+	The "+{gitsha}" suffix will be dropped if this is the tagged version.
+	Code adapted from setuptools_git_version which has an MIT license.
+		https://pypi.org/project/setuptools-git-version/
+	Note: Only look for tags that start with "2." to avoid tags like "demo-v1.0.1".
+	"""
+	git_command = "git describe --tags --long --match '2.*' --dirty --always"
+	fmt = '{tag}+{gitsha}{dirty}'
+
+	git_version = subprocess.check_output(git_command, shell=True).decode('utf-8').strip()
+	parts = git_version.split('-')
+	# FYI, if it can't find a tag for whatever reason, len may be 1 or 2
+	assert len(parts) in (3, 4)
+	if len(parts) == 4:
+		dirty = '+localmod'
+	else:
+		dirty = ''
+	tag, count, sha = parts[:3]
+	if count == '0' and not dirty:
+		return tag
+	return fmt.format(tag=tag, gitsha=sha.lstrip('g'), dirty=dirty)
+
+def get_and_record_version(repo_path):
+	"""
+	Attempt to get an absolute version number that includes commits made since
+	the last release. If that succeeds, record the absolute version and use it
+	for the pip catalog. If that fails, fall back to something reasonable and
+	vague for the pip catalog, using the data from base_version.py.
+	"""
+	pkg_dir = os.path.join(repo_path , 'switch_model', 'data' )
+	try:
+		__version__ = get_git_version()
+		with open(os.path.join(pkg_dir, 'installed_version.txt'), 'w+') as f:
+			f.write(__version__)
+	except subprocess.CalledProcessError as e:
+		logging.warning(
+			"Could not call git as a subprocess to determine precise version."
+			"Falling back to using the static version from version.py")
+		logging.exception(e)
+		module_dat = {}
+		with open(os.path.join(pkg_dir, 'version.py')) as fp:
+			exec(fp.read(), module_dat)
+		__version__ = module_dat['__version__']
+	return __version__
+
+if __name__ == "__main__":
+	repo_path = os.path.dirname(os.path.realpath(__file__))
+	__version__ = get_and_record_version(repo_path)
+	print(get_git_version())

setup.py

@@ -15,12 +15,10 @@
 import os
 from setuptools import setup, find_packages
 
-# Get the version number. Strategy #3 from https://packaging.python.org/single_source_version/
-version_path = os.path.join(os.path.dirname(__file__), 'switch_model', 'version.py')
-version = {}
-with open(version_path) as f:
-    exec(f.read(), version)
-__version__ = version['__version__']
+from get_and_record_version import get_and_record_version
+
+repo_path = os.path.dirname(os.path.realpath(__file__))
+__version__ = get_and_record_version(repo_path)
 
 def read(*rnames):
     return open(os.path.join(os.path.dirname(__file__), *rnames)).read()
@@ -55,6 +53,9 @@ def read(*rnames):
         'Topic :: Software Development :: Libraries :: Python Modules'
     ],
     packages=find_packages(include=['switch_model', 'switch_model.*']),
+	package_data = {
+		'switch_model': ['data/*']
+	},
     keywords=[
         'renewable', 'power', 'energy', 'electricity',
         'production cost', 'capacity expansion',

switch_model/data/__init__.py

@@ -0,0 +1,3 @@
+"""This directory contains any necessary package data or default configuration
+files.
+"""

switch_model/version.py

@@ -1,9 +1,18 @@
 # Copyright (c) 2015-2019 The Switch Authors. All rights reserved.
 # Licensed under the Apache License, Version 2.0, which is in the LICENSE file.
 """
-This file should only include the version. Do not import any packages or
-modules here because this file needs to be executed before Switch is
-installed and executed in environments that don't have any dependencies
-installed.
+This file should only include the version. Do not import anything in here that
+is not part of a minimal python distribution because this file needs to be
+executed before Switch is installed and executed in environments that don't
+have any dependencies installed.
 """
-__version__='2.0.4'
+import os
+
+base_version = '2.0.4'
+
+try:
+    DATA_ROOT = os.path.join(os.path.dirname(__file__), 'data')
+    with open(os.path.join(DATA_ROOT, 'installed_version.txt'), 'r') as f:
+        __version__ = f.read().strip()
+except IOError:
+    __version__ = base_version