Fix #303: Fix Version.__init__ method

tomschr · tomschr · commit 1587fa0d146c · 2020-11-08T15:46:40.000+01:00
* Allow different variants to call Version
* Adapt the documentation and README
* Adapt and amend tests
* Add changelog entries

TODO: Fix typing errors
diff --git a/README.rst b/README.rst
@@ -50,7 +50,7 @@ different parts, use the ``semver.Version.parse`` function:
 
 .. code-block:: python
 
-    >>> ver = semver.Version.parse('1.2.3-pre.2+build.4')
+    >>> ver = semver.Version('1.2.3-pre.2+build.4')
     >>> ver.major
     1
     >>> ver.minor
@@ -68,7 +68,7 @@ returns a new ``semver.Version`` instance with the raised major part:
 
 .. code-block:: python
 
-    >>> ver = semver.Version.parse("3.4.5")
+    >>> ver = semver.Version("3.4.5")
     >>> ver.bump_major()
     Version(major=4, minor=0, patch=0, prerelease=None, build=None)
 
diff --git a/changelog.d/303.doc.rst b/changelog.d/303.doc.rst
@@ -0,0 +1,2 @@
+Prefer :meth:`Version.__init__` over :meth:`Version.parse`
+and change examples accordingly.
diff --git a/changelog.d/303.feature.rst b/changelog.d/303.feature.rst
@@ -0,0 +1,3 @@
+Extend :meth:`Version.__init__` initializer. It allows
+now to have positional and keyword arguments. The keyword
+arguments overwrites any positional arguments.
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -57,14 +57,12 @@ A :class:`~semver.version.Version` instance can be created in different ways:
 * From a Unicode string::
 
     >>> from semver.version import Version
-    >>> Version.parse("3.4.5-pre.2+build.4")
+    >>> Version("3.4.5-pre.2+build.4")
     Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
-    >>> Version.parse(u"5.3.1")
-    Version(major=5, minor=3, patch=1, prerelease=None, build=None)
 
 * From a byte string::
 
-    >>> Version.parse(b"2.3.4")
+    >>> Version(b"2.3.4")
     Version(major=2, minor=3, patch=4, prerelease=None, build=None)
 
 * From individual parts by a dictionary::
@@ -100,6 +98,22 @@ A :class:`~semver.version.Version` instance can be created in different ways:
     >>> Version("3", "5", 6)
     Version(major=3, minor=5, patch=6, prerelease=None, build=None)
 
+It is possible to combine, positional and keyword arguments. In
+some use cases you have a fixed version string, but would like to
+replace parts of them. For example::
+
+    >>> Version(1, 2, 3, major=2, build="b2")
+    Version(major=2, minor=2, patch=3, prerelease=None, build='b2')
+
+In some cases it could be helpful to pass nothing to :class:`Version`::
+
+    >>> Version()
+    Version(major=0, minor=0, patch=0, prerelease=None, build=None)
+
+
+Using Deprecated Functions to Create a Version
+----------------------------------------------
+
 The old, deprecated module level functions are still available but
 using them are discoraged. They are available to convert old code
 to semver3.
@@ -133,16 +147,6 @@ Depending on your use case, the following methods are available:
     ValueError: 1.2 is not valid SemVer string
 
 
-Parsing a Version String
-------------------------
-
-"Parsing" in this context means to identify the different parts in a string.
-Use the function :func:`Version.parse <semver.version.Version.parse>`::
-
-    >>> Version.parse("3.4.5-pre.2+build.4")
-    Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
-
-
 Checking for a Valid Semver Version
 -----------------------------------
 
@@ -167,7 +171,7 @@ parts of a version:
 
 .. code-block:: python
 
-    >>> v = Version.parse("3.4.5-pre.2+build.4")
+    >>> v = Version("3.4.5-pre.2+build.4")
     >>> v.major
     3
     >>> v.minor
diff --git a/src/semver/_types.py b/src/semver/_types.py
@@ -7,4 +7,5 @@
 VersionDict = Dict[str, VersionPart]
 VersionIterator = Iterable[VersionPart]
 String = Union[str, bytes]
+StringOrInt = Union[String, int]
 F = TypeVar("F", bound=Callable)
diff --git a/src/semver/version.py b/src/semver/version.py
@@ -17,10 +17,11 @@
 )
 
 from ._types import (
-    VersionTuple,
+    String,
+    StringOrInt,
     VersionDict,
     VersionIterator,
-    String,
+    VersionTuple,
     VersionPart,
 )
 
