# Reference

## Module-level functions

semantic_version.compare(v1, v2)

  Compare two version strings, and return a result similar to that of `cmp()`:

      >>> compare('0.1.1', '0.1.2')
      -1
      >>> compare('0.1.1', '0.1.1')
      0
      >>> compare('0.1.1', '0.1.1-alpha')
      1

  Parameters:

    - v1 (str) – The first version to compare

    - v2 (str) – The second version to compare

  Raises:

    `ValueError`, if any version string is invalid

  Return type:

    `int`, -1 / 0 / 1 as for a `cmp()` comparison; `NotImplemented` if versions only differ by build metadata

Warning

Since build metadata has no ordering, `compare(Version('0.1.1'), Version('0.1.1+3'))` returns `NotImplemented`

semantic_version.match(spec, version)

  Check whether a version string matches a specification string:

      >>> match('>=0.1.1', '0.1.2')
      True
      >>> match('>=0.1.1', '0.1.1-alpha')
      False
      >>> match('~0.1.1', '0.1.1-alpha')
      True

  Parameters:

    - spec (str) – The specification to use, as a string

    - version (str) – The version string to test against the spec

  Raises:

    `ValueError`, if the `spec` or the `version` is invalid

  Return type:

    `bool`

semantic_version.validate(version)

  Check whether a version string complies with the SemVer rules.

      >>> semantic_version.validate('1.1.1')
      True
      >>> semantic_version.validate('1.2.3a4')
      False

  Parameters:

    version (str) – The version string to validate

  Return type:

    `bool`

## Representing a version (the Version class)

class semantic_version.Version(version_string[, partial=False])

  Object representation of a SemVer-compliant version.

  Constructed from a textual version string:

      >>> Version('1.1.1')
      Version('1.1.1')
      >>> str(Version('1.1.1'))
      '1.1.1'

