2010-03-02  Chris Jerdonek  <cjerdonek@webkit.org>

        Reviewed by NOBODY (OOPS!).

        Started using the logging module in check-webkit-style.

        This provides more options for debugging and a more flexible,

        uniform way to report messages to the end-user.

        https://bugs.webkit.org/show_bug.cgi?id=35484

        Also included classes in a central location to facilitate

        the unit testing of logging code (setUp and tearDown of unit

        test logging configurations, etc).

        * Scripts/check-webkit-style:

          - Added a call to configure_logging() in the beginning of main().

          - Replaced two calls to sys.stderr.write() with appropriate

            logging calls.

        * Scripts/webkitpy/init/logtesting.py: Added.

          - Added a UnitTestLogStream class to capture log output

            during unit tests.

          - Added a UnitTestLog class that provides convenience methods

            for unit-testing logging code.

        * Scripts/webkitpy/style/checker.py:

          - Added a configure_logging() method.

          - Added a _LevelLoggingFilter class to filter out log messages

            above a certain logging level.

          - Removed the _stderr_write() method from the StyleChecker class

            and replaced its use with appropriate logging calls.

        * Scripts/webkitpy/style/checker_unittest.py:

          - Added a ConfigureLoggingTest class to unit test the

            configure_logging() method.

          - Updated the StyleCheckerCheckFileTest class as necessary.

        * Scripts/webkitpy/style_references.py:

          - Added references to logtesting.UnitTestLog and

            logtesting.UnitTestLogStream.

import logging

_log = logging.getLogger("check-webkit-style")

# 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 the unit-testing of logging."""

import logging

class UnitTestLogStream(object):

    """Represents a file-like object for unit-testing logging.

    This is meant for passing to the logging.StreamHandler constructor.

    """

    def __init__(self):

        self.messages = []

        """A list of log messages written to the stream."""

    def write(self, message):

        self.messages.append(message)

    def flush(self):

        pass

class UnitTestLog(object):

    """Supports unit-testing logging.

    Sample usage:

    # The following line should go in the setUp() method of a

    # unittest.TestCase.  In particular, self is a TestCase instance.

    self._log = UnitTestLog(self)

    # Call the following in a test method of a unittest.TestCase.

    log = logging.getLogger("webkitpy")

    log.info("message1")

    log.warn("message2")

    self._log.assertMessages(["INFO: message1\n",

                              "WARN: message2\n"])  # Should succeed.

    # The following line should go in the tearDown() method of

    # unittest.TestCase.

    self._log.tearDown()

    """

    def __init__(self, test_case, logging_level=None):

        """Configure unit test logging, and return an instance.

        This method configures the root logger to log to a testing

        log stream.  Only messages logged at or above the given level

        are logged to the stream.  Messages are formatted in the

        following way, for example--

        "INFO: This is a test log message."

        This method should normally be called in the setUp() method

        of a unittest.TestCase.

        Args:

          test_case: A unittest.TestCase instance.

          logging_level: A logging level.  Only messages logged at or

                         above this level are written to the testing

                         log stream.  Defaults to logging.INFO.

        """

        if logging_level is None:

            logging_level = logging.INFO

        stream = UnitTestLogStream()

        handler = logging.StreamHandler(stream)

        formatter = logging.Formatter("%(levelname)s: %(message)s")

        handler.setFormatter(formatter)

        logger = logging.getLogger()

        logger.setLevel(logging_level)

        logger.addHandler(handler)

        self._handler = handler

        self._messages = stream.messages

        self._test_case = test_case

    def _logger(self):

        """Return the root logger used for logging."""

        return logging.getLogger()

    def assertMessages(self, messages):

        """Assert that the given messages match the logged messages."""

        self._test_case.assertEquals(messages, self._messages)

    def tearDown(self):

        """Unconfigure unit test logging.

        This should normally be called in the tearDown method of a

        unittest.TestCase

        """

        logger = self._logger()

        logger.removeHandler(self._handler)

import logging

_log = logging.getLogger("webkitpy.style.checker")

# FIXME: Add support for more verbose logging for debug purposes.

#        This can use a formatter like the following, for example--

#

#        formatter = logging.Formatter("%(name)s: [%(levelname)s] %(message)s")

