Semantic Versioning Library

Warnings

• gotcha The library strictly adheres to Semantic Versioning 2.0.0. Attempting to parse or validate strings that do not conform to this specification will raise a `ValueError`.
  Fix: Ensure version strings are SemVer 2.0.0 compliant (e.g., '1.0.0', '1.2.3-alpha.1', '1.0.0+build.20230101'). Do not include a 'v' prefix.
• gotcha Build metadata (the part after `+`, e.g., `+build.123`) is ignored when determining version precedence. This means `Version('1.0.0+abc') == Version('1.0.0+xyz')` is `True`. The `compare()` function may return `NotImplemented` if versions only differ by build metadata.
  Fix: Be aware that build metadata is purely for informational purposes and does not affect the order or equality of versions. If distinct versions are needed, ensure differences are in major, minor, patch, or pre-release components.
• gotcha Pre-release identifiers (the part after `-`, e.g., `-alpha`) are compared lexicographically as ASCII strings, not numerically. Also, pre-release versions have lower precedence than their corresponding release version (e.g., `1.0.0-alpha < 1.0.0`).
  Fix: Understand that '1.0.0-alpha.1' comes before '1.0.0-alpha.2', but '1.0.0-beta' comes after '1.0.0-alpha' due to ASCII sorting. Case also matters (e.g., '1.0.0-alpha' < '1.0.0-Beta').
• gotcha Using `Version(version_string, partial=True)` alters comparison behavior. If a component (minor, patch, prerelease, or build) was absent from the partial Version (represented with `None`), it is considered equal for comparison purposes. For instance, `Version('1.0', partial=True)` means 'any version beginning with 1.0'.
  Fix: Only use `partial=True` when intentionally desiring this flexible comparison behavior for incomplete version strings, such as matching a major.minor prefix.
• gotcha The `SimpleSpec` and `NpmSpec` classes implement different version range specification schemes. `SimpleSpec` is intuitive and inspired by PyPI, while `NpmSpec` strictly follows NPM's complex rules (e.g., `~` and `^` operators have specific meanings).
  Fix: Choose the appropriate `Spec` class based on the desired range syntax. Familiarize yourself with the specifics of `NpmSpec` if integrating with systems that use NPM-style version ranges.

Install

• pip install semantic-version Install from PyPI

Imports

• Version

  from semantic_version import Version

• SimpleSpec

  from semantic_version import SimpleSpec

  Used for simple, PyPI-inspired version range specifications.
• NpmSpec

  from semantic_version import NpmSpec

  Used for NPM-style version range specifications.
• compare, match, validate

  from semantic_version import compare, match, validate

  Module-level functions for version comparison, specification matching, and validation.

Quickstart

This example demonstrates how to create Version objects, access their components, perform comparisons, and use SimpleSpec to check if a version falls within a specified range.

from semantic_version import Version, SimpleSpec

# Create a Version object
v = Version('1.2.3-alpha+build.123')
print(f"Version: {v}")
print(f"Major: {v.major}, Minor: {v.minor}, Patch: {v.patch}")
print(f"Prerelease: {v.prerelease}, Build: {v.build}")

# Compare versions
v1 = Version('1.0.0')
v2 = Version('1.0.1')
print(f"Is {v1} < {v2}? {v1 < v2}")

# Define and use a SimpleSpec
spec = SimpleSpec('>=1.0.0,<2.0.0')
print(f"Does {v1} match spec '>1.0.0,<2.0.0'? {v1 in spec}")
print(f"Does {v2} match spec '>1.0.0,<2.0.0'? {v2 in spec}")
print(f"Does Version('2.0.0') match spec '>1.0.0,<2.0.0'? {Version('2.0.0') in spec}")