Improve pysemver subcommands (#214)

tomschr · scls19fr · commit 5755f9a58cbe · 2020-01-19T19:39:50.000+01:00
* Use separate cmd_* functions for each subcommand
* Replace which with func keyword
* Use func keyword to store the specific cmd_* function
* Adapt tests
* (Re)format with black
* Clarify return code in manpage (add new section "Return Code")

=&gt; Easier to extend
diff --git a/docs/pysemver.rst b/docs/pysemver.rst
@@ -133,17 +133,39 @@ to indicates which is the bigger version:
 * ``0`` if both versions are the same,
 * ``1`` if the first version is greater than the second version.
 
-The *error code* returned by the script indicates if both versions
-are valid (return code 0) or not (return code != 0)::
+
+Return Code
+-----------
+
+The *return code* of the script (accessible by ``$?`` from the Bash)
+indicates if the subcommand returned successfully nor not. It is *not*
+meant as the result of the subcommand.
+
+The result of the subcommand is printed on the standard out channel
+("stdout" or ``0``), any error messages to standard error ("stderr" or
+``2``).
+
+For example, to compare two versions, the command expects two valid
+semver versions::
 
     $ pysemver compare 1.2.3 2.4.0
     -1
-    $ pysemver compare 1.2.3 2.4.0 ; echo $?
+    $ echo $?
     0
-    $ pysemver compare 1.2.3 2.4.0 ; echo $?
-    ERROR 1.2.x is not valid SemVer string
+
+The return code is zero, but the result is ``-1``.
+
+However, if you pass invalid versions, you get this situation::
+
+    $ pysemver compare 1.2.3 2.4
+    ERROR 2.4 is not valid SemVer string
+    $ echo $?
     2
 
+If you use the :command:`pysemver` in your own scripts, check the
+return code first before you process the standard output.
+
+
 See also
 --------
 
diff --git a/semver.py b/semver.py
@@ -684,6 +684,61 @@ def finalize_version(version):
     return format_version(verinfo["major"], verinfo["minor"], verinfo["patch"])
 
 
+def cmd_bump(args):
+    """
+    Subcommand: Bumps a version.
+
+    Synopsis: bump <PART> <VERSION>
+    <PART> can be major, minor, patch, prerelease, or build
+
+    :param args: The parsed arguments
+    :type args: :class:`argparse.Namespace`
+    :return: the new, bumped version
+    """
+    maptable = {
+        "major": "bump_major",
+        "minor": "bump_minor",
+        "patch": "bump_patch",
+        "prerelease": "bump_prerelease",
+        "build": "bump_build",
+    }
+    if args.bump is None:
+        # When bump is called without arguments,
+        # print the help and exit
+        args.parser.parse_args(["bump", "-h"])
+
+    ver = parse_version_info(args.version)
+    # get the respective method and call it
+    func = getattr(ver, maptable[args.bump])
+    return str(func())
+
+
+def cmd_check(args):
+    """
+    Subcommand: Checks if a string is a valid semver version.
+
+    Synopsis: check <VERSION>
+
+    :param args: The parsed arguments
+    :type args: :class:`argparse.Namespace`
+    """
+    if VersionInfo.isvalid(args.version):
+        return None
+    raise ValueError("Invalid version %r" % args.version)
+
+
+def cmd_compare(args):
+    """
+    Subcommand: Compare two versions
+
+    Synopsis: compare <VERSION1> <VERSION2>
+
+    :param args: The parsed arguments
+    :type args: :class:`argparse.Namespace`
+    """
+    return str(compare(args.version1, args.version2))
+
+
 def createparser():
     """
     Create an :class:`argparse.ArgumentParser` instance.
@@ -700,13 +755,13 @@ def createparser():
     s = parser.add_subparsers()
     # create compare subcommand
     parser_compare = s.add_parser("compare", help="Compare two versions")
-    parser_compare.set_defaults(which="compare")
+    parser_compare.set_defaults(func=cmd_compare)
     parser_compare.add_argument("version1", help="First version")
     parser_compare.add_argument("version2", help="Second version")
 
     # create bump subcommand
     parser_bump = s.add_parser("bump", help="Bumps a version")
-    parser_bump.set_defaults(which="bump")
+    parser_bump.set_defaults(func=cmd_bump)
     sb = parser_bump.add_subparsers(title="Bump commands", dest="bump")
 
     # Create subparsers for the bump subparser:
@@ -723,7 +778,7 @@ def createparser():
     parser_check = s.add_parser(
         "check", help="Checks if a string is a valid semver version"
     )
-    parser_check.set_defaults(which="check")
+    parser_check.set_defaults(func=cmd_check)
     parser_check.add_argument("version", help="Version to check")
 
     return parser
@@ -740,35 +795,12 @@ def process(args):
     :return: result of the selected action
     :rtype: str
     """
-    if not hasattr(args, "which"):
+    if not hasattr(args, "func"):
         args.parser.print_help()
         raise SystemExit()
 
-    elif args.which == "bump":
-        maptable = {
-            "major": "bump_major",
-            "minor": "bump_minor",
-            "patch": "bump_patch",
-            "prerelease": "bump_prerelease",
-            "build": "bump_build",
-        }
-        if args.bump is None:
-            # When bump is called without arguments,
-            # print the help and exit
-            args.parser.parse_args([args.which, "-h"])
-
-        ver = parse_version_info(args.version)
-        # get the respective method and call it
-        func = getattr(ver, maptable[args.bump])
-        return str(func())
-
-    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)
+    # Call the respective function object:
+    return args.func(args)
 
 
 def main(cliargs=None):