class semantic_version.Version(major: int, minor: int, patch: int, prereleases: tuple, build: tuple[, partial=False])

  Constructed from named components:

  >     >>> Version(major=1, minor=2, patch=3)
  >     Version('1.2.3')

  Attributes

  major

    `int`, the major version number

  minor

    `int`, the minor version number.

    May be `None` for a `partial` version number in a `<major>` format.

  patch

    `int`, the patch version number.

    May be `None` for a `partial` version number in a `<major>` or `<major>.<minor>` format.

  prerelease

    `tuple` of `strings`, the prerelease component.

    It contains the various dot-separated identifiers in the prerelease component.

    May be `None` for a `partial` version number in a `<major>`, `<major>.<minor>` or `<major>.<minor>.<patch>` format.

  build

    `tuple` of `strings`, the build metadata.

    It contains the various dot-separated identifiers in the build metadata.

    May be `None` for a `partial` version number in a `<major>`, `<major>.<minor>`, `<major>.<minor>.<patch>` or `<major>.<minor>.<patch>-<prerelease>` format.

  precedence_key

    Read-only attribute; suited for use in `sort(versions, key=lambda v: v.precedence_key)`. The actual value of the attribute is considered an implementation detail; the only guarantee is that ordering versions by their precedence_key will comply with semver precedence rules.

    Warning

    Changed in version 2.10.0.

    The `build` is included in the precedence_key computation, but only for ordering stability. The only guarantee is that, for a given release of python-semanticversion, two versions’ `precedence_key` will always compare in the same direction if they include build metadata; that ordering is an implementation detail and shouldn’t be relied upon.

  partial

    `bool`, whether this is a ‘partial’ or a complete version number. Partial version number may lack `minor` or `patch` version numbers.

    Deprecated since version 2.7: The ability to define a partial version will be removed in version 3.0. Use `SimpleSpec` instead: `SimpleSpec('1.x.x')`.

  Methods

  next_major(self)

    Return the next major version, i.e the smallest version strictly greater than the current one with minor and patch set to 0 and no prerelease/build.

        >>> Version('1.0.2').next_major()
        Version('2.0.0')
        >>> Version('1.0.0+b3').next_major()
        Version('2.0.0')
        >>> Version('1.0.0-alpha').next_major()
        Version('1.0.0')

  next_minor(self)

    Return the next minor version, i.e the smallest version strictly greater than the current one, with a patch level of `0`.

        >>> Version('1.0.2').next_minor()
        Version('1.1.0')
        >>> Version('1.0.0+b3').next_minor()
        Version('1.1.0')
        >>> Version('1.1.2-alpha').next_minor()
        Version('1.2.0')
        >>> Version('1.1.0-alpha').next_minor()
        Version('1.1.0')

  next_patch(self)

    Return the next patch version, i.e the smallest version strictly greater than the current one with empty `prerelease` and `build`.

        >>> Version('1.0.2').next_patch()
        Version('1.0.3')
        >>> Version('1.0.2+b3').next_patch()
        Version('1.0.3')
        >>> Version('1.0.2-alpha').next_patch()
        Version('1.0.2')

    Warning

    The next patch version of a version with a non-empty `prerelease` is the version without that `prerelease` component: it’s the smallest “pure” patch version strictly greater than that version.

  truncate(self, level='patch']):

    Returns a similar level, but truncated at the provided level.

        >>> Version('1.0.2-rc1+b43.24').truncate()
        Version('1.0.2')
        >>> Version('1.0.2-rc1+b43.24').truncate('minor')
        Version('1.0.0')
        >>> Version('1.0.2-rc1+b43.24').truncate('prerelease')
        Version('1.0.2-rc1')

  __iter__(self)

    Iterates over the version components (`major`, `minor`, `patch`, `prerelease`, `build`):

        >>> list(Version('0.1.1'))
        [0, 1, 1, [], []]

    Note

    This may pose some subtle bugs when iterating over a single version while expecting an iterable of versions – similar to:

        >>> list('abc')
        ['a', 'b', 'c']
        >>> list(('abc',))
        ['abc']

  __cmp__(self, other)

    Provides comparison methods with other `Version` objects.

    The rules are:

    - For non-`partial` versions, compare using the SemVer scheme

    - If any compared object is `partial`:

      > - Begin comparison using the SemVer scheme

      > - If a component (`minor`, `patch`, `prerelease` or `build`) was absent from the `partial` `Version` – represented with `None` –, consider both versions equal.

      > For instance, `Version('1.0', partial=True)` means “any version beginning in `1.0`”.

      > `Version('1.0.1-alpha', partial=True)` means “The `1.0.1-alpha` version or any any release differing only in build metadata”: `1.0.1-alpha+build3` matches, `1.0.1-alpha.2` doesn’t.

    Examples:

        >>> Version('1.0', partial=True) == Version('1.0.1')
        True
        >>> Version('1.0.1-rc1.1') == Version('1.0.1-rc1', partial=True)
        False
        >>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1')
        False
        >>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1', partial=True)
        True

  __str__(self)

    Returns the standard text representation of the version:

        >>> v = Version('0.1.1-rc2+build4.4')
        >>> v
        Version('0.1.1-rc2+build4.4')
        >>> str(v)
        '0.1.1-rc2+build4.4'

  __hash__(self)

    Provides a hash based solely on the components.

    Allows using a `Version` as a dictionary key.

    Note

    A fully qualified `partial` `Version`

    (up to the `build` component) will hash the same as the equally qualified, non-`partial` `Version`:

        >>> hash(Version('1.0.1+build4')) == hash(Version('1.0.1+build4', partial=True))
        True

  Class methods

  classmethod parse(cls, version_string[, partial=False])

    Parse a version string into a `(major, minor, patch, prerelease, build)` tuple.

    Parameters:

      - version_string (str) – The version string to parse

      - partial (bool) – Whether this should be considered a `partial` version

    Raises:

      `ValueError`, if the `version_string` is invalid.

    Return type:

      (major, minor, patch, prerelease, build)

  classmethod coerce(cls, version_string[, partial=False])

    Try to convert an arbitrary version string into a `Version` instance.

    Rules are:

    - If no minor or patch component, and `partial` is `False`, replace them with zeroes

    - Any character outside of `a-zA-Z0-9.+-` is replaced with a `-`

    - If more than 3 dot-separated numerical components, everything from the fourth component belongs to the `build` part

    - Any extra `+` in the `build` part will be replaced with dots

    Examples:

        >>> Version.coerce('02')
        Version('2.0.0')
        >>> Version.coerce('1.2.3.4')
        Version('1.2.3+4')
        >>> Version.coerce('1.2.3.4beta2')
        Version('1.2.3+4beta2')
        >>> Version.coerce('1.2.3.4.5_6/7+8+9+10')
        Version('1.2.3+4.5-6-7.8.9.10')

    Parameters:

      - version_string (str) – The version string to coerce

      - partial (bool) – Whether to allow generating a `partial` version

    Raises:

      `ValueError`, if the `version_string` is invalid.

    Return type:

      `Version`

