logging — Logging Functions#

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 info() (alias output()), stdout(), warning() and 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 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 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 debug() only logs its messages, they are never displayed on the user console. debug() takes a required second argument, which is a string indicating the debugging layer.

See also

Imports in pywikibot module

The following functions are inported in pywikibot module and can also be used as pywikibot members:

pywikibot.logging.STDOUT = 16#
pywikibot.logging.VERBOSE = 18#
pywikibot.logging.INPUT = 25#

Three additional logging levels which are implemented beside CRITICAL, DEBUG, ERROR, INFO and WARNING.

See also

Python Logging Levels

pywikibot.logging.add_init_routine(routine)[source]#

Add a routine to be run as soon as possible.

Parameters:

routine (Callable[[], Any])

Return type:

None

pywikibot.logging.logoutput(msg, *args, level=20, **kwargs)[source]#

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.

args are the arguments which are merged into msg using the string formatting operator. It is passed unchanged to the logger.

Attention

Only old %-formatting is supported for args by the Python Library logging module.

Keyword arguments other than those listed below are also 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.

Changed in version 7.2: Positional arguments for decoder and newline are deprecated; keyword arguments should be used.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

Parameters:

  • msg (Any) – The message to be printed.

  • args (Any) – Passed as string formatter options to the logger.

  • level (int) – The logging level; supported by logoutput() only.

  • kwargs (Any) – For the other keyword arguments refer Logger.debug()

Keyword Arguments:

  • newline (bool) – If newline is True (default), a line feed will be added after printing the msg.

  • layer (str) – Suffix of the logger name separated by dot. By default no suffix is used.

  • decoder (str) – If msg is bytes, this decoder is used to decode. Default is ‘utf-8’, fallback is ‘iso8859-1’

Return type:

None

pywikibot.logging.info(msg='', *args, **kwargs)[source]#

Output a message to the user with level INFO.

msg will be sent to stderr via pywikibot.userinterfaces. It may be omitted and a newline is printed in that case. The arguments are interpreted as for logoutput(). args can be uses as formatting arguments for all logging functions of this module. But this works for old %-formatting only:

>>> info('Hello %s', 'World')  
Hello World
>>> info('Pywikibot %(version)d', {'version': 10})  
Pywikibot 10

Added in version 7.2: was renamed from output(). Positional arguments for decoder and newline are deprecated; keyword arguments should be used. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.info()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.output(msg='', *args, **kwargs)#

Synonym for info() for backward compatibility. The arguments are interpreted as for logoutput().

Changed in version 7.2: was renamed to info(); text was renamed to msg; msg paramerer may be omitted; only keyword arguments are allowed except for msg. Keyword parameter layer was added.

See also

Logger.info()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.stdout(msg='', *args, **kwargs)[source]#

Output script results to the user with level STDOUT.

msg will be sent to standard output (stdout) via 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 logoutput().

Changed in version 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.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.warning(msg, *args, **kwargs)[source]#

Output a warning message to the user with level WARNING.

msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: text was renamed to msg; only keyword arguments are allowed except for msg. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.warning()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.error(msg, *args, **kwargs)[source]#

Output an error message to the user with level ERROR.

msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: text was renamed to msg; only keyword arguments are allowed except for msg. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.error()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.log(msg, *args, **kwargs)[source]#

Output a record to the log file with level VERBOSE.

The arguments are interpreted as for logoutput().

Changed in version 7.2: text was renamed to msg; only keyword arguments are allowed except for msg. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.log()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.critical(msg, *args, **kwargs)[source]#

Output a critical record to the user with level CRITICAL.

msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: text was renamed to msg; only keyword arguments are allowed except for msg. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.critical()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.debug(msg, *args, **kwargs)[source]#

Output a debug record to the log file with level DEBUG.

The arguments are interpreted as for logoutput().

Changed in version 7.2: layer parameter is optional; text was renamed to msg; only keyword arguments are allowed except for msg.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.debug()

Parameters:

  • msg (Any)

  • args (Any)

  • kwargs (Any)

Return type:

None

pywikibot.logging.exception(msg=None, *args, exc_info=True, **kwargs)[source]#

Output an error traceback to the user with level 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 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 pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 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.

Changed in version 7.3: exc_info is True by default

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.exception()

The arguments are interpreted as for output().

Parameters:

  • msg (Any)

  • args (Any)

  • exc_info (bool)

  • kwargs (Any)

Return type:

None