8000 Fix #303: Fix Version.__init__ method · python-semver/python-semver@6f64b71 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6f64b71

Browse files
tomschrtomschr
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 * Add function "remove_noqa" in conf.py to remove any "# noqa" lines for flake8 issues like overly long lines * Introduce a (private) _ensure_str class method
1 parent 1562008 commit 6f64b71

File tree

8 files changed

+303
-87
lines changed

8 files changed

+303
-87
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/conf.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -265,3 +265,19 @@ def find_version(*file_paths):
265265
"Miscellaneous",
266266
)
267267
]
268+
269+
# ----------------
270+
# Setup for Sphinx
271+
272+
273+
def remove_noqa(app, what, name, obj, options, lines):
274+
"""Remove any 'noqa' parts in a docstring"""
275+
noqa_pattern = re.compile(r"\s+# noqa:.*$")
276+
# Remove any "# noqa" parts in a line
277+
for idx, line in enumerate(lines):
278+
lines[idx] = noqa_pattern.sub("", line, count=1)
279+
280+
281+
def setup(app):
282+
"""Set up the Sphinx app."""
283+
app.connect("autodoc-process-docstring", remove_noqa)

‎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)
0