## Version specifications (the Spec class)

The SemVer specification doesn’t provide a standard description of version ranges. And simply using a naive implementation leads to unexpected situations: `>=1.2.0,<1.3.0` isn’t expected to match version `1.3.0-rc.1`, yet a strict application of SemVer precedence rules would include it.

In order to solve this problem, each SemVer-based package management platform has designed its own rules. python-semanticversion provides a couple of implementations of those range definition syntaxes:

- `'simple'` (through `SimpleSpec`): A python-semanticversion specific syntax, which supports simple / intuitive patterns, and some NPM-inspired extensions;

- `'npm'` (through `NpmSpec`): The NPM syntax, based on https://github.com/npm/node-semver#ranges

- More might be added in the future.

Each of those `Spec` classes provides a shared set of methods to work with versions:

class semantic_version.BaseSpec(spec_string)

  Converts an expression describing a range of versions into a set of clauses, and matches any `Version` against those clauses.

  Attributes

  This class has no public attributes.

  Methods

  match(self, version)

    Test whether a given `Version` matches all included `SpecItem`:

        >>> Spec('>=1.1.0,<1.1.2').match(Version('1.1.1'))
        True

    Parameters:

      version (`Version`) – The version to test against the specs

    Return type:

      `bool`

  filter(self, versions)

    Extract all compatible `versions` from an iterable of `Version` objects.

    Parameters:

      versions (iterable of `Version`) – The versions to filter

    Yield:

      `Version`

  select(self, versions)

    Select the highest compatible version from an iterable of `Version` objects.

        >>> s = Spec('>=0.1.0')
        >>> s.select([])
        None
        >>> s.select([Version('0.1.0'), Version('0.1.3'), Version('0.1.1')])
        Version('0.1.3')

    Parameters:

      versions (iterable of `Version`) – The versions to filter

    Return type:

      The highest compatible `Version` if at least one of the given versions is compatible; `None` otherwise.

  __contains__(self, version)

    Alias of the `match()` method; allows the use of the `version in speclist` syntax:

        >>> Version('1.1.1-alpha') in Spec('>=1.1.0,<1.1.1')
        True

  __str__(self)

    Converting a `Spec` returns the initial description string:

        >>> str(Spec('>=0.1.1,!=0.1.2'))
        '>=0.1.1,!=0.1.2'

  __hash__(self)

    Provides a hash based solely on the hash of contained specs.

    Allows using a `Spec` as a dictionary key.

  Class methods

  classmethod parse(self, expression, syntax='simple')

    Retrieve a `BaseSpec` object tuple from a string.

    Parameters:

      - requirement_string (str) – The textual description of the specifications

      - syntax (str) – The identifier of the syntax to use for parsing

    Raises:

      `ValueError`: if the `requirement_string` is invalid.

    Return type:

      `BaseSpec` subclass

    Changed in version 2.7: This method used to return a tuple of `SpecItem` objects.

