14.5.5 Handler Objects

Handlers have the following attributes and methods. Note that Handler is never instantiated directly; this class acts as a base for more useful subclasses. However, the __init__() method in subclasses needs to call Handler.__init__().

__init__( level=NOTSET): Initializes the Handler instance by setting its level, setting the list of filters to the empty list and creating a lock (using createLock()) for serializing access to an I/O mechanism.

createLock( ): Initializes a thread lock which can be used to serialize access to underlying I/O functionality which may not be threadsafe.

acquire( ): Acquires the thread lock created with createLock().

release( ): Releases the thread lock acquired with acquire().

setLevel( lvl): Sets the threshold for this handler to lvl. Logging messages which are less severe than lvl will be ignored. When a handler is created, the level is set to NOTSET (which causes all messages to be processed).

setFormatter( form): Sets the Formatter for this handler to form.

addFilter( filt): Adds the specified filter filt to this handler.

removeFilter( filt): Removes the specified filter filt from this handler.

filter( record): Applies this handler's filters to the record and returns a true value if the record is to be processed.

flush( ): Ensure all logging output has been flushed. This version does nothing and is intended to be implemented by subclasses.

close( ): Tidy up any resources used by the handler. This version does nothing and is intended to be implemented by subclasses.

handle( record): Conditionally emits the specified logging record, depending on filters which may have been added to the handler. Wraps the actual emission of the record with acquisition/release of the I/O thread lock.

handleError( record): This method should be called from handlers when an exception is encountered during an emit() call. By default it does nothing, which means that exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The specified record is the one which was being processed when the exception occurred.

format( record): Do formatting for a record - if a formatter is set, use it. Otherwise, use the default formatter for the module.

emit( record): Do whatever it takes to actually log the specified logging record. This version is intended to be implemented by subclasses and so raises a NotImplementedError.

See About this document... for information on suggesting changes.