simplify logging configuration

single default handler and formatter
don't remove handlers
configure level once using setLevel
document logging
reorganize logging tests

flask/logging.py

@@ -1,94 +1,69 @@
-# -*- coding: utf-8 -*-
-"""
-    flask.logging
-    ~~~~~~~~~~~~~
-
-    Implements the logging support for Flask.
-
-    :copyright: (c) 2015 by Armin Ronacher.
-    :license: BSD, see LICENSE for more details.
-"""
-
 from __future__ import absolute_import
 
+import logging
 import sys
 
 from werkzeug.local import LocalProxy
-from logging import getLogger, StreamHandler, Formatter, getLoggerClass, \
-     DEBUG, ERROR
-from .globals import _request_ctx_stack
 
-
-PROD_LOG_FORMAT = '[%(asctime)s] %(levelname)s in %(module)s: %(message)s'
-DEBUG_LOG_FORMAT = (
-    '-' * 80 + '\n' +
-    '%(levelname)s in %(module)s [%(pathname)s:%(lineno)d]:\n' +
-    '%(message)s\n' +
-    '-' * 80
-)
+from .globals import request
 
 
 @LocalProxy
-def _proxy_stream():
-    """Finds the most appropriate error stream for the application.  If a
-    WSGI request is in flight we log to wsgi.errors, otherwise this resolves
-    to sys.stderr.
+def wsgi_errors_stream():
+    """Find the most appropriate error stream for the application. If a request
+    is active, log to ``wsgi.errors``, otherwise use ``sys.stderr``.
+
+    If you configure your own :class:`logging.StreamHandler`, you may want to
+    use this for the stream. If you are using file or dict configuration and
+    can't import this directly, you can refer to it as
+    ``ext://flask.logging.wsgi_errors_stream``.
     """
-    ctx = _request_ctx_stack.top
-    if ctx is not None:
-        return ctx.request.environ['wsgi.errors']
-    return sys.stderr
+    return request.environ['wsgi.errors'] if request else sys.stderr
 
 
-def _should_log_for(app, mode):
-    policy = app.config['LOGGER_HANDLER_POLICY']
-    if policy == mode or policy == 'always':
-        return True
+def has_level_handler(logger):
+    """Check if there is a handler in the logging chain that will handle the
+    given logger's :meth:`effective level <~logging.Logger.getEffectiveLevel>`.
+    """
+    level = logger.getEffectiveLevel()
+    current = logger
+
+    while current:
+        if any(handler.level <= level for handler in current.handlers):
+            return True
+
+        if not current.propagate:
+            break
+
+        current = current.parent
+
     return False
 
 
+#: Log messages to :func:`~flask.logging.wsgi_errors_stream` with the format
+#: ``[%(asctime)s] %(levelname)s in %(module)s: %(message)s``.
+default_handler = logging.StreamHandler(wsgi_errors_stream)
+default_handler.setFormatter(logging.Formatter(
+    '[%(asctime)s] %(levelname)s in %(module)s: %(message)s'
+))
+
+
 def create_logger(app):
-    """Creates a logger for the given application.  This logger works
-    similar to a regular Python logger but changes the effective logging
-    level based on the application's debug flag.  Furthermore this
-    function also removes all attached handlers in case there was a
-    logger with the log name before.
+    """Get the ``'flask.app'`` logger and configure it if needed.
+
+    When :attr:`~flask.Flask.debug` is enabled, set the logger level to
+    :data:`logging.DEBUG` if it is not set.
+
+    If there is no handler for the logger's effective level, add a
+    :class:`~logging.StreamHandler` for
+    :func:`~flask.logging.wsgi_errors_stream` with a basic format.
     """
-    Logger = getLoggerClass()
+    logger = logging.getLogger('flask.app')
 
-    class DebugLogger(Logger):
-        def getEffectiveLevel(self):
-            if self.level == 0 and app.debug:
-                return DEBUG
-            return Logger.getEffectiveLevel(self)
+    if app.debug and logger.level == logging.NOTSET:
+        logger.setLevel(logging.DEBUG)
 
-    class DebugHandler(StreamHandler):
-        def emit(self, record):
-            if app.debug and _should_log_for(app, 'debug'):
-                StreamHandler.emit(self, record)
-
-    class ProductionHandler(StreamHandler):
-        def emit(self, record):
-            if not app.debug and _should_log_for(app, 'production'):
-                StreamHandler.emit(self, record)
-
-    debug_handler = DebugHandler()
-    debug_handler.setLevel(DEBUG)
-    debug_handler.setFormatter(Formatter(DEBUG_LOG_FORMAT))
-
-    prod_handler = ProductionHandler(_proxy_stream)
-    prod_handler.setLevel(ERROR)
-    prod_handler.setFormatter(Formatter(PROD_LOG_FORMAT))
-
-    logger = getLogger(app.logger_name)
-    # just in case that was not a new logger, get rid of all the handlers
-    # already attached to it.
-    del logger.handlers[:]
-    logger.__class__ = DebugLogger
-    logger.addHandler(debug_handler)
-    logger.addHandler(prod_handler)
-
-    # Disable propagation by default
-    logger.propagate = False
+    if not has_level_handler(logger):
+        logger.addHandler(default_handler)
 
     return logger