Tools/Scripts/webkitpy/python24/versioning.py

# Copyright (C) 2010 Chris Jerdonek (cjerdonek@webkit.org)
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1.  Redistributions of source code must retain the above copyright
#     notice, this list of conditions and the following disclaimer.
# 2.  Redistributions in binary form must reproduce the above copyright
#     notice, this list of conditions and the following disclaimer in the
#     documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS'' AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

"""Supports Python version checking."""

import logging
import sys

_log = logging.getLogger("webkitpy.python24.versioning")

# The minimum Python version the webkitpy package supports.
_MINIMUM_SUPPORTED_PYTHON_VERSION = "2.5"


def compare_version(sysmodule=None, target_version=None):
    """Compare the current Python version with a target version.

    Args:
      sysmodule: An object with version and version_info data attributes
                 used to detect the current Python version.  The attributes
                 should have the same semantics as sys.version and
                 sys.version_info.  This parameter should only be used
                 for unit testing.  Defaults to sys.
      target_version: A string representing the Python version to compare
                      the current version against.  The string should have
                      one of the following three forms: 2, 2.5, or 2.5.3.
                      Defaults to the minimum version that the webkitpy
                      package supports.

    Returns:
      A triple of (comparison, current_version, target_version).

      comparison: An integer representing the result of comparing the
                  current version with the target version.  A positive
                  number means the current version is greater than the
                  target, 0 means they are the same, and a negative number
                  means the current version is less than the target.
                      This method compares version information only up
                  to the precision of the given target version.  For
                  example, if the target version is 2.6 and the current
                  version is 2.5.3, this method uses 2.5 for the purposes
                  of comparing with the target.
      current_version: A string representing the current Python version, for
                       example 2.5.3.
      target_version: A string representing the version that the current
                      version was compared against, for example 2.5.

    """
    if sysmodule is None:
        sysmodule = sys
    if target_version is None:
        target_version = _MINIMUM_SUPPORTED_PYTHON_VERSION

    # The number of version parts to compare.
    precision = len(target_version.split("."))

    # We use sys.version_info rather than sys.version since its first
    # three elements are guaranteed to be integers.
    current_version_info_to_compare = sysmodule.version_info[:precision]
    # Convert integers to strings.
    current_version_info_to_compare = map(str, current_version_info_to_compare)
    current_version_to_compare = ".".join(current_version_info_to_compare)

    # Compare version strings lexicographically.
    if current_version_to_compare > target_version:
        comparison = 1
    elif current_version_to_compare == target_version:
        comparison = 0
    else:
        comparison = -1

    # The version number portion of the current version string, for
    # example "2.6.4".
    current_version = sysmodule.version.split()[0]

    return (comparison, current_version, target_version)


# FIXME: Add a logging level parameter to allow the version message
#        to be logged at levels other than WARNING, for example CRITICAL.
def check_version(log=None, sysmodule=None, target_version=None):
    """Check the current Python version against a target version.

    Logs a warning message if the current version is less than the
    target version.

    Args:
      log: A logging.logger instance to use when logging the version warning.
           Defaults to the logger of this module.
      sysmodule: See the compare_version() docstring.
      target_version: See the compare_version() docstring.

    Returns:
      A boolean value of whether the current version is greater than
      or equal to the target version.

    """
    if log is None:
        log = _log

    (comparison, current_version, target_version) = \
        compare_version(sysmodule, target_version)

    if comparison >= 0:
        # Then the current version is at least the minimum version.
        return True

    message = ("WebKit Python scripts do not support your current Python "
               "version (%s).  The minimum supported version is %s.\n"
               "  See the following page to upgrade your Python version:\n\n"
               "    http://trac.webkit.org/wiki/PythonGuidelines\n"
               % (current_version, target_version))
    log.warn(message)
    return False