Fix #208: Introduce VersionInfo.isvalid() function (#209)

tomschr · scls19fr · commit f2c23f638220 · 2019-12-10T06:44:34.000+01:00
* VersionInfo.isvalid(cls, version:str) -&gt; bool
* Add test case
* Describe function in documentation
* Amend pysemver script with "check" subcommand
* Update manpage (pysemver.rst)
* Update `CHANGELOG.rst`
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -20,6 +20,9 @@ Features
 * :gh:`191` (:pr:`194`): Created manpage for pysemver
 * :gh:`196` (:pr:`197`): Added distribution specific installation instructions
 * :gh:`201` (:pr:`202`): Reformatted source code with black
+* :gh:`208` (:pr:`209`): Introduce new function :func:`semver.VersionInfo.isvalid`
+  and extend :command:`pysemver` with :command:`check` subcommand
+
 
 Bug Fixes
 ---------
@@ -54,7 +57,6 @@ Features
 * :pr:`166`: Reworked :file:`.gitignore` file
 * :gh:`167` (:pr:`168`): Introduced global constant :data:`SEMVER_SPEC_VERSION`
 
-
 Bug Fixes
 ---------
 
diff --git a/docs/pysemver.rst b/docs/pysemver.rst
@@ -86,6 +86,29 @@ you get an error message and a return code != 0::
    ERROR 1.5 is not valid SemVer string
 
 
+pysemver check
+~~~~~~~~~~~~~~
+
+Checks if a string is a valid semver version.
+
+.. code:: bash
+
+   pysemver check <VERSION>
+
+.. option:: <VERSION>
+
+    The version string to check.
+
+The *error code* returned by the script indicates if the
+version is valid (=0) or not (!=0)::
+
+    $ pysemver check 1.2.3; echo $?
+    0
+    $ pysemver check 2.1; echo $?
+    ERROR Invalid version '2.1'
+    2
+
+
 pysemver compare
 ~~~~~~~~~~~~~~~~
 
@@ -121,7 +144,6 @@ are valid (return code 0) or not (return code != 0)::
     ERROR 1.2.x is not valid SemVer string
     2
 
-
 See also
 --------
 
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -53,6 +53,13 @@ A version can be created in different ways:
     >>> semver.VersionInfo(1, 2, 3, 4, 5)
     VersionInfo(major=1, minor=2, patch=3, prerelease=4, build=5)
 
+If you pass an invalid version string you will get a ``ValueError``::
+
+    >>> semver.parse("1.2")
+    Traceback (most recent call last)
+    ...
+    ValueError: 1.2 is not valid SemVer string
+
 
 Parsing a Version String
 ------------------------
@@ -77,6 +84,20 @@ Parsing a Version String
     {'major': 3, 'minor': 4, 'patch': 5,  'prerelease': 'pre.2', 'build': 'build.4'}
 
 
+Checking for a Valid Semver Version
+-----------------------------------
+
+If you need to check a string if it is a valid semver version, use the
+classmethod :func:`semver.VersionInfo.isvalid`:
+
+.. code-block:: python
+
+    >>> VersionInfo.isvalid("1.0.0")
+    True
+    >>> VersionInfo.isvalid("invalid")
+    False
+
+
 Accessing Parts of a Version
 ----------------------------
 
diff --git a/semver.py b/semver.py
@@ -321,6 +321,21 @@ def replace(self, **parts):
             )
             raise TypeError(error)
 
+    @classmethod
+    def isvalid(cls, version):
+        """Check if the string is a valid semver version
+
+        :param str version: the version string to check
+        :return: True if the version string is a valid semver version, False
+                 otherwise.
+        :rtype: bool
+        """
+        try:
+            cls.parse(version)
+            return True
+        except ValueError:
+            return False
+
 
 def _to_dict(obj):
     if isinstance(obj, VersionInfo):
@@ -681,6 +696,14 @@ def createparser():
         sb.add_parser("build", help="Bump the build part of the version"),
     ):
         p.add_argument("version", help="Version to raise")
+
+    # Create the check subcommand
+    parser_check = s.add_parser(
+        "check", help="Checks if a string is a valid semver version"
+    )
+    parser_check.set_defaults(which="check")
+    parser_check.add_argument("version", help="Version to check")
+
     return parser
 
 
@@ -697,6 +720,7 @@ def process(args):
     if not hasattr(args, "which"):
         args.parser.print_help()
         raise SystemExit()
