Implement of next_version() function

tomschr · gsakkis · ppkt · tomschr · commit 3c3388d8adf3 · 2020-03-14T20:05:08.000+01:00
* Implement semver.next_version(version, part, prerelease_token="rc")
* Add test cases
  * test_next_version
  * test_next_version_with_invalid_parts
* Reformat code with black
* Document it in usage.rst
* Implement "nextver" subcommand for pysemver command

Co-authored-by: George Sakkis &lt;gsakkis@users.noreply.github.com&gt;
Co-Authored-By: Karol &lt;github@ppkt.eu&gt;
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -213,8 +213,8 @@ Depending which function you call, you get different types
     {'major': 3, 'minor': 4, 'patch': 5, 'prerelease': None, 'build': None}
 
 
-Increasing Parts of a Version
------------------------------
+Raising Parts of a Version
+--------------------------
 
 The ``semver`` module contains the following functions to raise parts of
 a version:
@@ -243,6 +243,57 @@ a version:
     '3.4.5-pre.2+build.5'
 
 
+Increasing Parts of a Version Taking into Account Prereleases
+-------------------------------------------------------------
+
+.. versionadded:: 2.9.2
+   Added :func:`semver.next_version`.
+
+If you want to raise your version and take prereleases into account,
+the :func:`semver.next_version` or :func:`semver.VersionInfo.next_version`
+would perhaps a better fit.
+
+
+.. code-block:: python
+
+    >>> semver.next_version("3.4.5-pre.2+build.4", part="prerelease"))
+    '3.4.5-pre.3'
+    >>> semver.next_version("3.4.5-pre.2+build.4", part="patch")
+    '3.4.5'
+    >>> semver.next_version("3.4.5+build.4", part="patch")
+    '3.4.5'
+    >>> semver.next_version("0.1.4", "prerelease")
+    '0.1.5-rc.1'
+
+
+Increasing Parts of a Version and Taking Prereleases into Account
+-----------------------------------------------------------------
+
+.. versionadded:: 2.9.2
+   Added :func:`semver.next_version`.
+
+If you want to raise your version and take prereleases into account,
+the :func:`semver.next_version` or :func:`semver.VersionInfo.next_version`
+would perhaps a better fit.
+
+The function requires two arguments: a version string and a string which
+parts to raise. Currently, only ``major``, ``minor``,  ``patch``, and
+``prerelease`` are allowed. The ``build`` part is currently undefined and
+as such not allowed.
+
+
+.. code-block:: python
+
+    >>> semver.next_version("3.4.5-pre.2+build.4", part="prerelease"))
+    '3.4.5-pre.3'
+    >>> semver.next_version("3.4.5-pre.2+build.4", part="patch")
+    '3.5.0'
+    >>> semver.next_version("3.4.5+build.4", part="patch")
+    '3.4.5'
+    >>> semver.next_version("0.1.4", "prerelease")
+    '0.1.5-rc.1'
+
+
 Comparing Versions
 ------------------
 
@@ -401,8 +452,7 @@ For example:
 
 .. code-block:: python
 
-    >>> coerce("v1.2")                                                                                                                                       
+    >>> coerce("v1.2")
     (VersionInfo(major=1, minor=2, patch=0, prerelease=None, build=None), '')
     >>> coerce("v2.5.2-bla")
     (VersionInfo(major=2, minor=5, patch=2, prerelease=None, build=None), '-bla')
-
diff --git a/semver.py b/semver.py
@@ -257,6 +257,26 @@ def bump_build(self, token="build"):
         """
         return parse_version_info(bump_build(str(self), token))
 
+    def next_version(self, part, prerelease_token="rc"):
+        """
+        Determines the next version, taking prereleases into account.
+
+        The "major", "minor", and "patch" raises the respective parts like
+        the ``bump_*`` functions. The real difference is using the
+        "preprelease" part. It gives you the next patch version of the prerelease,
+        for example:
+
+        >>> semver.next_version("0.1.4", "prerelease")
+        '0.1.5-rc.1'
+
+        :param version: a semver version string
+        :param part: One of "major", "minor", "patch", or "prerelease"
+        :param prerelease_token: prefix string of prerelease, defaults to 'rc'
+        :return:
+        """
+        nxt = next_version(str(self), part, prerelease_token)
+        return parse_version_info(nxt)
+
     @comparator
     def __eq__(self, other):
         return _compare_by_keys(self._asdict(), _to_dict(other)) == 0
@@ -374,14 +394,7 @@ def parse_version_info(version):
     'build.4'
     """
     parts = parse(version)
-    version_info = VersionInfo(
-        parts["major"],
-        parts["minor"],
-        parts["patch"],
-        parts["prerelease"],
-        parts["build"],
-    )
-
+    version_info = VersionInfo(**parts)
     return version_info
 
 
@@ -684,6 +697,53 @@ def finalize_version(version):
     return format_version(verinfo["major"], verinfo["minor"], verinfo["patch"])
 
 
