pywikibot/logging.py
"""User output/logging functions.
Six output functions are defined. Each requires a ``msg`` argument
All of these functions generate a message to the log file if
logging is enabled (`-log` or `-debug` command line arguments).
The functions :func:`info` (alias :func:`output`), :func:`stdout`,
:func:`warning` and :func:`error` all display a message to the user
through the logger object; the only difference is the priority level,
which can be used by the application layer to alter the display. The
:func:`stdout` function should be used only for data that is the
"result" of a script, as opposed to information messages to the user.
The function :func:`log` by default does not display a message to the
user, but this can be altered by using the `-verbose` command line
option.
The function :func:`debug` only logs its messages, they are never
displayed on the user console. :func:`debug()` takes a required second
argument, which is a string indicating the debugging layer.
.. seealso::
- :pyhow:`Logging HOWTO<logging>`
- :python:`Logging Cookbook<howto/logging-cookbook.html>`
"""
#
# (C) Pywikibot team, 2010-2024
#
# Distributed under the terms of the MIT license.
#
from __future__ import annotations
__all__ = (
'CRITICAL', 'DEBUG', 'ERROR', 'INFO', 'WARNING', 'STDOUT', 'VERBOSE',
'INPUT',
'add_init_routine',
'logoutput', 'info', 'output', 'stdout', 'warning', 'error', 'log',
'critical', 'debug', 'exception',
)
import logging
import os
import sys
# logging levels
from logging import CRITICAL, DEBUG, ERROR, INFO, WARNING
from typing import Any
from pywikibot.backports import Callable
from pywikibot.tools import deprecated_args, issue_deprecation_warning
STDOUT = 16 #:
VERBOSE = 18 #:
INPUT = 25 #:
"""Three additional logging levels which are implemented beside
:const:`CRITICAL`, :const:`DEBUG`, :const:`ERROR`, :const:`INFO` and
:const:`WARNING`.
.. seealso:: :python:`Python Logging Levels<logging.html#logging-levels>`
"""
_init_routines: list[Callable[[], Any]] = []
_inited_routines = set()
def add_init_routine(routine: Callable[[], Any]) -> None:
"""Add a routine to be run as soon as possible."""
_init_routines.append(routine)
def _init() -> None:
"""Init any routines which have not already been called."""
for init_routine in _init_routines:
found = init_routine in _inited_routines # prevent infinite loop
_inited_routines.add(init_routine)
if not found:
init_routine()
# Clear the list of routines to be inited
_init_routines[:] = [] # the global variable is used with slice operator
# Note: The frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def logoutput(msg: Any,
*args: Any,
level: int = INFO,
**kwargs: Any) -> None:
"""Format output and send to the logging module.
Dispatch helper function used by all the user-output convenience
functions. It can be used to implement your own high-level output
function with a different logging level.
`msg` can contain special sequences to create colored output. These
consist of the color name in angle bracket, e. g. <<lightpurple>>.
<<default>> resets the color.
Other keyword arguments are passed unchanged to the logger; so far,
the only argument that is useful is ``exc_info=True``, which causes
the log message to include an exception traceback.
.. versionchanged:: 7.2
Positional arguments for *decoder* and *newline* are deprecated;
keyword arguments should be used.
:param msg: The message to be printed.
:param args: Not used yet; prevents positional arguments except `msg`.
:param level: The logging level; supported by :func:`logoutput` only.
:keyword bool newline: If newline is True (default), a line feed
will be added after printing the msg.
:keyword str layer: Suffix of the logger name separated by dot. By
default no suffix is used.
:keyword str decoder: If msg is bytes, this decoder is used to
decode. Default is 'utf-8', fallback is 'iso8859-1'
:param kwargs: For the other keyword arguments refer
:python:`Logger.debug()<library/logging.html#logging.Logger.debug>`
"""
# invoke any init routines
if _init_routines:
_init()
keys: tuple[str, ...]
# cleanup positional args
if level == ERROR:
keys = ('decoder', 'newline', 'exc_info')
elif level == DEBUG:
keys = ('layer', 'decoder', 'newline')
else:
keys = ('decoder', 'newline')
for i, arg in enumerate(args):
key = keys[i]
issue_deprecation_warning(
f'Positional argument {i + 1} ({arg})',
f'keyword argument "{key}={arg}"',
since='7.2.0')
if key in kwargs:
warning('{!r} is given as keyword argument {!r} already; ignoring '
'{!r}'.format(key, arg, kwargs[key]))
else:
kwargs[key] = arg
# frame 0 is logoutput() in this module,
# frame 1 is the deprecation wrapper of this function
# frame 2 is the convenience function (output(), etc.)
# frame 3 is the deprecation wrapper the convenience function
# frame 4 is whatever called the convenience function
newline = kwargs.pop('newline', True)
frame = sys._getframe(4)
module = os.path.basename(frame.f_code.co_filename)
context = {'caller_name': frame.f_code.co_name,
'caller_file': module,
'caller_line': frame.f_lineno,
'newline': ('\n' if newline else '')}
context.update(kwargs.pop('extra', {}))
decoder = kwargs.pop('decoder', 'utf-8')
if isinstance(msg, bytes):
try:
msg = msg.decode(decoder)
except UnicodeDecodeError:
msg = msg.decode('iso8859-1')
layer = kwargs.pop('layer', '')
logger = logging.getLogger(('pywiki.' + layer).strip('.'))
logger.log(level, msg, extra=context, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def info(msg: Any = '', *args: Any, **kwargs: Any) -> None:
"""Output a message to the user with level :const:`INFO`.
``msg`` will be sent to stderr via :mod:`pywikibot.userinterfaces`.
It may be omitted and a newline is printed in that case.
The arguments are interpreted as for :func:`logoutput`.
.. versionadded:: 7.2
was renamed from :func:`output`. Positional arguments for
*decoder* and *newline* are deprecated; keyword arguments should
be used. Keyword parameter *layer* was added.
.. seealso::
:python:`Logger.info()<library/logging.html#logging.Logger.info>`
"""
logoutput(msg, *args, **kwargs)
output = info
"""Synonym for :func:`info` for backward compatibility. The arguments
are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
was renamed to :func:`info`; `text` was renamed to `msg`; `msg`
paramerer may be omitted; only keyword arguments are allowed except
for `msg`. Keyword parameter *layer* was added.
.. seealso::
:python:`Logger.info()<library/logging.html#logging.Logger.info>`
"""
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def stdout(msg: Any = '', *args: Any, **kwargs: Any) -> None:
"""Output script results to the user with level :const:`STDOUT`.
``msg`` will be sent to standard output (stdout) via
:mod:`pywikibot.userinterfaces`, so that it can be piped to another
process. All other functions will send to stderr.
`msg` may be omitted and a newline is printed in that case.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
`text` was renamed to `msg`; `msg` parameter may be omitted;
only keyword arguments are allowed except for `msg`. Keyword
parameter *layer* was added.
.. seealso::
- :python:`Logger.log()<library/logging.html#logging.Logger.log>`
- https://en.wikipedia.org/wiki/Pipeline_%28Unix%29
"""
logoutput(msg, *args, level=STDOUT, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def warning(msg: Any, *args: Any, **kwargs: Any) -> None:
"""Output a warning message to the user with level :const:`WARNING`.
``msg`` will be sent to stderr via :mod:`pywikibot.userinterfaces`.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
`text` was renamed to `msg`; only keyword arguments are allowed
except for `msg`. Keyword parameter *layer* was added.
.. seealso::
:python:`Logger.warning()<library/logging.html#logging.Logger.warning>`
"""
logoutput(msg, *args, level=WARNING, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def error(msg: Any, *args: Any, **kwargs: Any) -> None:
"""Output an error message to the user with level :const:`ERROR`.
``msg`` will be sent to stderr via :mod:`pywikibot.userinterfaces`.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
`text` was renamed to `msg`; only keyword arguments are allowed
except for `msg`. Keyword parameter *layer* was added.
.. seealso::
:python:`Logger.error()<library/logging.html#logging.Logger.error>`
"""
logoutput(msg, *args, level=ERROR, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def log(msg: Any, *args: Any, **kwargs: Any) -> None:
"""Output a record to the log file with level :const:`VERBOSE`.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
`text` was renamed to `msg`; only keyword arguments are allowed
except for `msg`. Keyword parameter *layer* was added.
.. seealso::
:python:`Logger.log()<library/logging.html#logging.Logger.log>`
"""
logoutput(msg, *args, level=VERBOSE, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def critical(msg: Any, *args: Any, **kwargs: Any) -> None:
"""Output a critical record to the user with level :const:`CRITICAL`.
``msg`` will be sent to stderr via :mod:`pywikibot.userinterfaces`.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
`text` was renamed to `msg`; only keyword arguments are allowed
except for `msg`. Keyword parameter *layer* was added.
.. seealso::
:python:`Logger.critical()
<library/logging.html#logging.Logger.critical>`
"""
logoutput(msg, *args, level=CRITICAL, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(text='msg') # since 7.2
def debug(msg: Any, *args: Any, **kwargs: Any) -> None:
"""Output a debug record to the log file with level :const:`DEBUG`.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
`layer` parameter is optional; `text` was renamed to `msg`;
only keyword arguments are allowed except for `msg`.
.. seealso::
:python:`Logger.debug()<library/logging.html#logging.Logger.debug>`
"""
logoutput(msg, *args, level=DEBUG, **kwargs)
# Note: The logoutput frame must be updated if this decorator is removed
@deprecated_args(tb='exc_info') # since 7.2
def exception(msg: Any = None, *args: Any,
exc_info: bool = True, **kwargs: Any) -> None:
"""Output an error traceback to the user with level :const:`ERROR`.
Use directly after an 'except' statement::
...
except Exception:
pywikibot.exception()
...
or alternatively::
...
except Exception as e:
pywikibot.exception(e)
...
With `exc_info=False` this function works like :func:`error` except
that the `msg` parameter may be omitted.
This function should only be called from an Exception handler.
``msg`` will be sent to stderr via :mod:`pywikibot.userinterfaces`.
The arguments are interpreted as for :func:`logoutput`.
.. versionchanged:: 7.2
only keyword arguments are allowed except for `msg`;
`exc_info` keyword is to be used instead of `tb`. Keyword
parameter *layer* was added.
.. versionchanged:: 7.3
`exc_info` is True by default
.. seealso::
:python:`Logger.exception()
<library/logging.html#logging.Logger.exception>`
The arguments are interpreted as for :meth:`output`.
"""
if msg is None:
exc_type, value, _tb = sys.exc_info()
msg = str(value)
if not exc_info:
msg += f' ({exc_type.__name__})'
assert msg is not None
error(msg, *args, exc_info=exc_info, **kwargs)