class semantic_version.SimpleSpec(spec_string)

  Added in version 2.7: Previously reachable through `Spec`.

  Applies the python-semanticversion range specification:

  - A specification of `<1.3.4` is not expected to allow `1.3.4-rc2`, but strict SemVer comparisons allow it ;

  - It may be necessary to exclude either all variations on a patch-level release (`!=1.3.3`) or specifically one build-level release (`1.3.3+build.434`).

  Specification structure:

  In order to have version specification behave naturally, the `SimpleSpec` syntax uses the following rules:

  - A specification expression is a list of clauses separated by a comma (`,`);

  - A version is matched by an expression if, and only if, it matches every clause in the expression;

  - A clause of `*` matches every valid version;

  Equality clauses

  - A clause of `==0.1.2` will match version `0.1.2` and any version differing only through its build number (`0.1.2+b42` matches);

  - A clause of `==0.1.2+b42` will only match that specific version: `0.1.2+b43` and `0.1.2` are excluded;

  - A clause of `==0.1.2+` will only match that specific version: `0.1.2+b42` is excluded;

  - A clause of `!=0.1.2` will prevent all versions with the same major/minor/patch combination: `0.1.2-rc.1` and `0.1.2+b42` are excluded’

  - A clause of `!=0.1.2-` will only prevent build variations of that version: `0.1.2-rc.1` is included, but not `0.1.2+b42`;

  - A clause of `!=0.1.2+` will exclude only that exact version: `0.1.2-rc.1` and `0.1.2+b42` are included;

  - Only a `==` or `!=` clause may contain build-level metadata: `==1.2.3+b42` is valid, `>=1.2.3+b42` isn’t.

  Comparison clauses

  - A clause of `<0.1.2` will match versions strictly below `0.1.2`, excluding prereleases of `0.1.2`: `0.1.2-rc.1` is excluded;

  - A clause of `<0.1.2-` will match versions strictly below `0.1.2`, including prereleases of `0.1.2`: `0.1.2-rc.1` is included;

  - A clause of `<0.1.2-rc.3` will match versions strictly below `0.1.2-rc.3`, including prereleases: `0.1.2-rc.2` is included;

  - A clause of `<=XXX` will match versions that match `<XXX` or `==XXX`

  - A clause of `>0.1.2` will match versions strictly above `0.1.2`, including all prereleases of `0.1.3`.

  - A clause of `>0.1.2-rc.3` will match versions strictly above `0.1.2-rc.3`, including matching prereleases of `0.1.2`: `0.1.2-rc.10` is included;

  - A clause of `>=XXX` will match versions that match `>XXX` or `==XXX`

  Wildcards

  - A clause of `==0.1.*` is equivalent to `>=0.1.0,<0.2.0`

  - A clause of `>=0.1.*` is equivalent to `>=0.1.0`

  - A clause of `==1.*` or `==1.*.*` is equivalent to `>=1.0.0,<2.0.0`

  - A clause of `>=1.*` or `>=1.*.*` is equivalent to `>=1.0.0`

  - A clause of `==*` maps to `>=0.0.0`

  - A clause of `>=*` maps to `>=0.0.0`

  Extensions

  Additionnally, python-semanticversion supports extensions from specific packaging platforms:

  PyPI-style compatible release clauses:

  > - `~=2.2` means “Any release between 2.2.0 and 3.0.0”

  > - `~=1.4.5` means “Any release between 1.4.5 and 1.5.0”

  NPM-style specs:

  > - `~1.2.3` means “Any release between 1.2.3 and 1.3.0”

  > - `^1.3.4` means “Any release between 1.3.4 and 2.0.0”

  Some examples:

      >>> Version('0.1.2-rc.1') in SimpleSpec('*')
      True
      >>> SimpleSpec('<0.1.2').filter([Version('0.1.2-rc.1'), Version('0.1.1'), Version('0.1.2+b42')])
      [Version('0.1.1')]
      >>> SimpleSpec('<0.1.2-').filter([Version('0.1.2-rc.1'), Version('0.1.1'), Version('0.1.2+b42')])
      [Version('0.1.2-rc.1'), Version('0.1.1')]
      >>> SimpleSpec('>=0.1.2,!=0.1.3,!=0.1.4-rc.1',!=0.1.5+b42).filter([
              Version('0.1.2'), Version('0.1.3'), Version('0.1.3-beta'),
              Version('0.1.4'), Version('0.1.5'), Version('0.1.5+b42'),
              Version('2.0.1-rc.1'),
          ])
      [Version('0.1.2'), Version('0.1.4'), Version('0.1.5'), Version('2.0.1-rc.1')]

class semantic_version.NpmSpec(spec_string)

  Added in version 2.7.

  A NPM-compliant version matching engine, based on the https://github.com/npm/node-semver#ranges specification.

      >>> Version('0.1.2') in NpmSpec('0.1.0-alpha.2 .. 0.2.4')
      True
      >>> Version('0.1.2') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')
      True
      >>> Version('2.3.4') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')
      True

class semantic_version.Spec(spec_string)

  Deprecated since version 2.7: The alias from `Spec` to `SimpleSpec` will be removed in 3.1.

  Alias to `LegacySpec`, for backwards compatibility.

