support enforcing version numbers via the env

4 files changed, 23 insertions, 0 deletions

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 430fc52..3f6410d 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,4 +1,6 @@
 
+* add support for overriding the version number via the 
+  environment variable SETUPTOOLS_SCM_PRETEND_VERSION
 
 * fix isssue #63 by adding the --match parameter to the git describe call
   and prepare the possibility of passing more options to scm backends
diff --git a/README.rst b/README.rst
index 6d0ebdb..578d0a2 100644
--- a/README.rst
+++ b/README.rst
@@ -155,6 +155,15 @@ It optionally accepts the keys of the ``use_scm_version`` parameter as
 keyword arguments.
 
 
+Environment Variables
+---------------------
+
+:SETUPTOOLS_SCM_PRETEND_VERSION:
+  when defined and not empty,
+  its used as the primary source for the version number
+  in which case it will be a unparsed string
+
+
 Extending setuptools_scm
 ------------------------
 
diff --git a/setuptools_scm/__init__.py b/setuptools_scm/__init__.py
index 0e03a7d..ad4be3c 100644
--- a/setuptools_scm/__init__.py
+++ b/setuptools_scm/__init__.py
@@ -9,6 +9,9 @@ from .utils import trace
 from .version import format_version
 from .discover import find_matching_entrypoint
 
+PRETEND_KEY = 'SETUPTOOLS_SCM_PRETEND_VERSION'
+
+
 TEMPLATES = {
     '.py': """\
 # coding: utf-8
@@ -24,6 +27,9 @@ string_types = (str,) if PY3 else (str, unicode)  # noqa
 
 
 def version_from_scm(root):
+    pretended = os.environ.get(PRETEND_KEY)
+    if pretended:
+        return pretended
     ep = find_matching_entrypoint(root, 'setuptools_scm.parse_scm')
     if ep:
         return ep.load()(root)
diff --git a/testing/test_basic_api.py b/testing/test_basic_api.py
index 2e030d7..80c51a3 100644
--- a/testing/test_basic_api.py
+++ b/testing/test_basic_api.py
@@ -50,6 +50,12 @@ def test_root_parameter_pass_by(monkeypatch):
     setuptools_scm.get_version(root='/tmp')
 
 
+def test_pretended(monkeypatch):
+    pretense = '2345'
+    monkeypatch.setenv(setuptools_scm.PRETEND_KEY, pretense)
+    assert setuptools_scm.get_version() == pretense
+
+
 def test_root_relative_to(monkeypatch):
     assert_root(monkeypatch, '/tmp/alt')
     __file__ = '/tmp/module/file.py'