Source code for irfpy.util.version

import warnings as _warnings

from packaging.version import Version as _version

from irfpy.util import exception as _ex

class VersionException(_ex.IrfpyException):
    def __init__(self, *args, **argv):
        _ex.IrfpyException.__init__(self, *args, **argv)


def requires(required_version, installed_version, package_name="unknown", error_message=None):
    """ Raises VersionException if installed version does not match.

    :param required_version: Required package version.
    :type required_version: String
    :param installed_version: Installed package version.
    :type installed_version: String
    :param package_name: Package name.  Used for error message.
    :param error_message: Error message to show.

    For typical use in library or your script:

    >>> from irfpy.util import __version__
    >>> requires('4.0.0', __version__, package_name='irfpy.util')    # One should use irfpy.util >4.0.0

    If the version does not match: 

    >>> installed_version = "4.0"
    >>> required_version = "5.0"

    >>> requires(required_version, installed_version, package_name="testpackage")  # doctest: +IGNORE_EXCEPTION_DETAIL
    Traceback (most recent call last):
    irfpy.util.version.VersionException: ...
    """

    ins = _version(installed_version)
    req = _version(required_version)

    if error_message is None:
        error_message = "Package {}: Version {} is required, but installed {}".format(package_name, required_version, installed_version)

    if ins < req:
        raise VersionException(error_message)


def recommends(recommended_version, installed_version, package_name="unknown", error_message=None):
    """ Warning message is shown if installed version does not match.

    :param recommended_version: Recommended package version, inclusive.
    :type recommended_version: String
    :param installed_version: Installed package version.
    :type installed_version: String
    :param package_name: Package name.  (Used for error message.)
    :param error_message: Error message to show.

    For typical use in library or your script:

    >>> import scipy
    >>> recommends('1.4.1', scipy.__version__, package_name='irfpy.util')    # scipy v1.4.1 or higher is recommended.

    If the version does not match:

    >>> installed_version = "4.0"
    >>> recommended_version = "5.0"

    >>> recommends(recommended_version, installed_version, package_name="testpackage")
    """
    ins = _version(installed_version)
    req = _version(recommended_version)

    if error_message is None:
        error_message = "Package {}: Version {} is recommended, but installed {}".format(package_name, recommended_version, installed_version)

    if ins < req:
        _warnings.warn(error_message)