diff --git a/test_semver.py b/test_semver.py
@@ -9,6 +9,9 @@
     bump_minor,
     bump_patch,
     bump_prerelease,
+    cmd_bump,
+    cmd_check,
+    cmd_compare,
     compare,
     createparser,
     finalize_version,
@@ -684,87 +687,70 @@ def test_should_be_able_to_use_integers_as_prerelease_build():
 @pytest.mark.parametrize(
     "cli,expected",
     [
-        (
-            ["bump", "major", "1.2.3"],
-            Namespace(which="bump", bump="major", version="1.2.3"),
-        ),
-        (
-            ["bump", "minor", "1.2.3"],
-            Namespace(which="bump", bump="minor", version="1.2.3"),
-        ),
-        (
-            ["bump", "patch", "1.2.3"],
-            Namespace(which="bump", bump="patch", version="1.2.3"),
-        ),
+        (["bump", "major", "1.2.3"], Namespace(bump="major", version="1.2.3")),
+        (["bump", "minor", "1.2.3"], Namespace(bump="minor", version="1.2.3")),
+        (["bump", "patch", "1.2.3"], Namespace(bump="patch", version="1.2.3")),
         (
             ["bump", "prerelease", "1.2.3"],
-            Namespace(which="bump", bump="prerelease", version="1.2.3"),
-        ),
-        (
-            ["bump", "build", "1.2.3"],
-            Namespace(which="bump", bump="build", version="1.2.3"),
+            Namespace(bump="prerelease", version="1.2.3"),
         ),
+        (["bump", "build", "1.2.3"], Namespace(bump="build", version="1.2.3")),
         # ---
-        (
-            ["compare", "1.2.3", "2.1.3"],
-            Namespace(which="compare", version1="1.2.3", version2="2.1.3"),
-        ),
+        (["compare", "1.2.3", "2.1.3"], Namespace(version1="1.2.3", version2="2.1.3")),
         # ---
-        (["check", "1.2.3"], Namespace(which="check", version="1.2.3")),
+        (["check", "1.2.3"], Namespace(version="1.2.3")),
     ],
 )
 def test_should_parse_cli_arguments(cli, expected):
     parser = createparser()
     assert parser
     result = parser.parse_args(cli)
+    del result.func
     assert result == expected
 
 
 @pytest.mark.parametrize(
-    "args,expectation",
+    "func,args,expectation",
     [
         # bump subcommand
+        (cmd_bump, Namespace(bump="major", version="1.2.3"), does_not_raise("2.0.0")),
+        (cmd_bump, Namespace(bump="minor", version="1.2.3"), does_not_raise("1.3.0")),
+        (cmd_bump, Namespace(bump="patch", version="1.2.3"), does_not_raise("1.2.4")),
         (
-            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"),
+            cmd_bump,
+            Namespace(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"),
+            cmd_bump,
+            Namespace(bump="build", version="1.2.3+build.13"),
             does_not_raise("1.2.3+build.14"),
         ),
         # compare subcommand
         (
-            Namespace(which="compare", version1="1.2.3", version2="2.1.3"),
+            cmd_compare,
+            Namespace(version1="1.2.3", version2="2.1.3"),
             does_not_raise("-1"),
         ),
         (
-            Namespace(which="compare", version1="1.2.3", version2="1.2.3"),
+            cmd_compare,
+            Namespace(version1="1.2.3", version2="1.2.3"),
             does_not_raise("0"),
         ),
         (
-            Namespace(which="compare", version1="2.4.0", version2="2.1.3"),
+            cmd_compare,
+            Namespace(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)),
+        (cmd_check, Namespace(version="1.2.3"), does_not_raise(None)),
+        (cmd_check, Namespace(version="1.2"), pytest.raises(ValueError)),
     ],
 )
-def test_should_process_parsed_cli_arguments(args, expectation):
+def test_should_process_parsed_cli_arguments(func, args, expectation):
     with expectation as expected:
-        assert process(args) == expected
+        result = func(args)
+        assert result == expected
 
 
 def test_should_process_print(capsys):
