Skip to content

Commit b66fc51

Browse files
committed
Fix #303: Fix Version.__init__ method
* 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
1 parent 6bb8ca6 commit b66fc51

File tree

7 files changed

+283
-81
lines changed

7 files changed

+283
-81
lines changed

README.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ different parts, use the ``semver.Version.parse`` function:
5050

5151
.. code-block:: python
5252
53-
>>> ver = semver.Version.parse('1.2.3-pre.2+build.4')
53+
>>> ver = semver.Version('1.2.3-pre.2+build.4')
5454
>>> ver.major
5555
1
5656
>>> ver.minor
@@ -68,7 +68,7 @@ returns a new ``semver.Version`` instance with the raised major part:
6868

6969
.. code-block:: python
7070
71-
>>> ver = semver.Version.parse("3.4.5")
71+
>>> ver = semver.Version("3.4.5")
7272
>>> ver.bump_major()
7373
Version(major=4, minor=0, patch=0, prerelease=None, build=None)
7474

changelog.d/303.doc.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Prefer :meth:`Version.__init__` over :meth:`Version.parse`
2+
and change examples accordingly.

changelog.d/303.feature.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff 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.

docs/usage.rst

Lines changed: 37 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -54,17 +54,20 @@ The preferred way to create a new version is with the class
5454

5555
A :class:`~semver.version.Version` instance can be created in different ways:
5656

57-
* From a Unicode string::
57+
* Without any arguments::
5858

5959
>>> from semver.version import Version
60-
>>> Version.parse("3.4.5-pre.2+build.4")
60+
>>> Version()
61+
Version(major=0, minor=0, patch=0, prerelease=None, build=None)
62+
63+
* From a Unicode string::
64+
65+
>>> Version("3.4.5-pre.2+build.4")
6166
Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
62-
>>> Version.parse(u"5.3.1")
63-
Version(major=5, minor=3, patch=1, prerelease=None, build=None)
6467

6568
* From a byte string::
6669

67-
>>> Version.parse(b"2.3.4")
70+
>>> Version(b"2.3.4")
6871
Version(major=2, minor=3, patch=4, prerelease=None, build=None)
6972

7073
* From individual parts by a dictionary::
@@ -100,6 +103,32 @@ A :class:`~semver.version.Version` instance can be created in different ways:
100103
>>> Version("3", "5", 6)
101104
Version(major=3, minor=5, patch=6, prerelease=None, build=None)
102105

106+
It is possible to combine, positional and keyword arguments. In
107+
some use cases you have a fixed version string, but would like to
108+
replace parts of them. For example::
109+
110+
>>> Version(1, 2, 3, major=2, build="b2")
111+
Version(major=2, minor=2, patch=3, prerelease=None, build='b2')
112+
113+
It is also possible to use a version string and replace specific
114+
parts::
115+
116+
>>> Version("1.2.3", major=2, build="b2")
117+
Version(major=2, minor=2, patch=3, prerelease=None, build='b2')
118+
119+
However, it is not possible to use a string and additional positional
120+
arguments:
121+
122+
>>> Version("1.2.3", 4)
123+
Traceback (most recent call last):
124+
...
125+
ValueError: You cannot pass a string and additional positional arguments
126+
127+
128+
129+
Using Deprecated Functions to Create a Version
130+
----------------------------------------------
131+
103132
The old, deprecated module level functions are still available but
104133
using them are discoraged. They are available to convert old code
105134
to semver3.
@@ -130,17 +159,7 @@ Depending on your use case, the following methods are available:
130159
>>> semver.parse("1.2")
131160
Traceback (most recent call last):
132161
...
133-
ValueError: 1.2 is not valid SemVer string
134-
135-
136-
Parsing a Version String
137-
------------------------
138-
139-
"Parsing" in this context means to identify the different parts in a string.
140-
Use the function :func:`Version.parse <semver.version.Version.parse>`::
141-
142-
>>> Version.parse("3.4.5-pre.2+build.4")
143-
Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
162+
ValueError: '1.2' is not valid SemVer string
144163

145164

146165
Checking for a Valid Semver Version
@@ -167,7 +186,7 @@ parts of a version:
167186

168187
.. code-block:: python
169188
170-
>>> v = Version.parse("3.4.5-pre.2+build.4")
189+
>>> v = Version("3.4.5-pre.2+build.4")
171190
>>> v.major
172191
3
173192
>>> v.minor
@@ -436,7 +455,7 @@ To compare two versions depends on your type:
436455
>>> v > "1.0"
437456
Traceback (most recent call last):
438457
...
439-
ValueError: 1.0 is not valid SemVer string
458+
ValueError: '1.0' is not valid SemVer string
440459

441460
* **A** :class:`Version <semver.version.Version>` **type and a** :func:`dict`
442461

src/semver/_types.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@
77
VersionDict = Dict[str, VersionPart]
88
VersionIterator = Iterable[VersionPart]
99
String = Union[str, bytes]
10+
StringOrInt = Union[String, int]
1011
F = TypeVar("F", bound=Callable)

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy