Fix #344 Allow empty string for bump method

tomschr · tomschr · commit 6e8231ca8107 · 2022-12-18T13:16:37.000+01:00
The methods .bump_prerelease('') and .bump_build('') generates
a prerelease and build part without the token.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -16,6 +16,51 @@ in our repository.
 
 .. towncrier release notes start
 
+Version 3.0.0-dev.3
+===================
+
+:Released: 2022-10-04
+:Maintainer:
+
+
+Features
+--------
+
+* :pr:`359`: Add optional parameter ``optional_minor_and_patch`` in :meth:`.Version.parse`  to allow optional
+  minor and patch parts.
+
+* :pr:`362`: Make :meth:`.Version.match` accept a bare version string as match expression, defaulting to
+  equality testing.
+
+* :gh:`364`: Enhance :file:`pyproject.toml` to make it possible to use the
+  :command:`pyproject-build` command from the build module.
+  For more information, see :ref:`build-semver`.
+
+
+
+Improved Documentation
+----------------------
+
+* :gh:`335`: Add new section "Converting versions between PyPI and semver" the limitations
+  and possible use cases to convert from one into the other versioning scheme.
+
+* :gh:`340`: Describe how to get version from a file
+
+* :gh:`343`: Describe combining Pydantic with semver in the "Advanced topic"
+  section.
+
+* :gh:`350`: Restructure usage section. Create subdirectory "usage/" and splitted
+  all section into different files.
+
+* :gh:`351`: Introduce new topics for:
+
+  * "Migration to semver3"
+  * "Advanced topics"
+
+
+
+----
+
 
 Version 3.0.0-dev.3
 ===================
diff --git a/docs/usage/raise-parts-of-a-version.rst b/docs/usage/raise-parts-of-a-version.rst
@@ -28,3 +28,28 @@ a version:
     '3.4.5-pre.2+build.5'
 
 Likewise the module level functions :func:`semver.bump_major`.
+
+For the functions :func:`Version.bump_prerelease <semver.version.Version.bump_prerelease>` and :func:`Version.bump_build <semver.version.Version.bump_build>` it's possible to pass an empty string or ``None``. However,
+it gives different results::
+
+.. code-block:: python
+
+    >>> str(Version.parse("3.4.5").bump_prerelease(''))
+    '3.4.5-1'
+    >>> str(Version.parse("3.4.5").bump_prerelease(None))
+    '3.4.5-rc.1'
+
+An empty string removes any prefix whereas ``None`` is the same as calling
+the method without any argument.
+
+If you already have a prerelease, the argument for the method
+is not taken into account:
+
+.. code-block:: python
+
+    >>> str(Version.parse("3.4.5-rc.1").bump_prerelease(None))
+    '3.4.5-rc.2'
+    >>> str(Version.parse("3.4.5-rc.1").bump_prerelease(''))
+    '3.4.5-rc.2'
+
+
diff --git a/src/semver/version.py b/src/semver/version.py
@@ -298,39 +298,64 @@ def bump_patch(self) -> "Version":
         cls = type(self)
         return cls(self._major, self._minor, self._patch + 1)
 
-    def bump_prerelease(self, token: str = "rc") -> "Version":
+    def bump_prerelease(self, token: Optional[str] = "rc") -> "Version":
         """
         Raise the prerelease part of the version, return a new object but leave
         self untouched.
 
-        :param token: defaults to ``rc``
-        :return: new object with the raised prerelease part
+        :param token: defaults to ``'rc'``
+        :return: new :class:`Version` object with the raised prerelease part.
+            The original object is not modified.
 
         >>> ver = semver.parse("3.4.5")
-        >>> ver.bump_prerelease()
-        Version(major=3, minor=4, patch=5, prerelease='rc.2', \
-build=None)
+        >>> ver.bump_prerelease().prerelease
+        'rc.2'
+        >>> ver.bump_prerelease('').prerelease
+        '1'
         """
         cls = type(self)
-        prerelease = cls._increment_string(self._prerelease or (token or "rc") + ".0")
+        if self._prerelease is not None:
+            prerelease = self._prerelease
+        elif token == "":
+            prerelease = "0"
+        elif token is None:
+            prerelease = "rc.0"
+        else:
+            prerelease = str(token) + ".0"
+
+        # self._prerelease or (token or "rc") + ".0"
+        prerelease = cls._increment_string(prerelease)
         return cls(self._major, self._minor, self._patch, prerelease)
 
-    def bump_build(self, token: str = "build") -> "Version":
+    # VersionPart = Union[int, Optional[str]]
+    def bump_build(self, token: Optional[str] = "build") -> "Version":
         """
         Raise the build part of the version, return a new object but leave self
         untouched.
 
-        :param token: defaults to ``build``
-        :return: new object with the raised build part
+        :param token: defaults to ``'build'``
+        :return: new :class:`Version` object with the raised build part.
+            The original object is not modified.
 
         >>> ver = semver.parse("3.4.5-rc.1+build.9")
         >>> ver.bump_build()
         Version(major=3, minor=4, patch=5, prerelease='rc.1', \
 build='build.10')
         """
         cls = type(self)
-        build = cls._increment_string(self._build or (token or "build") + ".0")
-        return cls(self._major, self._minor, self._patch, self._prerelease, build)
+        if self._build is not None:
+            build = self._build
+        elif token == "":
+            build = "0"
+        elif token is None:
+            build = "build.0"
+        else:
+            build = str(token) + ".0"
+
+        # self._build or (token or "build") + ".0"
+        build = cls._increment_string(build)
+        return cls(self._major, self._minor, self._patch,
+                   self._prerelease, build)
 
     def compare(self, other: Comparable) -> int:
         """
diff --git a/tests/test_bump.py b/tests/test_bump.py
@@ -66,6 +66,30 @@ def test_should_versioninfo_bump_multiple():
     assert v.bump_prerelease().bump_build().bump_build().bump_prerelease() == expected
 
 
+def test_should_versioninfo_bump_prerelease_with_empty_str():
+    v = parse_version_info("3.4.5")
+    expected = parse_version_info("3.4.5-1")
+    assert v.bump_prerelease("") == expected
+
+
+def test_should_versioninfo_bump_prerelease_with_none():
+    v = parse_version_info("3.4.5")
+    expected = parse_version_info("3.4.5-rc.1")
+    assert v.bump_prerelease(None) == expected
+
+
+def test_should_versioninfo_bump_build_with_empty_str():
+    v = parse_version_info("3.4.5")
+    expected = parse_version_info("3.4.5+1")
+    assert v.bump_build("") == expected
+
+
+def test_should_versioninfo_bump_build_with_none():
+    v = parse_version_info("3.4.5")
+    expected = parse_version_info("3.4.5+build.1")
+    assert v.bump_build(None) == expected
+
+
 def test_should_ignore_extensions_for_bump():
     assert bump_patch("3.4.5-rc1+build4") == "3.4.6"
 
