Fix #303: Fix Version.__init__ method

tomschr · tomschr · commit b66fc517b586 · 2020-11-08T20:09:22.000+01:00
* Allow different variants to call Version
* Adapt the documentation and README
* Adapt and amend tests
* Add changelog entries
* Introduce a (private) _ensure_str class method
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
@@ -54,17 +54,20 @@ The preferred way to create a new version is with the class
 
 A :class:`~semver.version.Version` instance can be created in different ways:
 
-* From a Unicode string::
+* Without any arguments::
 
     >>> from semver.version import Version
-    >>> Version.parse("3.4.5-pre.2+build.4")
+    >>> Version()
+    Version(major=0, minor=0, patch=0, prerelease=None, build=None)
+
+* From a Unicode string::
+
+    >>> 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 +103,32 @@ 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')
+
+It is also possible to use a version string and replace specific
+parts::
+
+    >>> Version("1.2.3", major=2, build="b2")
+    Version(major=2, minor=2, patch=3, prerelease=None, build='b2')
+
+However, it is not possible to use a string and additional positional
+arguments:
+
+    >>> Version("1.2.3", 4)
+    Traceback (most recent call last):
+      ...
+    ValueError: You cannot pass a string and additional positional arguments
+
+
+
+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.
@@ -130,17 +159,7 @@ Depending on your use case, the following methods are available:
     >>> semver.parse("1.2")
     Traceback (most recent call last):
     ...
-    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')
+    ValueError: '1.2' is not valid SemVer string
 
 
 Checking for a Valid Semver Version
@@ -167,7 +186,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
@@ -436,7 +455,7 @@ To compare two versions depends on your type:
     >>> v > "1.0"
     Traceback (most recent call last):
     ...
-    ValueError: 1.0 is not valid SemVer string
+    ValueError: '1.0' is not valid SemVer string
 
 * **A** :class:`Version <semver.version.Version>` **type and a** :func:`dict`
 
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
diff --git a/tests/test_semver.py b/tests/test_semver.py

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.`