class semantic_version.LegacySpec(spec_string)

  Deprecated since version 2.7: The `LegacySpec` class will be removed in 3.0; use `SimpleSpec` instead.

  A `LegacySpec` class has the exact same behaviour as `SimpleSpec`, with backwards-compatible features:

  It accepts version specifications passed in as separated arguments:

      >>> Spec('>=1.0.0', '<1.2.0', '!=1.1.4,!=1.1.13')
      <Spec: (
          <SpecItem: >= Version('1.0.0', partial=True)>,
          <SpecItem: < Version('1.2.0', partial=True)>,
          <SpecItem: != Version('1.1.4', partial=True)>,
          <SpecItem: != Version('1.1.13', partial=True)>,
      )>

  It keeps a list of `SpecItem` objects, based on the initial expression components.

  __iter__(self)

    Returns an iterator over the contained specs:

        >>> for spec in Spec('>=0.1.1,!=0.1.2'):
        ...     print spec
        >=0.1.1
        !=0.1.2

  Attributes

  specs

    Tuple of `SpecItem`, the included specifications.

class semantic_version.SpecItem(spec_string)

  Deprecated since version 2.7: This class will be removed in 3.0.

  Note

  This class belong to the private python-semanticversion API.

  Stores a version specification, defined from a string:

      >>> SpecItem('>=0.1.1')
      <SpecItem: >= Version('0.1.1', partial=True)>

  This allows to test `Version` objects against the `SpecItem`:

      >>> SpecItem('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release satisfy conditions
      True
      >>> Version('0.1.1+build2') in SpecItem('>=0.1.1')   # build metadata is ignored when checking for precedence
      True
      >>>
      >>> # Use the '-' marker to include the pre-release component in checks
      >>> SpecItem('>=0.1.1-').match(Version('0.1.1-rc1')
      False
      >>> # Use the '+' marker to include the build metadata in checks
      >>> SpecItem('==0.1.1+').match(Version('0.1.1+b1234')
      False
      >>>

  Attributes

  kind

    One of `KIND_LT`, `KIND_LTE`, `KIND_EQUAL`, `KIND_GTE`, `KIND_GT` and `KIND_NEQ`.

  spec

    `Version` in the `SpecItem` description.

    It is alway a `partial` `Version`.

  Class methods

  classmethod parse(cls, requirement_string)

    Retrieve a `(kind, version)` tuple from a string.

    Parameters:

      requirement_string (str) – The textual description of the specification

    Raises:

      `ValueError`: if the `requirement_string` is invalid.

    Return type:

      (`kind`, `version`) tuple

  Methods

  match(self, version)

    Test whether a given `Version` matches this `SpecItem`:

        >>> SpecItem('>=0.1.1').match(Version('0.1.1-alpha'))
        True
        >>> SpecItem('>=0.1.1-').match(Version('0.1.1-alpha'))
        False

    Parameters:

      version (`Version`) – The version to test against the spec

    Return type:

      `bool`

  __str__(self)

    Converting a `SpecItem` to a string returns the initial description string:

        >>> str(SpecItem('>=0.1.1'))
        '>=0.1.1'

  __hash__(self)

    Provides a hash based solely on the current kind and the specified version.

    Allows using a `SpecItem` as a dictionary key.

  Class attributes

  KIND_LT

    The kind of ‘Less than’ specifications:

        >>> Version('1.0.0-alpha') in Spec('<1.0.0')
        False

  KIND_LTE

    The kind of ‘Less or equal to’ specifications:

        >>> Version('1.0.0-alpha1+build999') in Spec('<=1.0.0-alpha1')
        True

  KIND_EQUAL

    The kind of ‘equal to’ specifications:

        >>> Version('1.0.0+build3.3') in Spec('==1.0.0')
        True

  KIND_GTE

    The kind of ‘Greater or equal to’ specifications:

        >>> Version('1.0.0') in Spec('>=1.0.0')
        True

  KIND_GT

    The kind of ‘Greater than’ specifications:

        >>> Version('1.0.0+build667') in Spec('>1.0.1')
        False

  KIND_NEQ

    The kind of ‘Not equal to’ specifications:

        >>> Version('1.0.1') in Spec('!=1.0.1')
        False

  KIND_COMPATIBLE

    The kind of compatible release clauses specifications:

        >>> Version('1.1.2') in Spec('~=1.1.0')
        True