Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/royw/Versio
python version manipulation library
https://github.com/royw/Versio
Last synced: 3 months ago
JSON representation
python version manipulation library
- Host: GitHub
- URL: https://github.com/royw/Versio
- Owner: royw
- License: mit
- Created: 2013-12-17T21:12:10.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2024-05-24T02:20:50.000Z (5 months ago)
- Last Synced: 2024-07-23T05:26:47.346Z (3 months ago)
- Language: Python
- Size: 2.33 MB
- Stars: 12
- Watchers: 4
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.txt
- License: license.txt
Awesome Lists containing this project
- starred-awesome - Versio - python version manipulation library (Python)
README
## Welcome to Versio
End Of Life. As of 2024, you probably should be using [PyPA's packaging](https://github.com/pypa/packaging)
### Latin
Noun
1. a turning, change, version
### Build Information
[](https://github.com/royw/Versio/actions/workflows/pr-lint.yml)
* [Syntax Errors](http://royw.github.io/Versio/reports/flake8-syntax-errors-3.9.txt)
* [Potential Problems](http://royw.github.io/Versio/reports/flake8-problems-3.9.txt)
* [Unit Test Report](http://royw.github.io/Versio/reports/pytest-results-3.9.html)
([XML](http://royw.github.io/Versio/reports/pytest-results-3.9.xml))
* [Code Coverage Report](http://royw.github.io/Versio/reports/coverage-report-3.9/index.html)
([XML](http://royw.github.io/Versio/reports/coverage-3.9.xml))
### About Versio
Versio is a generic version class that supports comparison and version bumping (incrementing by part, for example
you may bump the minor part of '1.2.3' yielding '1.3.0').
Four version schemes are included:
* **Simple3VersionScheme** which supports 3 numerical part versions (A.B.C where A, B, and C are integers)
* **Simple4VersionScheme** which supports 4 numerical part versions (A.B.C.D where A, B, C, and D are integers)
* **Pep440VersionScheme** which supports PEP 440 (http://www.python.org/dev/peps/pep-0440/) versions
(N[.N]+[{a|b|c|rc}N][.postN][.devN][+local])
* **PerlVersionScheme** which supports 2 numerical part versions where the second part is at least two digits
(A.BB where A and B are integers and B is zero padded on the left. For example: 1.02, 1.34, 1.567)
If you don't specify which version scheme the version instance uses, then it will use the first scheme from the
**SupportedVersionSchemes** list that successfully parses the version string
By default, **Pep440VersionScheme** is the supported scheme. To change to a different list of schemes, use the
**Version.set_supported_version_schemes(schemes)**. For example::
from versio.version_scheme import Simple3VersionScheme, PerlVersionScheme
Version.set_supported_version_schemes([Simple3VersionScheme, PerlVersionScheme])
In addition, you may define your own version scheme by creating a new VersionScheme instance.
The VersionScheme class defines the version scheme.
A version scheme consists of:
* a name,
* a regular expression used to parse the version string,
* the regular expression flags to use (mainly to allow verbose regexes),
* a format string used to reassemble the parsed version into a string,
* an optional list of field types (if not specified, assumes all fields are strings),
* a list of field names used for accessing the components of the version.
* an optional subfield dictionary with the key being a field name, and the value being a list of sub-field names.
For example, in the **Pep440VersionScheme**, the "Release" field may contain multiple parts, so we use
subfield names for the parts. Say we have a version of "1.2.3rc1", the "1.2.3" is the release field, then
"1" is the "major" subfield, "2" is the "minor" subfield, and "3" is the "tiny" subfield.
* a "clear" value used to set the field values to the right of the field being bumped,
* a sequence dictionary where the keys are the field names, and the values are a list of allowed values.
The list must be in bump order. Bumping the last value in the list has no effect.
Note, you need to manually maintain consistency between the regular expression,
the format string, the optional field types, and the fields list. For example,
if your version scheme has N parts, then the regular expression should match
into N groups, the format string should expect N arguments to the str.format()
method, and there must be N unique names in the fields list.
### Installation
From pypi::
pip install Versio
### Usage
First let's just play with the comparing and bumping versions::
>>> from versio.version import Version
>>> from versio.version_scheme import Pep440VersionScheme
>>> v1 = Version('1.2.3rc4.post5.dev6', scheme=Pep440VersionScheme)
>>> v2 = Version('1.2.3rc4.post5.dev7', scheme=Pep440VersionScheme)
>>> v1 == v2
False
>>> v1 < v2
True
>>> v1.bump('dev')
True
>>> str(v1)
'1.2.3rc4.post5.dev7'
>>> v1 == v2
True
>>> v1.bump('pre')
True
Now let's look in the PEP 440 scheme::
>>> Pep440VersionScheme.fields
['release', 'pre', 'post', 'dev', 'local']
>>> Pep440VersionScheme.format_str
'{0}{1}{2}{3}{4}'
The fields are used by the **bump(field)** method in the above example. We skipped bumping the release above so let's
do it here::
>>> v1 = Version('1.2.3rc4.post5.dev6', scheme=Pep440VersionScheme)
>>> str(v1)
'1.2.3rc4.post5.dev6'
>>> v1.bump('release')
True
>>> str(v1)
'1.2.4'
For PEP 440, the release part is defined as "N[.N]+". We can bump specific parts of the release by using an
index like::
>>> v1.bump('release', 2)
True
>>> str(v1)
'1.2.5'
>>> v1.bump('release', 1)
True
>>> str(v1)
'1.3.0'
>>> v1.bump('release', 0)
True
>>> str(v1)
'2.0.0'
To use a name directly, we use the concept of subfields which are mapped to a field/index pair::
>>> Pep440VersionScheme.subfields
{'tiny2': ['Release', 3], 'major': ['Release', 0], 'tiny': ['Release', 2], 'minor': ['Release', 1]}
>>> v1 = Version('1.2.3rc4.post5.dev6', scheme=Pep440VersionScheme)
>>> str(v1)
'1.2.3rc4.post5.dev6'
>>> v1.bump('tiny')
True
>>> str(v1)
'1.2.4'
>>> v1.bump('minor')
True
>>> str(v1)
'1.3.0'
>>> v1.bump('major')
True
>>> str(v1)
'2.0.0'
Now that you've seen the version scheme in action, let's take a look at how it is defined::
Pep440VersionScheme = VersionScheme(name="pep440",
parse_regex=r"""
^
(\d[\.\d]*(?<= \d))
((?:[abc]|rc)\d+)?
(?:(\.post\d+))?
(?:(\.dev\d+))?
(?:(\+(?![.])[a-zA-Z0-9\.]*[a-zA-Z0-9]))?
$
""",
compare_order=[0, 1, 2, 3, 4],
compare_fill=['~', '~', '', '~', ''],
parse_flags=re.VERBOSE,
clear_value=None,
format_str='{0}{1}{2}{3}{4}',
fields=['Release', 'Pre', 'Post', 'Dev', 'Local'],
subfields={'Release': ['Major', 'Minor', 'Tiny', 'Tiny2']},
sequences={'Pre': ['a', 'b', 'c', 'rc'],
'Post': ['.post'],
'Dev': ['.dev'],
'Local': ['+']},
description=dedent("""\
PEP 440
Public version identifiers MUST comply with the following scheme:
N[.N]+[{a|b|c|rc}N][.postN][.devN][+local]
Public version identifiers MUST NOT include leading or trailing whitespace.
Public version identifiers MUST be unique within a given distribution.
Public version identifiers are separated into up to five segments:
Release segment: N[.N]+
Pre-release segment: {a|b|c|rc}N
Post-release segment: .postN
Development release segment: .devN
Local release segment: +local
The local version labels MUST be limited to the following set of permitted
characters:
ASCII letters ( [a-zA-Z] )
ASCII digits ( [0-9] )
periods ( . )
Local version labels MUST start and end with an ASCII letter or digit.
"""))
The **parse_regex** and **parse_flags** do what you think by parsing a string into a list containing regex groups,
except the group list is zero indexed to the first matching group.
The **format_str** and **format_types** control how the version is converted to a string in **__str__()**. Basically
**format_str.format(*args)** is called where the args is a list built by casting each of the version's groups using
the corresponding type from the **format_types** list. If you don't specify a **format_types**, then each group
is cast as a str.
The **clear_value** typically should be '0' for numeric versions and None for non-numeric. Basically it specifies
what to put in the groups to the right of the group being bumped.
The **sequences** dictionary maps text to prepend to a group when formatting. The dictionary keys must be in the
**fields** list. To progress through the sequence, bump the field with an index of 0. An index of 1 bumps the numeric
part of the group. For example::
>>> v1 = Version('1.2.3a4.post5.dev6', scheme=Pep440VersionScheme)
>>> str(v1)
'1.2.3a4.post5.dev6'
>>> v1.bump('pre', 0)
True
>>> str(v1)
'1.2.3b1'
>>> v1.bump('pre', 1)
True
>>> str(v1)
'1.2.3b2'
>>> v1.bump('pre', 0)
True
>>> str(v1)
'1.2.3c1'
>>> v1.bump('pre', 0)
True
>>> str(v1)
'1.2.3rc1'
>>> v1.bump('pre', 0)
False
>>> str(v1)
'1.2.3rc1'
Notice that bumping fails at the end of the sequence, and the version is not changed. You can override this behavior
by setting the "promote" argument to True, resulting in the field being removed at the end of the field's sequence.
For example:
>>> v1 = Version('1.2.3rc1', scheme=Pep440VersionScheme)
>>> str(v1)
'1.2.3rc1'
>>> v1.bump('pre', 0)
False
>>> str(v1)
'1.2.3rc1'
>>> v1.bump('pre', 0, promote=True)
True
>>> str(v1)
'1.2.3'
That's it.
There are more examples in *tests/version_test.py*. You may test directly with *py.test* or against multiple
python versions with *tox*.
Enjoy!