@@ -109,12 +110,28 @@ class Version:
     """
     A semver compatible version class.
 
+    :param args: a tuple with version information. It can consist of:
+
+        * a maximum length of 5 items that comprehend the major,
+          minor, patch, prerelease, or build.
+        * a str or bytes string that contains a valid semver
+          version string.
     :param major: version when you make incompatible API changes.
     :param minor: version when you add functionality in
                   a backwards-compatible manner.
     :param patch: version when you make backwards-compatible bug fixes.
     :param prerelease: an optional prerelease string
     :param build: an optional build string
+
+    This gives you some options to call the :class:`Version` class.
+    Precedence has the keyword arguments over the positional arguments.
+
+    >>> Version(1, 2, 3)
+    Version(major=1, minor=2, patch=3, prerelease=None, build=None)
+    >>> Version("2.3.4-pre.2")
+    Version(major=2, minor=3, patch=4, prerelease="pre.2", build=None)
+    >>> Version(major=2, minor=3, patch=4, build="build.2")
+    Version(major=2, minor=3, patch=4, prerelease=None, build="build.2")
     """
 
     __slots__ = ("_major", "_minor", "_patch", "_prerelease", "_build")
@@ -144,27 +161,92 @@ class Version:
 
     def __init__(
         self,
-        major: SupportsInt,
+        *args: Tuple[
+            Union[str, bytes, int],
+            Optional[int],
+            Optional[int],
+            Optional[str],
+            Optional[str],
+        ],
+        major: SupportsInt = 0,
         minor: SupportsInt = 0,
         patch: SupportsInt = 0,
-        prerelease: Union[String, int] = None,
-        build: Union[String, int] = None,
+        prerelease: StringOrInt = None,
+        build: StringOrInt = None,
     ):
+        verlist = [None, None, None, None, None]
+
+        if args and "." in str(args[0]):
+            # we have a version string as first argument
+            cls = self.__class__
+            v = cast(dict, cls._parse(args[0]))  # type: ignore
+            self._major = int(v["major"])
+            self._minor = int(v["minor"])
+            self._patch = int(v["patch"])
+            self._prerelease = v["prerelease"]
+            self._build = v["build"]
+            return
+        if args and len(args) > 5:
+            raise ValueError("You cannot pass more than 5 arguments to Version")
+
+        for index, item in enumerate(args):
+            verlist[index] = args[index]  # type: ignore
+
         # Build a dictionary of the arguments except prerelease and build
-        version_parts = {"major": int(major), "minor": int(minor), "patch": int(patch)}
+        try:
+            version_parts = {
+                # Prefer major, minor, and patch over args
+                "major": int(major or verlist[0] or 0),
+                "minor": int(minor or verlist[1] or 0),
+                "patch": int(patch or verlist[2] or 0),
+            }
+        except ValueError:
+            raise ValueError(
+                "Expected integer or integer string for major, " "minor, or patch"
+            )
 
         for name, value in version_parts.items():
             if value < 0:
                 raise ValueError(
                     "{!r} is negative. A version can only be positive.".format(name)
                 )
 
+        prerelease = prerelease or verlist[3]
+        build = build or verlist[4]
+
         self._major = version_parts["major"]
         self._minor = version_parts["minor"]
         self._patch = version_parts["patch"]
         self._prerelease = None if prerelease is None else str(prerelease)
         self._build = None if build is None else str(build)
 
+    @classmethod
+    def _parse(cls, version: String) -> Dict:
+        """
+        Parse version string to a Version instance.
+
+        .. versionchanged:: 2.11.0
+           Changed method from static to classmethod to
+           allow subclasses.
+
+        :param version: version string
+        :return: a new :class:`Version` instance
+        :raises ValueError: if version is invalid
+
+        >>> semver.Version.parse('3.4.5-pre.2+build.4')
+        Version(major=3, minor=4, patch=5, \
+prerelease='pre.2', build='build.4')
+        """
+        if isinstance(version, bytes):
+            version: str = version.decode("UTF-8")  # type: ignore
+        elif not isinstance(version, String.__args__):  # type: ignore
+            raise TypeError(f"not expecting type {type(version)!r}")
+        match = cls._REGEX.match(cast(str, version))
+        if match is None:
+            raise ValueError(f"{version} is not valid SemVer string")  # type: ignore
+
+        return cast(dict, match.groupdict())
+
     @property
     def major(self) -> int:
         """The major part of a version (read-only)."""
