"""
Kivy Logging
============
By default, Kivy provides a logging system based on the standard Python
`logging <https://docs.python.org/3/library/logging.html>`_ module with
several additional features designed to be more convenient. These features
include:
* simplied usage (single instance, simple configuration, works by default)
* color-coded output on supported terminals
* output to ``stderr`` by default
* message categorization via colon separation
* access to log history even if logging is disabled
* built-in handling of various cross-platform considerations
* any stray output written to ``sys.stderr`` is captured, and stored in the log
file as a warning.
These features are configurable via the Config file or environment variables -
including falling back to only using the standard Python system.
Logger object
=============
The Kivy ``Logger`` class provides a singleton logging.logger instance.
As well as the standard logging levels (``debug``, ``info``,
``warning``, ``error`` and ``critical``), an additional ``trace`` level is
available.
Example Usage
-------------
Use the ``Logger`` as you would a standard Python logger. ::
from kivy.logger import Logger
Logger.info('title: This is a info message.')
Logger.debug('title: This is a debug message.')
try:
raise Exception('bleh')
except Exception:
Logger.exception('Something happened!')
The message passed to the logger is split into two parts separated by a colon
(:). The first part is used as a title and the second part is used as the
message. This way, you can "categorize" your messages easily. ::
Logger.info('Application: This is a test')
# will appear as
[INFO ] [Application ] This is a test
You can change the logging level at any time using the ``setLevel`` method. ::
from kivy.logger import Logger, LOG_LEVELS
Logger.setLevel(LOG_LEVELS["debug"])
.. versionchanged:: 2.2.0
Interaction with other logging
------------------------------
The Kivy logging system will, by default, present all log messages sent from
any logger - e.g. from third-party libraries.
Additional handlers may be added.
.. warning:: Handlers that output to ``sys.stderr`` may cause loops, as stderr
output is reported as a warning log message.
Logger Configuration
====================
Kivy Log Mode
-------------
At the highest level, Kivy's logging system is controlled by an environment
variable ``KIVY_LOG_MODE``. It may be given any of three values:
``KIVY``, ``PYTHON``, ``MIXED``
.. versionadded: 2.2.0
KIVY Mode (default)
^^^^^^^^^^^^^^^^^^^
In ``KIVY`` mode, all Kivy handlers are attached to the root logger, so all log
messages in the system are output to the Kivy log files and to the console. Any
stray output to ``sys.stderr`` is logged as a warning.
If you are writing an entire Kivy app from scratch, this is the most convenient
mode.
PYTHON Mode
^^^^^^^^^^^
In ``PYTHON`` mode, no handlers are added, and ``sys.stderr`` output is not
captured. It is left to the client to add appropriate handlers. (If none are
added, the ``logging`` module will output them to ``stderr``.)
Messages logged with ``Logger`` will be propagated to the root logger, from a
logger named ``kivy``.
If the Kivy app is part of a much larger project which has its own logging
regimen, this is the mode that gives most control.
The ``kivy.logger`` file contains a number of ``logging.handler``,
``logging.formatter``, and other helper classes to allow
users to adopt the features of Kivy logging that they like, including the
stderr redirection.
MIXED Mode
^^^^^^^^^^
In ``MIXED`` mode, handlers are added to the Kivy's ``Logger`` object directly,
and propagation is turned off. ``sys.stderr`` is not redirected.
Messages logged with Kivy's ``Logger`` will appear in the Kivy log file and
output to the Console.
However, messages logged with other Python loggers will not be handled by Kivy
handlers. The client will need to add their own.
If you like the features of Kivy ``Logger``, but are writing a Kivy app that
relies on third-party libraries that don't use colon-separation of categorise
or depend on the display of the logger name, this mode provides a compromise.
Again, the ``kivy.logger`` file contains re-usable logging features that can be
used to get the best of both systems.
Config Files
------------
In ``KIVY`` and ``MIXED`` modes, the logger handlers can be controlled via the
Kivy configuration file::
[kivy]
log_level = info
log_enable = 1
log_dir = logs
log_name = kivy_%y-%m-%d_%_.txt
log_maxfiles = 100
More information about the allowed values are described in the
:mod:`kivy.config` module.
In addition, the environment variables ``KIVY_NO_FILELOG`` and
``KIVY_NO_CONSOLELOG`` can be used to turn off the installation of the
corresponding handlers.
Logger History
--------------
Even if the logger is not enabled, you still have access to the last 100
LogRecords::
from kivy.logger import LoggerHistory
print(LoggerHistory.history)
"""
import logging
import os
import sys
from functools import partial
import pathlib
import kivy
from kivy.utils import platform
__all__ = (
"add_kivy_handlers",
"ColonSplittingLogRecord",
"ColoredLogRecord",
"COLORS",
"ConsoleHandler",
"file_log_handler",
"FileHandler",
"is_color_terminal",
"KivyFormatter",
"LOG_LEVELS",
"Logger",
"LoggerHistory",
"ProcessingStream",
"UncoloredLogRecord",
)
Logger = None
logging.addLevelName(9, 'TRACE')
logging.TRACE = 9
LOG_LEVELS = {
'trace': logging.TRACE,
'debug': logging.DEBUG,
'info': logging.INFO,
'warning': logging.WARNING,
'error': logging.ERROR,
'critical': logging.CRITICAL}
[docs]class FileHandler(logging.Handler):
history = []
filename = 'log.txt'
fd = None
log_dir = ''
encoding = 'utf-8'
[docs] def purge_logs(self):
"""Purge logs which exceed the maximum amount of log files,
starting with the oldest creation timestamp (or edit-timestamp on Linux)
"""
if not self.log_dir:
return
from kivy.config import Config
maxfiles = Config.getint("kivy", "log_maxfiles")
# Get path to log directory
log_dir = pathlib.Path(self.log_dir)
if maxfiles < 0: # No log file limit set
return
Logger.info("Logger: Purge log fired. Processing...")
# Get all files from log directory and corresponding creation timestamps
files = [(item, item.stat().st_ctime)
for item in log_dir.iterdir() if item.is_file()]
# Sort files by ascending timestamp
files.sort(key=lambda x: x[1])
for file, _ in files[:(-maxfiles or len(files))]:
# More log files than allowed maximum,
# delete files, starting with oldest creation timestamp
# (or edit-timestamp on Linux)
try:
file.unlink()
except (PermissionError, FileNotFoundError) as e:
Logger.info(f"Logger: Skipped file {file}, {repr(e)}")
Logger.info("Logger: Purge finished!")
def _configure(self, *largs, **kwargs):
from time import strftime
from kivy.config import Config
log_dir = Config.get('kivy', 'log_dir')
log_name = Config.get('kivy', 'log_name')
_dir = kivy.kivy_home_dir
if log_dir and os.path.isabs(log_dir):
_dir = log_dir
else:
_dir = os.path.join(_dir, log_dir)
if not os.path.exists(_dir):
os.makedirs(_dir)
self.log_dir = _dir
pattern = log_name.replace('%_', '@@NUMBER@@')
pattern = os.path.join(_dir, strftime(pattern))
n = 0
while True:
filename = pattern.replace('@@NUMBER@@', str(n))
if not os.path.exists(filename):
break
n += 1
if n > 10000: # prevent maybe flooding ?
raise Exception('Too many logfile, remove them')
if FileHandler.filename == filename and FileHandler.fd is not None:
return
FileHandler.filename = filename
if FileHandler.fd not in (None, False):
FileHandler.fd.close()
FileHandler.fd = open(filename, 'w', encoding=FileHandler.encoding)
Logger.info('Logger: Record log in %s' % filename)
def _write_message(self, record):
if FileHandler.fd in (None, False):
return
msg = self.format(record)
stream = FileHandler.fd
fs = "%s\n"
stream.write('[%-7s] ' % record.levelname)
stream.write(fs % msg)
stream.flush()
[docs] def emit(self, message):
# during the startup, store the message in the history
if Logger.logfile_activated is None:
FileHandler.history += [message]
return
# startup done, if the logfile is not activated, avoid history.
if Logger.logfile_activated is False:
FileHandler.history = []
return
if FileHandler.fd is None:
try:
self._configure()
from kivy.config import Config
Config.add_callback(self._configure, 'kivy', 'log_dir')
Config.add_callback(self._configure, 'kivy', 'log_name')
except Exception:
# deactivate filehandler...
if FileHandler.fd not in (None, False):
FileHandler.fd.close()
FileHandler.fd = False
Logger.exception('Error while activating FileHandler logger')
return
while FileHandler.history:
_message = FileHandler.history.pop()
self._write_message(_message)
self._write_message(message)
[docs]class LoggerHistory(logging.Handler):
history = []
[docs] def emit(self, message):
LoggerHistory.history = [message] + LoggerHistory.history[:100]
@classmethod
def clear_history(cls):
del cls.history[:]
[docs] def flush(self):
super(LoggerHistory, self).flush()
self.clear_history()
[docs]class ConsoleHandler(logging.StreamHandler):
"""
Emits records to a stream (by default, stderr).
However, if the msg starts with "stderr:" it is not formatted, but
written straight to the stream.
.. versionadded:: 2.2.0
"""
[docs] def filter(self, record):
try:
msg = record.msg
k = msg.split(':', 1)
if k[0] == 'stderr' and len(k) == 2:
# This message was scraped from stderr.
# Emit it without formatting.
self.stream.write(k[1] + '\n')
# Don't pass it to the formatted emitter.
return False
except Exception:
pass
return True
[docs]class ProcessingStream(object):
"""
Stream-like object that takes each completed line written to it,
adds a given prefix, and applies the given function to it.
.. versionadded:: 2.2.0
"""
def __init__(self, channel, func):
self.buffer = ""
self.func = func
self.channel = channel
self.errors = ""
def write(self, s):
s = self.buffer + s
self.flush()
f = self.func
channel = self.channel
lines = s.split('\n')
for line in lines[:-1]:
f('%s: %s' % (channel, line))
self.buffer = lines[-1]
def flush(self):
return
def isatty(self):
return False
def logger_config_update(section, key, value):
if KIVY_LOG_MODE != "PYTHON":
if LOG_LEVELS.get(value) is None:
raise AttributeError('Loglevel {0!r} doesn\'t exists'.format(value))
Logger.setLevel(level=LOG_LEVELS.get(value))
[docs]class ColonSplittingLogRecord(logging.LogRecord):
"""Clones an existing logRecord, but reformats the message field
if it contains a colon.
.. versionadded:: 2.2.0
"""
def __init__(self, logrecord):
try:
parts = logrecord.msg.split(":", 1)
if len(parts) == 2:
new_msg = "[%-12s]%s" % (parts[0], parts[1])
else:
new_msg = parts[0]
except Exception:
new_msg = logrecord.msg
super().__init__(
name=logrecord.name,
level=logrecord.levelno,
pathname=logrecord.pathname,
lineno=logrecord.lineno,
msg=new_msg,
args=logrecord.args,
exc_info=logrecord.exc_info,
func=logrecord.funcName,
sinfo=logrecord.stack_info,
)
[docs]class ColoredLogRecord(logging.LogRecord):
"""Clones an existing logRecord, but reformats the levelname to add
color, and the message to add bolding (where indicated by $BOLD
and $RESET in the message).
.. versionadded:: 2.2.0"""
BLACK = 0
RED = 1
GREEN = 2
YELLOW = 3
BLUE = 4
MAGENTA = 5
CYAN = 6
WHITE = 7
RESET_SEQ = "\033[0m"
COLOR_SEQ = "\033[1;%dm"
BOLD_SEQ = "\033[1m"
LEVEL_COLORS = {
"TRACE": MAGENTA,
"WARNING": YELLOW,
"INFO": GREEN,
"DEBUG": CYAN,
"CRITICAL": RED,
"ERROR": RED,
}
@classmethod
def _format_message(cls, message):
return str(message).replace(
"$RESET", cls.RESET_SEQ).replace("$BOLD", cls.BOLD_SEQ)
@classmethod
def _format_levelname(cls, levelname):
if levelname in cls.LEVEL_COLORS:
return (
cls.COLOR_SEQ % (30 + cls.LEVEL_COLORS[levelname])
+ levelname
+ cls.RESET_SEQ
)
return levelname
def __init__(self, logrecord):
super().__init__(
name=logrecord.name,
level=logrecord.levelno,
pathname=logrecord.pathname,
lineno=logrecord.lineno,
msg=logrecord.msg,
args=logrecord.args,
exc_info=logrecord.exc_info,
func=logrecord.funcName,
sinfo=logrecord.stack_info,
)
self.levelname = self._format_levelname(self.levelname)
self.msg = self._format_message(self.msg)
# Included for backward compatibility only.
# Could be used to override colors.
COLORS = ColoredLogRecord.LEVEL_COLORS
[docs]class UncoloredLogRecord(logging.LogRecord):
"""Clones an existing logRecord, but reformats the message
to remove $BOLD/$RESET markup.
.. versionadded:: 2.2.0"""
@classmethod
def _format_message(cls, message):
return str(message).replace("$RESET", "").replace("$BOLD", "")
def __init__(self, logrecord):
super().__init__(
name=logrecord.name,
level=logrecord.levelno,
pathname=logrecord.pathname,
lineno=logrecord.lineno,
msg=logrecord.msg,
args=logrecord.args,
exc_info=logrecord.exc_info,
func=logrecord.funcName,
sinfo=logrecord.stack_info,
)
self.msg = self._format_message(self.msg)
[docs]def is_color_terminal():
""" Detect whether the environment supports color codes in output.
.. versionadded:: 2.2.0
"""
return (
(
os.environ.get("WT_SESSION") or
os.environ.get("COLORTERM") == 'truecolor' or
os.environ.get('PYCHARM_HOSTED') == '1' or
os.environ.get('TERM') in (
'rxvt',
'rxvt-256color',
'rxvt-unicode',
'rxvt-unicode-256color',
'xterm',
'xterm-256color',
)
)
and platform not in ('android', 'ios')
)
#: Kivy default logger instance
# .. versionchanged:: 2.2.0
Logger = logging.getLogger('kivy')
Logger.logfile_activated = None
Logger.trace = partial(Logger.log, logging.TRACE)
file_log_handler = (
FileHandler()
if 'KIVY_NO_FILELOG' not in os.environ
else None
)
# Issue #7891 describes an undocumented feature that was since removed
# Detect if a client was depending on it.
# .. versionchanged:: 2.2.0
assert not hasattr(sys, '_kivy_logging_handler'), \
"Not supported. Try logging.root.addHandler()"
[docs]def add_kivy_handlers(logger):
""" Add Kivy-specific handlers to a logger.
.. versionadded:: 2.2.0
"""
# add default kivy logger
logger.addHandler(LoggerHistory())
if file_log_handler:
logger.addHandler(file_log_handler)
# Use the custom handler instead of streaming one.
# Don't output to stderr if it is set to None
# stderr is set to None by pythonw and pyinstaller 5.7+
if sys.stderr and 'KIVY_NO_CONSOLELOG' not in os.environ:
use_color = is_color_terminal()
if not use_color:
# No additional control characters will be inserted inside the
# levelname field, 7 chars will fit "WARNING"
fmt = "[%(levelname)-7s] %(message)s"
else:
# levelname field width need to take into account the length of
# the color control codes (7+4 chars for bold+color, and reset)
fmt = "[%(levelname)-18s] %(message)s"
formatter = KivyFormatter(fmt, use_color=use_color)
console = ConsoleHandler()
console.setFormatter(formatter)
logger.addHandler(console)
KIVY_LOG_MODE = os.environ.get("KIVY_LOG_MODE", "KIVY")
assert KIVY_LOG_MODE in ("KIVY", "PYTHON", "MIXED"), "Unknown log mode"
if KIVY_LOG_MODE == "KIVY":
# Add the Kivy handlers to the root logger, so they will be used
# for all propagated log messages.
add_kivy_handlers(logging.root)
# Root logger defaults to warning. Let Logger be the limiting factor.
logging.root.setLevel(logging.NOTSET)
# install stderr handlers
# Caution: If any logging handlers output to sys.stderr they should be
# configured BEFORE this reconfiguration is done to avoid loops.
sys.stderr = ProcessingStream("stderr", Logger.warning)
# Sends all messages written to stderr to the Logger, after prefixing it
# with "stderr:"
elif KIVY_LOG_MODE == "MIXED":
# Add the Kivy handlers to the Kivy logger, so they will be used
# for all messages sent through Logger, only.
add_kivy_handlers(Logger)
# Don't spread Kivy-related log messages to the root logger.
Logger.propagate = False
# Don't set stderr redirection: it is too likely to cause loops with other
# handlers. Client can manually add it, if desired.
else: # KIVY_LOG_MODE == "PYTHON"
# Don't add handlers or redirect stderr. Client can manually add if desired.
pass
