Logger

Logger

The agutil module includes the Logger class, which provides a simple interface for quick logging. Messages can be logged over specific channels, and each channel can be set to log to a file, stdout, neither, or both. The actual Logger instance is meant to be the point of control for the log. All agutil classes which support logging will log messages through the lambda returned by Logger.bindToSender().

Note: agutil also includes DummyLog, a default log used in other agutil classes which does no actual logging or printing

API

• Logger(filename=None, name='agutil', loglevel=logging.INFO): (Constructor)

  Instantiates a new Logger instance. filename specifies where log messages should be dispatched. If filename is a string, log messages will be written to the file at that path (appending to the file if it already exists). If filename is None (default), log messages are written to sys.stdout. Otherwise, filename is assumed to be a file-like-object and log messages will be written directly to filename. name should be the name of the log in the builtin logging hierarchy. This parameter is useful if you need to create multiple Logger instances. Warning: Messages logged by one Logger will also be logged by any additional Loggers with the same name. loglevel is used to control the minimum severity that this Logger will respond to. Messages logged below this level are ignored. Collection (see below) will automatically be enabled on 'ERROR' and 'WARNING' channels iff logging those channels is enabled (as determined by the loglevel)

• Logger(message, sender='ANONYMOUS', channel='INFO'): (Call)

• Logger.log(message, sender='ANONYMOUS', channel='INFO'):

  Logs the provided message. sender specifies the name of the object which is sending the message. channel specifies what channel the message is sent over. If the provided channel does not exist, the message will not be logged, and instead a warning message is logged. If the provided channel is below the Logger.level, the message will not be logged. If the provided sender has been muted by Logger.mute(), the message will not be logged.

• Logger.addChannel(name, priority):

  Defines a new channel with the given name. priority indicates how messages from this channel should be treated. If priority is less than the current Logger.level, then messages on this channel will be ignored. If priority is at or above the priority of warnings (30) and is greater than or equal to the current Logger.level, collection will automatically be enabled for this channel

• Logger.level (Property)

  Returns the current level of the Logger. Messages on channels with a priority below this value are ignored. You can assign a new value to this attribute to change the level. Warning: The level is shared between all Logger instances created with the same name. Preferred usage is to create one logger and bind to multiple senders.

• Logger.bindToSender(sender, can_close=True):

  Returns a bound version of Logger.log with the sender argument of Logger.log bound to the value of sender. This is the preferred way to have multiple objects logging to the same Logger instance. The returned function also has a callable attribute bindToSender which behaves identically to the root bindToSender, except can_close defaults to False. The returned function also has a callable attribute close which takes no arguments. If can_close is True, then the close attribute of the returned object will close this Logger. If can_close is True, then the close attribute of the returned object is a no-op. The returned function also has a string attribute name which reflects the bound value of sender.

• Logger.setChannelCollection(channel, collect=True):

  Enables or disables collection of the specified channel depending on the value of collect. While collection is enabled on a given channel, all messages logged by this Logger on that channel are recorded and appear in a dump when the Logger is closed. When collection is disabled, any previously collected messages are discarded. Channel collection is useful for making errors and warnings more visible at the end of logs

• Logger.mute(mutee, muter='ANONYMOUS'):

  Mutes messages sent by the given mutee. While a given sender is muted, they cannot log any messages, however messages will still be collected from this sender if the channel has collection enabled. When a sender gets muted, a message is logged on the INFO channel with sender set to the value of muter.

• Logger.unmut(mutee):

  Unmutes the given mutee. When a sender gets unmuted, a messages is logged on the INFO channel. Additionally, if the mutee sent any messages while muted, the most recent message sent will be logged.

• Logger.close():

  Closes the log. Any channels with collection enabled will dump any collected messages to the end of the log. Warning: If there are any other Loggers with the same name, they will still respond to calling this object's log()

Default Channels

In addition to supporting any user-created channels, the Logger class supports 5 built-in channels:

• ERROR: For logging errors and exceptions
• WARN: For logging warnings or minor errors
• INFO: For logging informative, and human-readable information
• DEBUG: For logging messages useful to debugging
• DETAIL: For logging extremely detailed information regarding program function

Each channel also has a constant set at the class level to use as input for the constructor's log_level and stdout_level arguments:

• LOGLEVEL_ERROR: Logs/prints only errors
• LOGLEVEL_WARN: Logs/prints errors and warnings
• LOGLEVEL_INFO: Logs/prints errors, warnings, and info
• LOGLEVEL_DEBUG: Logs/prints errors, warnings, info, and debug info
• LOGLEVEL_DETAIL: Logs/prints all messages to the 5 standard channels

And the additional level:

• LOGLEVEL_NONE: Do not log or print any messages to the 5 standard channels