Fix #208: Introduce VersionInfo.isvalid() function

tomschr · tomschr · commit 3df41bccc32d · 2019-12-09T12:36:45.000+01:00
* VersionInfo.isvalid(cls, version:str) -&gt; bool
* Add test case
* Describe function in documentation
* Amend pysemver script with "is-valid" 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:`is-valid` 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
@@ -121,6 +121,28 @@ are valid (return code 0) or not (return code != 0)::
     ERROR 1.2.x is not valid SemVer string
     2
 
+pysemver is-valid
+~~~~~~~~~~~~~~~~~
+
+Checks if a string is a valid semver version.
+
+.. code:: bash
+
+   pysemver is-valid <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 is-valid 1.2.3; echo $?
+    0
+    $ pysemver is-valid 2.1; echo $?
+    ERROR Invalid version '2.1'
+    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,13 @@ def createparser():
         sb.add_parser("build", help="Bump the build part of the version"),
     ):
         p.add_argument("version", help="Version to raise")
+
+    # Create the is-valid subcommand
+    parser_isvalid = s.add_parser("is-valid",
+                                  help="Checks if a string is a valid semver version")
+    parser_isvalid.set_defaults(which="is-valid")
+    parser_isvalid.add_argument("version", help="Version to check")
+
     return parser
 
 
@@ -697,6 +719,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 +741,11 @@ def process(args):
     elif args.which == "compare":
         return str(compare(args.version1, args.version2))
 
+    elif args.which == "is-valid":
+        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 +760,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
@@ -803,3 +803,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