@@ -285,7 +367,7 @@ def bump_major(self) -> "Version":
         Version(major=4, minor=0, patch=0, prerelease=None, build=None)
         """
         cls = type(self)
-        return cls(self._major + 1)
+        return cls(major=self._major + 1)
 
     def bump_minor(self) -> "Version":
         """
@@ -299,7 +381,7 @@ def bump_minor(self) -> "Version":
         Version(major=3, minor=5, patch=0, prerelease=None, build=None)
         """
         cls = type(self)
-        return cls(self._major, self._minor + 1)
+        return cls(major=self._major, minor=self._minor + 1)
 
     def bump_patch(self) -> "Version":
         """
@@ -313,7 +395,7 @@ def bump_patch(self) -> "Version":
         Version(major=3, minor=4, patch=6, prerelease=None, build=None)
         """
         cls = type(self)
-        return cls(self._major, self._minor, self._patch + 1)
+        return cls(major=self._major, minor=self._minor, patch=self._patch + 1)
 
     def bump_prerelease(self, token: str = "rc") -> "Version":
         """
@@ -330,7 +412,12 @@ def bump_prerelease(self, token: str = "rc") -> "Version":
         """
         cls = type(self)
         prerelease = cls._increment_string(self._prerelease or (token or "rc") + ".0")
-        return cls(self._major, self._minor, self._patch, prerelease)
+        return cls(
+            major=self._major,
+            minor=self._minor,
+            patch=self._patch,
+            prerelease=prerelease,
+        )
 
     def bump_build(self, token: str = "build") -> "Version":
         """
@@ -347,7 +434,13 @@ def bump_build(self, token: str = "build") -> "Version":
         """
         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)
+        return cls(
+            major=self._major,
+            minor=self._minor,
+            patch=self._patch,
+            prerelease=self._prerelease,
+            build=build,
+        )
 
     def compare(self, other: Comparable) -> int:
         """
@@ -513,11 +606,11 @@ def __repr__(self) -> str:
         return "%s(%s)" % (type(self).__name__, s)
 
     def __str__(self) -> str:
-        version = "%d.%d.%d" % (self.major, self.minor, self.patch)
+        version = f"{self.major:d}.{self.minor:d}.{self.patch:d}"
         if self.prerelease:
-            version += "-%s" % self.prerelease
+            version += f"-{self.prerelease}"
         if self.build:
-            version += "+%s" % self.build
+            version += f"+{self.build}"
         return version
 
     def __hash__(self) -> int:
@@ -533,7 +626,7 @@ def finalize_version(self) -> "Version":
         '1.2.3'
         """
         cls = type(self)
-        return cls(self.major, self.minor, self.patch)
+        return cls(major=self.major, minor=self.minor, patch=self.patch)
 
     def match(self, match_expr: str) -> bool:
         """
@@ -598,13 +691,7 @@ def parse(cls, version: String) -> "Version":
         Version(major=3, minor=4, patch=5, \
 prerelease='pre.2', build='build.4')
         """
-        version_str = ensure_str(version)
-        match = cls._REGEX.match(version_str)
-        if match is None:
-            raise ValueError(f"{version_str} is not valid SemVer string")
-
-        matched_version_parts: Dict[str, Any] = match.groupdict()
-
+        matched_version_parts: Dict[str, Any] = cls._parse(version)
         return cls(**matched_version_parts)
 
     def replace(self, **parts: Union[int, Optional[str]]) -> "Version":
diff --git a/tests/test_semver.py b/tests/test_semver.py
@@ -80,3 +80,13 @@ def test_should_versioninfo_isvalid():
 def test_versioninfo_compare_should_raise_when_passed_invalid_value():
     with pytest.raises(TypeError):
         Version(1, 2, 3).compare(4)
+
+
+def test_should_raise_when_too_many_arguments():
+    with pytest.raises(ValueError, match=".* more than 5 arguments .*"):
+        Version(1, 2, 3, 4, 5, 6)
+
+
+def test_should_raise_when_incompatible_type():
+    with pytest.raises(TypeError, match="not expecting type .*"):
+        Version.parse(complex(42))

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Prefer :meth:`Version.__init__` over :meth:`Version.parse`
	`2`	`+and change examples accordingly.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+Extend :meth:`Version.__init__` initializer. It allows
	`2`	`+now to have positional and keyword arguments. The keyword`
	`3`	`+arguments overwrites any positional arguments.`