+
     elif args.which == "bump":
         maptable = {
             "major": "bump_major",
@@ -718,6 +742,11 @@ def process(args):
     elif args.which == "compare":
         return str(compare(args.version1, args.version2))
 
+    elif args.which == "check":
+        if VersionInfo.isvalid(args.version):
+            return None
+        raise ValueError("Invalid version %r" % args.version)
+
 
 def main(cliargs=None):
     """Entry point for the application script
@@ -732,7 +761,8 @@ def main(cliargs=None):
         # Save parser instance:
         args.parser = parser
         result = process(args)
-        print(result)
+        if result is not None:
+            print(result)
         return 0
 
     except (ValueError, TypeError) as err:
diff --git a/test_semver.py b/test_semver.py
@@ -1,4 +1,5 @@
 from argparse import Namespace
+from contextlib import contextmanager
 import pytest  # noqa
 
 from semver import (
@@ -41,6 +42,11 @@
 ]
 
 
+@contextmanager
+def does_not_raise(item):
+    yield item
+
+
 @pytest.mark.parametrize(
     "string,expected", [("rc", "rc"), ("rc.1", "rc.2"), ("2x", "3x")]
 )
@@ -703,6 +709,8 @@ def test_should_be_able_to_use_integers_as_prerelease_build():
             ["compare", "1.2.3", "2.1.3"],
             Namespace(which="compare", version1="1.2.3", version2="2.1.3"),
         ),
+        # ---
+        (["check", "1.2.3"], Namespace(which="check", version="1.2.3")),
     ],
 )
 def test_should_parse_cli_arguments(cli, expected):
@@ -713,25 +721,50 @@ def test_should_parse_cli_arguments(cli, expected):
 
 
 @pytest.mark.parametrize(
-    "args,expected",
+    "args,expectation",
     [
         # bump subcommand
-        (Namespace(which="bump", bump="major", version="1.2.3"), "2.0.0"),
-        (Namespace(which="bump", bump="minor", version="1.2.3"), "1.3.0"),
-        (Namespace(which="bump", bump="patch", version="1.2.3"), "1.2.4"),
-        (Namespace(which="bump", bump="prerelease", version="1.2.3-rc1"), "1.2.3-rc2"),
+        (
+            Namespace(which="bump", bump="major", version="1.2.3"),
+            does_not_raise("2.0.0"),
+        ),
+        (
+            Namespace(which="bump", bump="minor", version="1.2.3"),
+            does_not_raise("1.3.0"),
+        ),
+        (
+            Namespace(which="bump", bump="patch", version="1.2.3"),
+            does_not_raise("1.2.4"),
+        ),
+        (
+            Namespace(which="bump", bump="prerelease", version="1.2.3-rc1"),
+            does_not_raise("1.2.3-rc2"),
+        ),
         (
             Namespace(which="bump", bump="build", version="1.2.3+build.13"),
-            "1.2.3+build.14",
+            does_not_raise("1.2.3+build.14"),
         ),
         # compare subcommand
-        (Namespace(which="compare", version1="1.2.3", version2="2.1.3"), "-1"),
-        (Namespace(which="compare", version1="1.2.3", version2="1.2.3"), "0"),
-        (Namespace(which="compare", version1="2.4.0", version2="2.1.3"), "1"),
+        (
+            Namespace(which="compare", version1="1.2.3", version2="2.1.3"),
+            does_not_raise("-1"),
+        ),
+        (
+            Namespace(which="compare", version1="1.2.3", version2="1.2.3"),
+            does_not_raise("0"),
+        ),
+        (
+            Namespace(which="compare", version1="2.4.0", version2="2.1.3"),
+            does_not_raise("1"),
+        ),
+        # check subcommand
+        (Namespace(which="check", version="1.2.3"), does_not_raise(None)),
+        (Namespace(which="check", version="1.2"), pytest.raises(ValueError)),
     ],
 )
-def test_should_process_parsed_cli_arguments(args, expected):
-    assert process(args) == expected
+def test_should_process_parsed_cli_arguments(args, expectation):
+    with expectation as expected:
+        assert process(args) == expected
 
 
 def test_should_process_print(capsys):
@@ -803,3 +836,8 @@ 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")
+
+
+def test_should_versioninfo_isvalid():
+    assert VersionInfo.isvalid("1.0.0") is True
+    assert VersionInfo.isvalid("foo") is False
