Skip to main content

A mostly universal library to parse and compare software package versions and version ranges. A companion to Package URLs.

Project description

univers: mostly universal version and version ranges comparison and conversion

Build Status License Python 3.6+

univers was born out of the need for a mostly universal way to store version ranges and to compare two software package versions in VulnerableCode.

Package version ranges and version constraints are useful and essential:

  • When relating a known vulnerability or bug to a range of affected package versions. For instance a statement such as “vulnerability 123 affects package bar, version 3.1 and version 4.2 but not version 5” defines a range of bar versions affected by a vulnerability.

  • When resolving the dependencies of a package to express which subset of the versions are supported. For instance a dependency requirement statement such as “I require package foo, version 2.0 and later versions” defines a range of acceptable foo versions.

Version syntaxes and range notations are quite different across ecosystems, making it is difficult to process versions and version ranges across ecosystems in a consistent way.

Existing tools and libraries typically support a single algorithms to parse and compare versions with a single version range notation for a single package ecosystem.

univers is different:

  • It tracks each ecosystem versioning scheme and how two versions are compared.

  • It support a growing number of package ecosystems versioning in a single library.

  • It can parse version range strings using their native notation (such as an npm range) into the common “vers” notation and internal object model and can return back a native version range string rebuilt from a “vers” range.

  • It is designed to work with Package URLs (purl).

How does univers work ?

univers wraps, embeds and implements multiple version comparison libraries, each focused on a specific ecosystem versioning scheme.

For each scheme, univers provides an implementation for:

  • the version comparison procedure e.g, how to compare two versions,

  • parsing and converting from a native version range notation to the univers normalized and unified internal model,

  • converting a range back to its scheme-native range syntax and to the vers syntax.

univers implements vers, an experimental unified and mostly universal version range syntax. It can parse and convert an existing native version range strings to this unified syntax. For example, this means:

  • converting “>=1.2.3” as used in a Python package into vers:pypi/>=1.2.3,

  • or converting “^1.0.2” as used in an npm package dependency declaration into vers:npm/>=1.0.2|<2.0.0

The supported package ecosystems versioning schemes and underlying libraries include:

  • npm that use the “node-semver” ranges notation and the semver versions syntax This is supported in part by the semantic_version library.

  • pypi: handled by Python’s packaging library and the standard packaging.version module.

  • Rubygems which use a semver-like but not-quite-semver scheme and there can be commonly more than three version segments. Gems also use a slightly different range notation from node-semver with different operators and slightly different semantics: for instance it uses “~>” as a pessimistic operator and supports exclusion with != and does not support “OR” between constraints (that it call requirements). Gem are handled by Python port of the Rubygems requirements and version handling code from the puppeteer tool

  • debian: handled by the debian-inspector library.

  • maven: handled by the embedded pymaven library.

  • rpm: handled by the embedded rpm_vercmp library.

  • golang (using semver)

  • PHP composer

  • ebuild/gentoo: handled by the embedded gentoo_vercmp module.

  • arch linux: handled by the embedded arch utility module borrowed from msys2.

  • Alpine linux: handled using the base Gentoo version support and extras specific to Alpine.

The level of support for each ecosystem may not be even for now and new schemes and support for more package types are implemented on a continuous basis.

Alternative

Rather than using ecosystem-specific version schemes and code, another approach is to use a single procedure for all the versions as implemented in libversion. libversion works in the most common case but may not work correctly when a task that demand precise version comparisons such as for dependency resolution and vulnerability lookup where a “good enough” comparison accuracy is not acceptable. libversion does not handle version range notations.

Installation

$ pip install univers

Examples

Compare two native Python versions:

from univers.versions import PypiVersion
assert PypiVersion("1.2.3") < PypiVersion("1.2.4")

Normalize a version range from an npm:

from univers.version_range import NpmVersionRange
range = NpmVersionRange.from_native("^1.0.2")
assert str(range) == "vers:npm/>=1.0.2|<2.0.0"

Test if a version is within or outside a version range:

from univers.versions import PypiVersion
from univers.version_range import VersionRange

range = VersionRange.from_string("vers:pypi/>=1.2.4")

assert PypiVersion("1.2.4") in range
assert PypiVersion("1.2.3") not in range

Development

Run these commands, starting from a git clone of https://github.com/nexB/univers

$ ./configure --dev
$ source venv/bin/active
$ pytest -vvs

We use the same development process as other AboutCode projects.

Visit https://github.com/nexB/univers and https://gitter.im/aboutcode-org/vulnerablecode and https://gitter.im/aboutcode-org/aboutcode for support and chat.

Primary license: Apache-2.0 SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause AND MIT

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

univers-30.5.0.tar.gz (163.1 kB view details)

Uploaded Source

Built Distribution

univers-30.5.0-py3-none-any.whl (77.3 kB view details)

Uploaded Python 3

File details

Details for the file univers-30.5.0.tar.gz.

File metadata

  • Download URL: univers-30.5.0.tar.gz
  • Upload date:
  • Size: 163.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.0 CPython/3.9.12

File hashes

Hashes for univers-30.5.0.tar.gz
Algorithm Hash digest
SHA256 d06fbd362eda4c8de493b3e4a22386aa94c632a195c9f14ab87bf968899a0ad6
MD5 5bca7ca3941e21b2c1a0a3c8529ceda7
BLAKE2b-256 0d3c6c060b3efc72dc6f9d649950874d0d5bbfd2bb42fefbfb5fe12c63550fc2

See more details on using hashes here.

Provenance

File details

Details for the file univers-30.5.0-py3-none-any.whl.

File metadata

  • Download URL: univers-30.5.0-py3-none-any.whl
  • Upload date:
  • Size: 77.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.0 CPython/3.9.12

File hashes

Hashes for univers-30.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7d41b8235481312b8e525ca98e876759d1bf299936e404ec454b9346af2eab4d
MD5 88b40c1d29fc2949905ea51c327f80c9
BLAKE2b-256 6a104e7bdb8da9bc4b1a010b3228ed5697ee86cd3cd4c592e2f2c7f6190a12e3

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page