Fix #210: Add classmethod VersionInfo.coerce

tomschr · tomschr · commit bdf2c127a9cd · 2019-12-09T21:32:02.000+01:00
Signature:
VersionInfo.coerce(cls, version:str) -&gt; tuple
  Convert an incomplete version string into a semver-compatible VersionInfo
  object
  - Tries to detect a "basic" version string (``major.minor.patch``).
  - If not enough components can be found, missing components are
    set to zero to obtain a valid semver version.
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -192,6 +192,35 @@ Depending which function you call, you get different types
     {'major': 3, 'minor': 4, 'patch': 5, 'prerelease': None, 'build': None}
 
 
+Parsing Incomplete Versions
+---------------------------
+
+If a version is incomplete (some parts are missing) this would lead to an
+exception during the parsing process. As such, you cannot get a valid
+:class:`semver.VersionInfo` instance.
+
+To avoid such situations, such incomplete version strings can still be parsed
+with the :func:`semver.VersionInfo.coerce` function. This function applies
+the following rules:
+
+* Tries to detect a "basic" version string (``major.minor.patch``).
+* If not enough components can be found, missing components are
+  set to zero to obtain a valid semver version.
+
+It expects a version string and returns a tuple. The first item of the tuple
+is either a :class:`VersionInfo` instance or ``None`` if the function cannot
+extract a version. The second item is the rest of the string:
+
+.. code-block:: python
+
+    >>> semver.VersionInfo.coerce("v1.2")
+    (VersionInfo(major=1, minor=2, patch=0, prerelease=None, build=None), '')
+    >>> semver.VersionInfo.coerce("v1.2-abc")
+    (VersionInfo(major=1, minor=2, patch=0, prerelease=None, build=None), '-abc')
+    >>> semver.VersionInfo.coerce("abc")                                                                                                                     
+    (None, 'abc')
+
+
 Increasing Parts of a Version
 -----------------------------
 
diff --git a/semver.py b/semver.py
@@ -16,6 +16,19 @@
 __maintainer__ = "Sebastien Celles"
 __maintainer_email__ = "s.celles@gmail.com"
 
+_BASEVERSION = re.compile(
+    r"""[vV]?
+        (?P<major>0|[1-9]\d*)
+        (\.
+          (?P<minor>0|[1-9]\d*)
+          (\.
+            (?P<patch>0|[1-9]\d*)
+          )?
+        )?
+    """,
+    re.VERBOSE,
+)
+
 _REGEX = re.compile(
     r"""
         ^
@@ -321,6 +334,34 @@ def replace(self, **parts):
             )
             raise TypeError(error)
 
+    @classmethod
+    def coerce(cls, version):
+        """
+        Convert an incomplete version string into a semver-compatible VersionInfo
+        object
+
+        * Tries to detect a "basic" version string (``major.minor.patch``).
+        * If not enough components can be found, missing components are
+          set to zero to obtain a valid semver version.
+
+        :param str version: the version string to convert
+        :return: a tuple with a :class:`VersionInfo` instance (or ``None``
+          if it's not a version) and the rest of the string which doesn't
+          belong to a basic version.
+        :rtype: tuple(:class:`VersionInfo` | None, str)
+        """
+        match = _BASEVERSION.search(version)
+        if not match:
+            return (None, version)
+
+        ver = {
+            key: 0 if value is None else value
+            for key, value in match.groupdict().items()
+        }
+        ver = cls(**ver)
+        rest = match.string[match.end() :]
+        return ver, rest
+
 
 def _to_dict(obj):
     if isinstance(obj, VersionInfo):
diff --git a/test_semver.py b/test_semver.py
@@ -803,3 +803,21 @@ def test_should_return_versioninfo_with_replaced_parts(version, parts, expected)
 def test_replace_raises_ValueError_for_non_numeric_values():
     with pytest.raises(ValueError):
         VersionInfo.parse("1.2.3").replace(major="x")
+
+
+@pytest.mark.parametrize(
+    "version,expected",
+    [
+        ("v1", ("1.0.0", "")),
+        ("v1.1", ("1.1.0", "")),
+        ("v1.1.1", ("1.1.1", "")),
+        ("v1.1.1-abc", ("1.1.1", "-abc")),
+        ("not-semver", (None, "not-semver")),
+        ("1-2-3", ("1.0.0", "-2-3")),
+    ],
+)
+def test_should_versioninfo_coerce(version, expected):
+    ver = list(VersionInfo.coerce(version))
+    if ver[0] is not None:
+        ver[0] = str(ver[0])
+    assert tuple(ver) == expected
