offlineimap.ui – A flexible logging system

OfflineImap has various ui systems, that can be selected. They offer various functionalities. They must implement all functions that the offlineimap.ui.UIBase offers. Early on, the ui must be set using getglobalui()

ui.setglobalui(newui)

Set the global ui object to be used for logging.

ui.getglobalui()

Return the current ui object.

Base UI plugin

class UIBase(config, loglevel=20)

acct(account)

Output that we start syncing an account (and start counting).

acctdone(account)

Output that we finished syncing an account (in which time).

connecting(reposname, hostname, port)

Log ‘Establishing connection to’.

copyingmessage(uid, num, num_to_copy, src, destfolder)

Output a log line stating which message we copy.

error(exc, exc_traceback=None, msg=None)

Log a message at severity level ERROR.

Log Exception ‘exc’ to error log, possibly prepended by a preceding error “msg”, detailing at what point the error occurred.

In debug mode, we also output the full traceback that occurred if one has been passed in via sys.info()[2].

Also save the Exception to a stack that can be output at the end of the sync run when offlineiamp exits. It is recommended to always pass in exceptions if possible, so we can give the user the best debugging info.

We are always pushing tracebacks to the exception queue to make them to be output at the end of the run to allow users pass sensible diagnostics to the developers or to solve problems by themselves.

One example of such a call might be:

ui.error(exc, sys.exc_info()[2], msg=”While syncing Folder %s in “

“repo %s”)

getnicename(object)

Return the type of a repository or Folder as string.

(IMAP, Gmail, Maildir, etc...)

getthreadaccount(thr=None)

Get Account() for a thread (current if None)

If no account has been registered with this thread, return ‘None’.

ignorecopyingmessage(uid, src, destfolder)

Output a log line stating which message is ignored.

info(msg)

Display a message.

init_banner()

Called when the UI starts. Must be called before any other UI call except isusable(). Displays the copyright banner. This is where the UI should do its setup – TK, for instance, would create the application window here.

isusable()

Returns true if this UI object is usable in the current environment. For instance, an X GUI would return true if it’s being run in X with a valid DISPLAY setting, and false otherwise.

makefolder(repo, foldername)

Called when a folder is created.

registerthread(account)

Register current thread as being associated with an account name.

savemessage(debugtype, uid, flags, folder)

Output a log line stating that we save a msg.

serverdiagnostics(repository, type)

Connect to repository and output useful information for debugging.

setlogfile(logfile)

Create file handler which logs to file.

setup_consolehandler()

Backend specific console handler.

Sets up things and adds them to self.logger. :returns: The logging.Handler() for console output

setup_sysloghandler()

Backend specific syslog handler.

skippingfolder(folder)

Called when a folder sync operation is started.

sleep(sleepsecs, account)

This function does not actually output anything, but handles the overall sleep, dealing with updates as necessary. It will, however, call sleeping() which DOES output something.

Returns:0/False if timeout expired, 1/2/True if there is a request to cancel the timer.

sleeping(sleepsecs, remainingsecs)

Sleep for sleepsecs, display remainingsecs to go.

Does nothing if sleepsecs <= 0. Display a message on the screen if we pass a full minute.

This implementation in UIBase does not support this, but some implementations return 0 for successful sleep and 1 for an ‘abort’, ie a request to sync immediately.

syncfolders(src_repo, dst_repo)

Log ‘Copying folder structure...’.

syncingfolder(srcrepos, srcfolder, destrepos, destfolder)

Called when a folder sync operation is started.

terminate(exitstatus=0, errortitle=None, errormsg=None)

Called to terminate the application.

threadException(thread)

Called when a thread has terminated with an exception. The argument is the ExitNotifyThread that has so terminated.

threadExited(thread)

Called when a thread has exited normally.

Many UIs will just ignore this.

unregisterthread(thr)

Unregister a thread as being associated with an account name.