logger: Application log support

Support classes for logging messages.

class CollatingLog

Bases: HtmlLog

Collates log messages

This class is designed to be used via the Collator context manager. Please see that class for documentation.

log(self, level, msg, image_info, is_html)

Supported API . Log a message.

Parameters
levelLEVEL_XXX constant from Log base class

How important the message is (e.g., error, warning, info)

msgtext, possibly HTML

Message to log

image_infoa (image, boolean) 2-tuple

image is either a PIL image or None (if there is no image to log). The boolean indicates whether there should be a line break after the image. When there is an image to log, msg param is alt text to use

is_htmlboolean

Is the message text HTML or not

Returns
True if the routine displayed/handled the log message, False otherwise.
class Collator(logger, summary_title, log_messages=True)

Bases: object

Context manager for a CollatingLog

This class is designed to be used when some operation may produce many log messages that would be more convenient to present as one combined message. Since this class is a context manager, you simply surround the code whose messages you want collated with a ‘with’ context using an instance of this class, e.g.:

from chimerax.core.logger import Collator
with Collator(session.logger, "Problems found while doing X"):
    ...code to collate...
Parameters
loggerthe session’s Logger

The logger to use.

summary_titlestring

What to title the log summary.

log_messagesboolean

Whether or not to actually log the collated messages, defaults True.

class HtmlLog

Bases: Log

Base class for logs that support HTML output

log(self, level, msg, image_info, is_html)

Supported API . Log a message.

Parameters
levelLEVEL_XXX constant from Log base class

How important the message is (e.g., error, warning, info)

msgtext, possibly HTML

Message to log

image_infoa (image, boolean) 2-tuple

image is either a PIL image or None (if there is no image to log). The boolean indicates whether there should be a line break after the image. When there is an image to log, msg param is alt text to use

is_htmlboolean

Is the message text HTML or not

Returns
True if the routine displayed/handled the log message, False otherwise.
class Log

Bases: object

Base class for the “real” log classes: HtmlLog and PlainTextLog.

Attributes
LEVEL_BUGfor bugs
LEVEL_ERRORfor other error messages
LEVEL_INFOfor informational messages
LEVEL_WARNINGfor warning messages
log(self, level, msg)

Supported API . Log a message.

Must be overriden by subclass.

Parameters
levelLEVEL_XXX constant from Log base class

How important the message is (e.g., error, warning, info)

msgtext, possibly HTML

Message to log

status(self, msg, color, secondary)

Supported API . Show a status message.

Parameters
msgplain (non-HTML) text

The message to display

colortext or (r,g,b) tuple, r/g/b in range 0-1

Color to display text in. If log cannot understand color text string, use black instead.

secondaryboolean

Whether to show the status in the secondary status area. If the log doesn’t support a secondary status area it should either drop the status or combine it with the last known primary status message.

Returns
True if the routine displayed/handled the status, False otherwise.
This method is not abstract because a log is free to totally
ignore/drop status messages.
Note that this method may be called from a thread (due to the
use of timers to get proper time delays) and that therefore
special window toolkit handling may be necessary to get your
code executed in the main thread (e.g., session.ui.thread_safe()).
class Logger(session)

Bases: StatusLogger

Log/status message dispatcher

Log/status message producers use the error()/ warning()/ info()/ status() methods to send messages to a log. The message will be sent to the log at the top of the log stack and then each other log in order.

Message consumers must inherit from HtmlLog or PlainTextLog and register themselves with the Logger’s add_log() method, which will put them at the top of the log stack. When quitting or otherwise no longer interested in receiving log messages they should deregister themselves with the remove_log() method. Consumers need to override their Log.log() abstract method, but need not override the Log.status() method if they are not interested in showing status.

add_log(self, log)

Supported API . Add a logger

bug(self, msg, add_newline=True, image=None, is_html=False)

Supported API . Log a bug

Parameters
msgtext

Message to log, either plain text or HTML

add_newlineboolean

Whether to add a newline to the message before logging it (also whether there is a line break after an image)

imagePIL image or None

If not None, an image to log. If an image is provided, then the :param:msg parameter is alt text to show for logs than cannot display images

is_htmlboolean

Is the :param:msg text HTML or plain text

clear(self)

Supported API . Clear all loggers

error(self, msg, add_newline=True, image=None, is_html=False)

Supported API . Log an error message

Parameters
msgtext

Message to log, either plain text or HTML

add_newlineboolean

Whether to add a newline to the message before logging it (also whether there is a line break after an image)

imagePIL image or None

If not None, an image to log. If an image is provided, then the :param:msg parameter is alt text to show for logs than cannot display images

is_htmlboolean

Is the :param:msg text HTML or plain text

info(self, msg, add_newline=True, image=None, is_html=False)

Supported API . Log an info message

The parameters are the same as for the error() method.

remove_log(self, log)

Supported API . Remove a logger

report_exception(self, preface=None, error_description=None, exc_info=None)

Supported API . Report the current exception (without changing execution context)

Parameters
prefacetext

Prepend this text to the report

error_descriptiontext

Replace any traceback information with this text

status(self, msg, **kw)

Supported API . Show status.

warning(self, msg, add_newline=True, image=None, is_html=False)

Supported API . Log a warning message

The parameters are the same as for the error() method.

class PlainTextLog

Bases: Log

Base class for logs that support only plain text output

log(self, level, msg)

Supported API . Log a message.

Parameters
levelLOG_XXX constant from Log base class

How important the message is (e.g., error, warning, info)

msgtext

Message to log

Returns
True if the routine displayed/handled the log message, False otherwise.
class StatusLogger(session)

Bases: object

Base class for classes that offer ‘status’ method.

status(self, msg, color='black', log=False, secondary=False, blank_after=None, follow_with='', follow_time=20, follow_log=None)

Supported API . Show status.

class StringPlainTextLog(logger)

Bases: PlainTextLog

Capture plain text messages in a string (similar to StringIO)

log(self, level, msg)

Supported API . Log a message.

Parameters
levelLOG_XXX constant from Log base class

How important the message is (e.g., error, warning, info)

msgtext

Message to log

Returns
True if the routine displayed/handled the log message, False otherwise.
html_to_plain(html)

Experimental API . ‘best effort’ to convert HTML to plain text

log_version(logger)

Experimental API . Show version information.