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.

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.

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, text='[deprecated name of 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.

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.

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

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

  • args (Any) – Not used yet; prevents positional arguments except msg.

  • 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’

pywikibot.logging.info(msg='', text='[deprecated name of 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().

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.

See also

Logger.info()

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.output(msg='', text='[deprecated name of 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)

pywikibot.logging.stdout(msg='', text='[deprecated name of 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.

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.warning(msg, text='[deprecated name of 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.

See also

Logger.warning()

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.error(msg, text='[deprecated name of 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.

See also

Logger.error()

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.log(msg, text='[deprecated name of 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.

See also

Logger.log()

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.critical(msg, text='[deprecated name of 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.

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.debug(msg, text='[deprecated name of 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.

See also

Logger.debug()

Parameters:
  • msg (Any)

  • args (Any)

  • kwargs (Any)

pywikibot.logging.exception(msg=None, tb='[deprecated name of exc_info]', *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

The arguments are interpreted as for output().

Parameters:
  • msg (Any)

  • args (Any)

  • exc_info (bool)

  • kwargs (Any)