def configure_logging(stream):

    """Configure logging, and return the list of handlers added.

    Configures the root logger to log INFO messages and higher.

    Formats WARNING messages and above to display the logging level

    and messages strictly below WARNING not to display it.

    Returns:

      A list of references to the logging handlers added to the root

      logger.  This allows the caller to later remove the handlers

      using logger.removeHandler.  This is useful primarily during unit

      testing where the caller may want to configure logging temporarily

      and then undo the configuring.

    Args:

      stream: A file-like object to which to log.  The stream must

              define an "encoding" data attribute, or else logging

              raises an error.

    """

    # If the stream does not define an "encoding" data attribute, the

    # logging module can throw an error like the following:

    #

    # Traceback (most recent call last):

    #   File "/System/Library/Frameworks/Python.framework/Versions/2.6/...

    #         lib/python2.6/logging/__init__.py", line 761, in emit

    #     self.stream.write(fs % msg.encode(self.stream.encoding))

    # LookupError: unknown encoding: unknown

    # Handles logging.WARNING and above.

    error_handler = logging.StreamHandler(stream)

    error_handler.setLevel(logging.WARNING)

    formatter = logging.Formatter("%(levelname)s: %(message)s")

    error_handler.setFormatter(formatter)

    # Handles records strictly below logging.WARNING.

    non_error_handler = logging.StreamHandler(stream)

    non_error_filter = _LevelLoggingFilter(logging.WARNING)

    non_error_handler.addFilter(non_error_filter)

    formatter = logging.Formatter("%(message)s")

    non_error_handler.setFormatter(formatter)

    logger = logging.getLogger()

    logger.setLevel(logging.INFO)

    handlers = [error_handler, non_error_handler]

    for handler in handlers:

        logger.addHandler(handler)

    return handlers

# FIXME: Consider moving this class into a module in webkitpy.init after

#        getting more experience with its use.  We want to make sure

#        we have the right API before doing so.  For example, we may

#        want to provide a constructor that has both upper and lower

#        bounds, and not just an upper bound.

class _LevelLoggingFilter(object):

    """A logging filter for blocking records at or above a certain level."""

    def __init__(self, logging_level):

        """Create a _LevelLoggingFilter.

        Args:

          logging_level: The logging level cut-off.  Logging levels at

                         or above this level will not be logged.

        """

        self._logging_level = logging_level

    # The logging module requires that this method be defined.

    def filter(self, log_record):

        """Return whether given the LogRecord should be logged."""

        return log_record.levelno < self._logging_level

# FIXME: Remove the stderr_write attribute from this class and replace

#        its use with calls to a logging module logger.

        # FIXME: Make a CarriageReturnProcessor for this logic, and put

        #        it in processors.common.  The process() method should

        #        return the lines with the carriage returns stripped.

import logging

from ..style_references import UnitTestLog

from ..style_references import UnitTestLogStream

from checker import configure_logging

class ConfigureLoggingTest(unittest.TestCase):

    """Tests the configure_logging() function."""

    def setUp(self):

        log_stream = UnitTestLogStream()

        self._handlers = configure_logging(log_stream)

        self._log_stream = log_stream

    def tearDown(self):

        """Reset logging to its original state.

        This method ensures that the logging configuration set up

        for a unit test does not affect logging in other unit tests.

        """

        # This should be the same as the logger configured in the

        # configure_logging() method.

        logger = logging.getLogger()

        for handler in self._handlers:

            logger.removeHandler(handler)

    def _log(self):

        return logging.getLogger("webkitpy")

    def assert_log_messages(self, messages):

        """Assert that the logged messages equal the given messages."""

        self.assertEquals(messages, self._log_stream.messages)

    def test_warning_message(self):

        self._log().warn("test message")

        self.assert_log_messages(["WARNING: test message\n"])

    def test_below_warning_message(self):

        # We test the boundary case of a logging level equal to 29.

        # In practice, we will probably only be calling log.info(),

        # which corresponds to a logging level of 20.

        level = logging.WARNING - 1  # Equals 29.

        self._log().log(level, "test message")

        self.assert_log_messages(["test message\n"])

    def test_debug_message(self):

        self._log().debug("test message")

        self.assert_log_messages([])

    def test_two_messages(self):

        self._log().info("message1")

        self._log().info("message2")

        self.assert_log_messages(["message1\n", "message2\n"])

        self._log = UnitTestLog(self)

    def tearDown(self):

        self._log.tearDown()

from init.logtesting import UnitTestLog

from init.logtesting import UnitTestLogStream