logger: Application log support¶
This module is very important.
-
class
CollatingLog
¶ Bases:
chimera.core.logger.PlainTextLog
Collates log messages
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. You call the logger’s
add_log()
method to start collating, and remove it withremove_log()
to stop collating. If the operation may produce many consecutive simiilar (or identical) log messagesm you may also want to set the logger’scollapse_similar
attribute to True after adding the log, and set it back to its original value before removing the log.To get the collated messages, call
summarize()
on the log. That will return a 2-tuple consisting of the maximum log level of the messages, and their combined text. The text will list the errors, warnings, etc. in separate sections of the text. To log the result, use the logger’smethod_map
dictionary to convert the maximum level to a method to call, and call that method with the summary as an argument (possibly preceded with some introductory text) and with the add_newline keyword set to False.
-
class
Collator
(logger, summary_title, log_errors=True)¶ Bases:
object
Context manager for a CollatingLog
Parameters: logger : the session’s
Logger
The logger to use.
summary_title : string
What to title the log summary.
log_errors : boolean
Whether or not to log errors, defaults True.
-
class
HtmlLog
¶ Bases:
chimera.core.logger.Log
Base class for logs that support HTML output
-
log
(level, msg, image_info, is_html)¶ Log a message.
Parameters: level : LEVEL_XXX constant from
Log
base classHow important the message is (e.g., error, warning, info)
msg : text, possibly HTML
Message to log
image_info : a (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_html : boolean
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
andPlainTextLog
.Attributes
LEVEL_ERROR (for error messages) LEVEL_INFO (for informational messages) LEVEL_WARNING (for warning messages) -
log
(level, msg)¶ Log a message.
Must be overriden by subclass.
Parameters: level : LEVEL_XXX constant from
Log
base classHow important the message is (e.g., error, warning, info)
msg : text, possibly HTML
Message to log
-
status
(msg, color, secondary)¶ Show a status message.
Parameters: msg : plain (non-HTML) text
The message to display
color : text 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.
secondary : boolean
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., wx.CallAfter).
-
-
class
Logger
(session)¶ Bases:
object
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
orPlainTextLog
and register themselves with the Logger’sadd_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 theremove_log()
method. Consumers need to override theirLog.log()
abstract method, but need not override theLog.status()
method if they are not interested in showing status.If the Logger
collapse_similar
attribute is True, then after a few occurances of consecutive similar log messages, the remainder will be collapsed into a single log message noting how many additional occurances there were.-
add_log
(log)¶ Add a logger
-
clear
()¶ clear all loggers
-
error
(msg, add_newline=True, image=None, is_html=False)¶ Log an error message
Parameters: msg : text
Message to log, either plain text or HTML
add_newline : boolean
Whether to add a newline to the message before logging it (also whether there is a line break after an image)
image : PIL 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_html : boolean
Is the :param:msg text HTML or plain text
-
info
(msg, add_newline=True, image=None, is_html=False)¶ Log an info message
The parameters are the same as for the
error()
method.
-
remove_log
(log)¶ remove a logger
-
status
(msg, color='black', log=False, secondary=False, blank_after=None, follow_with='', follow_time=20, follow_log=None)¶ Show status.
-
-
class
PlainTextLog
¶ Bases:
chimera.core.logger.Log
Base class for logs that support only plain text output
-
log
(level, msg)¶ Log a message.
Parameters: level : LOG_XXX constant from Log base class
How important the message is (e.g., error, warning, info)
msg : text
Message to log
Returns: True if the routine displayed/handled the log message, False otherwise.
-
-
html_to_plain
(html)¶ ‘best effort’ to convert HTML to plain text