python-semver · tomschr · Nov 6, 2020 · Nov 6, 2020 · Nov 20, 2020 · Nov 20, 2020
diff --git a/README.rst b/README.rst
@@ -51,7 +51,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
@@ -69,7 +69,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/conf.py b/docs/conf.py
@@ -267,3 +267,19 @@ def find_version(*file_paths):
         "Miscellaneous",
     )
 ]
+
+# ----------------
+# Setup for Sphinx
+
+
+def remove_noqa(app, what, name, obj, options, lines):
+    """Remove any 'noqa' parts in a docstring"""
+    noqa_pattern = re.compile(r"\s+# noqa:.*$")
+    # Remove any "# noqa" parts in a line
+    for idx, line in enumerate(lines):
+        lines[idx] = noqa_pattern.sub("", line, count=1)
+
+
+def setup(app):
+    """Set up the Sphinx app."""
+    app.connect("autodoc-process-docstring", remove_noqa)
diff --git a/docs/migration/migratetosemver3.rst b/docs/migration/migratetosemver3.rst
@@ -1,5 +1,6 @@
 .. _semver2-to-3:
 
+
 Migrating from semver2 to semver3
 =================================
 
@@ -15,8 +16,8 @@ For a more detailed overview of all the changes, refer
 to our :ref:`change-log`.
 
 
-Use Version instead of VersionInfo
-----------------------------------
+Use :class:`Version` instead of :class:`VersionInfo`
+----------------------------------------------------
 
 The :class:`VersionInfo` has been renamed to :class:`Version`
 to have a more succinct name.
@@ -30,9 +31,20 @@ If you still need the old version, use this line:
    from semver.version import Version as VersionInfo
 
 
+Use :class:`Version` instead of :meth:`Version.parse`
+-----------------------------------------------------
+
+The :class:`~semver.version.Version` class supports now different variants
+how a version can be called (see section :ref:`sec_creating_version`
+for more details).
+
+It's important to know that you do not need to use
+:meth:`Version.parse <semver.version.Version.parse>` anymore. You
+can pass a string directly to :class:`~semver.Version`.
+
 
-Use semver.cli instead of semver
---------------------------------
+Use :mod:`semver.cli` instead of :mod:`semver`
+----------------------------------------------
 
 All functions related to CLI parsing are moved to :mod:`semver.cli`.
 If you need such functions, like :func:`semver.cmd_bump <semver.cli.cmd_bump>`,

diff --git a/docs/usage/compare-versions.rst b/docs/usage/compare-versions.rst
@@ -67,7 +67,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/docs/usage/create-a-version.rst b/docs/usage/create-a-version.rst
@@ -21,17 +21,21 @@ 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::
@@ -47,7 +51,7 @@ A :class:`~semver.version.Version` instance can be created in different ways:
       >>> Version(**d)
       Traceback (most recent call last):
       ...
-      ValueError: 'major' is negative. A version can only be positive.
+      ValueError: Argument -3 is negative. A version can only be positive.
 
   As a minimum requirement, your dictionary needs at least the ``major``
   key, others can be omitted. You get a ``TypeError`` if your
@@ -67,6 +71,31 @@ 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.
@@ -97,4 +126,4 @@ 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
+    ValueError: '1.2' is not valid SemVer string
diff --git a/src/semver/_types.py b/src/semver/_types.py
@@ -8,5 +8,6 @@
 VersionDict = Dict[str, VersionPart]
 VersionIterator = Iterable[VersionPart]
 String = Union[str, bytes]
+StringOrInt = Union[String, int]
 F = TypeVar("F", bound=Callable)
 Decorator = Union[Callable[..., F], partial]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Prefer :meth:`Version.__init__` over :meth:`Version.parse`
		and change examples accordingly.