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
(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
- levelLEVEL_XXX constant from
- 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.
- loggerthe session’s
-
class
HtmlLog
¶ Bases:
Log
Base class for logs that support HTML output
-
log
(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
- levelLEVEL_XXX constant from
- 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_BUGfor bugs
- LEVEL_ERRORfor other error messages
- LEVEL_INFOfor informational messages
- LEVEL_WARNINGfor warning messages
-
log
(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
- levelLEVEL_XXX constant from
-
status
(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
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.-
add_log
(log)¶ Supported API . Add a logger
-
bug
(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
()¶ Supported API . Clear all loggers
-
error
(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
(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
(log)¶ Supported API . Remove a logger
-
report_exception
(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
(msg, **kw)¶ Supported API . Show status.
-
warning
(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
(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
(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
(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.