+def next_version(version, part, prerelease_token="rc"):
+    """
+    Determines the next version, taking prereleases into account.
+
+    The "major", "minor", and "patch" raises the respective parts like
+    the ``bump_*`` functions. The real difference is using the
+    "preprelease" part. It gives you the next patch version of the prerelease,
+    for example:
+
+    >>> semver.next_version("0.1.4", "prerelease")
+    '0.1.5-rc.1'
+
+    :param version: a semver version string
+    :param part: One of "major", "minor", "patch", or "prerelease"
+    :param prerelease_token: prefix string of prerelease, defaults to 'rc'
+    :return:
+    """
+    validparts = {
+        "major",
+        "minor",
+        "patch",
+        "prerelease",
+        # "build", # ???
+    }
+    if part not in validparts:
+        raise ValueError(
+            "Invalid part. Expected one of {validparts}, but got {part!r}".format(
+                validparts=validparts, part=part
+            )
+        )
+    version = VersionInfo.parse(version)
+    if (version.prerelease or version.build) and (
+        part == "patch"
+        or (part == "minor" and version.patch == 0)
+        or (part == "major" and version.minor == version.patch == 0)
+    ):
+        return str(version.replace(prerelease=None, build=None))
+
+    if part in ("major", "minor", "patch"):
+        return str(getattr(version, "bump_" + part)())
+
+    if not version.prerelease:
+        version = version.bump_patch()
+    return str(version.bump_prerelease(prerelease_token))
+
+
+# ---- CLI
 def cmd_bump(args):
     """
     Subcommand: Bumps a version.
@@ -739,6 +799,18 @@ def cmd_compare(args):
     return str(compare(args.version1, args.version2))
 
 
+def cmd_nextver(args):
+    """
+    Subcommand: Determines the next version, taking prereleases into account.
+
+    Synopsis: nextver <VERSION> <PART>
+
+    :param args: The parsed arguments
+    :type args: :class:`argparse.Namespace`
+    """
+    return str(next_version(args.version, args.part))
+
+
 def createparser():
     """
     Create an :class:`argparse.ArgumentParser` instance.
@@ -781,6 +853,15 @@ def createparser():
     parser_check.set_defaults(func=cmd_check)
     parser_check.add_argument("version", help="Version to check")
 
+    # Create the nextver subcommand
+    parser_nextver = s.add_parser(
+        "nextver", help="Determines the next version, taking prereleases into account."
+    )
+    parser_nextver.set_defaults(func=cmd_nextver)
+    parser_nextver.add_argument("version", help="Version to raise")
+    parser_nextver.add_argument(
+        "part", help="One of 'major', 'minor', 'patch', or 'prerelease'"
+    )
     return parser
 
 
diff --git a/test_semver.py b/test_semver.py
@@ -20,6 +20,7 @@
     match,
     max_ver,
     min_ver,
+    next_version,
     parse,
     parse_version_info,
     process,
@@ -39,6 +40,7 @@
     match,
     max_ver,
     min_ver,
+    next_version,
     parse,
     process,
     replace,
@@ -827,3 +829,71 @@ def test_replace_raises_ValueError_for_non_numeric_values():
 def test_should_versioninfo_isvalid():
     assert VersionInfo.isvalid("1.0.0") is True
     assert VersionInfo.isvalid("foo") is False
+
+
+@pytest.mark.parametrize(
+    "version, part, expected",
+    [
+        # major
+        ("1.0.4-rc.1", "major", "2.0.0"),
+        ("1.1.0-rc.1", "major", "2.0.0"),
+        ("1.1.4-rc.1", "major", "2.0.0"),
+        ("1.2.3", "major", "2.0.0"),
+        ("1.0.0-rc.1", "major", "1.0.0"),
+        # minor
+        ("0.2.0-rc.1", "minor", "0.2.0"),
+        ("0.2.5-rc.1", "minor", "0.3.0"),
+        ("1.3.1", "minor", "1.4.0"),
+        # patch
+        ("1.3.2", "patch", "1.3.3"),
+        ("0.1.5-rc.2", "patch", "0.1.5"),
+        # prerelease
+        ("0.1.4", "prerelease", "0.1.5-rc.1"),
+        ("0.1.5-rc.1", "prerelease", "0.1.5-rc.2"),
+        # special cases
+        ("0.2.0-rc.1", "patch", "0.2.0"),  # same as "minor"
+        ("1.0.0-rc.1", "patch", "1.0.0"),  # same as "major"
+        ("1.0.0-rc.1", "minor", "1.0.0"),  # same as "major"
+        #
+        ("3.4.5-pre.2+build.4", "prerelease", "3.4.5-pre.3"),
+        ("3.4.5-pre.2+build.4", "patch", "3.4.5"),
+        ("3.4.5+build.4", "patch", "3.4.5"),
+    ],
+)
+def test_next_version(version, part, expected):
+    assert next_version(version, part) == expected
+
+
+def test_next_version_with_invalid_parts():
+    with pytest.raises(ValueError):
+        next_version("1.0.1", "invalid")
+
+
+@pytest.mark.parametrize(
+    "version, part, expected",
+    [
+        # major
+        ("1.0.4-rc.1", "major", "2.0.0"),
+        ("1.1.0-rc.1", "major", "2.0.0"),
+        ("1.1.4-rc.1", "major", "2.0.0"),
+        ("1.2.3", "major", "2.0.0"),
+        ("1.0.0-rc.1", "major", "1.0.0"),
+        # minor
+        ("0.2.0-rc.1", "minor", "0.2.0"),
+        ("0.2.5-rc.1", "minor", "0.3.0"),
+        ("1.3.1", "minor", "1.4.0"),
+        # patch
+        ("1.3.2", "patch", "1.3.3"),
+        ("0.1.5-rc.2", "patch", "0.1.5"),
+        # prerelease
+        ("0.1.4", "prerelease", "0.1.5-rc.1"),
+        ("0.1.5-rc.1", "prerelease", "0.1.5-rc.2"),
+        # special cases
+        ("0.2.0-rc.1", "patch", "0.2.0"),  # same as "minor"
+        ("1.0.0-rc.1", "patch", "1.0.0"),  # same as "major"
+        ("1.0.0-rc.1", "minor", "1.0.0"),  # same as "major"
+    ],
+)
+def test_next_version_with_versioninfo(version, part, expected):
+    ver = VersionInfo.parse(version)
+    assert str(ver.next_version(part)) == expected
