version-filter 0.7.3

A semantic and regex version filtering/masking library.

version-filter

A semantic and regex version filtering/masking library.

Given a filtering mask or regex and a list of versions (as strings), a subset of that list of versions will be returned. If a mask is given and the mask uses current version references, an explicit current version must also be provided as an imput must also be provided as an imput.

Inputs

Mask/Regex

The Mask can be a SemVer v2 valid mask with the following extensions.

Mask Lock Extension

Locks (L) are used as a substitution character in the mask for the major, minor and patch components where you want to limit the version filter to just those versions where it has the same value as the given current_version. If a L is present anywhere in the mask, a current_version parameter must also be provided. By giving a positive integer immediately following the ‘L’ you can express “lock + int” behavior. For example, L1 in a mask states “the current version number + 1” for any given position.

Mask Yes Extension

Yes (Y) are used to provide wildcard acceptance of any value in the position of the Y. It can be used in the major, minor, patch or pre-release components of version’

‘Next Best’ Matching Extension

Some packages fail to ever publicly release expected semantic versions. Take for instance a package that never releases a '2.0.0' version, but instead has '2.0.1' as the first available version of the 2 series. To be able to handle that convention deviation without resorting to ranges or wildcards and thus losing some of the power of the Lock and Yes extensions you can prefix a mask with the hyphen (-) character. This allows the algorithm to anticipate what releases “should” get released, and select the “next” release if the anticipated release never appears. For instance, the mask '-Y.0.0' anticipates that the '2.0.0' release will be made, but will return the 2.0.1 if the 2.0.0 release never appears.

Boolean AND and OR

Boolean AND operators (&&) and boolean OR operators (||) can be used to combine masks. However, both AND and OR cannot be combined in the same expression.

Mask Examples

Some common examples:

• '1.Y.0' # return only those minor versions that are of major release 1

• 'L.Y.0' # return only those minor versions that are greater than the currently installed version, but in the same major release

• '>=L1.0.0' # return every version for major versions at least 1 greater that the current major version

• '-Y.0.0' # return only major versions that are greater than the currently installed version with “next best” matching enabled (will return a 2.0.1 release if 2.0.0 is never released)

• 'L.L.Y' # return only those patch versions that are greater than the currently installed version, but in the same major and minor release

• 'Y.Y.Y' # return all major, minor and patch versions

• 'Y.Y.Y-Y' # return all major, minor, patch and prerelease versions

• 'L.L.Y || Y.Y.0' # return patch versions of my currently installed version or all major and minor releases

• '>1.0.0 && <3.0.0' # return all versions between 1.0.0 and 3.0.0, exclusive

• '*' # return all versions, including pre-releases

List of version strings

The list of version strings is expected to be a set of well formed semantic versions conforming to the SemVer v2 spec.

Current Version

A version string that conforms to the SemVer v2 spec.

Usage

from version_filter import VersionFilter

mask = 'L.Y.Y'
versions = ['1.8.0', '1.8.1', '1.8.2', '1.9.0', '1.9.1', '1.10.0', 'nightly']
current_version = '1.9.0'

VersionFilter.semver_filter(mask, versions, current_version)
# ['1.9.1', '1.10.0']

VersionFilter.regex_filter(r'^night', versions)
# ['nightly']

Resources

• Semver Specification

• NPM Semver Spec

• Yarn

• Dependencies.io Docs

License

• Free software: MIT license

Credits

• Paul Ortman

• Dave Gaeddert

History

0.7.3 (2018-02-09)

• Return the list of matched version in sorted form when doing semver filtering

• Strip _all_ leading ‘=’ and ‘v’ characters from version strings

0.7.2 (2018-01-31)

• Tighten up the restrictions for ‘*’ masks to only allow whitespace around the star

0.7.1 (2018-01-22)

• Add Semver validation method

0.7.0 (2018-01-16)

• Add support for “Last + N” matching in masks

0.6.0 (2018-01-08)

• Enable the “Next Best” matching algorithm to find next best releases when anticipated releases do not exist

0.5.1 (2017-12-09)

• Use forked version of python-semanticversion to get NPM consistent caret (^) matching behavior

0.5.0 (2017-07-19)

• Add support for pre-release locking and matching pre-releases by string

0.4.0 (2017-06-30)

• Do two-staging parsing of version strings to be more accurate and robust

• Fix a couple of documentation bugs with the package name vs project name

0.3.0 (2017-05-30)

• Accept (but ignore) version strings with leading ‘v’ or ‘=’ characters

0.2.0 (2017-05-24)

• Add support for pre-release versions

0.1.1 (2017-05-23)

• Fix some documentation

0.1.0 (2017-05-20)

• First release on PyPI.