offlineimap's API documentation

Within offlineimap, the classes OfflineImap provides the high-level functionality. The rest of the classes should usually not needed to be touched by the user. Email repositories are represented by a offlineimap.repository.Base.BaseRepository or derivatives (see offlineimap.repository for details). A folder within a repository is represented by a offlineimap.folder.Base.BaseFolder or any derivative from offlineimap.folder.

This page contains the main API overview of OfflineImap 6.5.5.

OfflineImap can be imported as:

from offlineimap import OfflineImap

The file SubmittingPatches.rst in the source distribution documents a number of resources and conventions you may find useful. It will eventually be merged into the main documentation. .. TODO: merge SubmittingPatches.rst to the main documentation

offlineimap – The OfflineImap module

class OfflineImap(cmdline_opts = None)

The main class that encapsulates the high level use of OfflineImap.

To invoke OfflineImap you would call it with:

oi = OfflineImap()
oi.run()

run()

Parse the commandline and invoke everything

parse_cmd_options()

offlineimap.account

An accounts.Account connects two email repositories that are to be synced. It comes in two flavors, normal and syncable.

class Account(config, name)

Represents an account (ie. 2 repositories) to sync

Most of the time you will actually want to use the derived accounts.SyncableAccount which contains all functions used for syncing an account.

Parameters:

• config (offlineimap.CustomConfig.CustomConfigParser) – Representing the offlineimap configuration file.
• name – A string denoting the name of the Account as configured

class SyncableAccount(*args, **kwargs)

A syncable email account connecting 2 repositories

Derives from accounts.Account but contains the additional functions syncrunner(), sync(), syncfolders(), used for syncing.

ui = <module 'offlineimap.ui' from '/builddir/build/BUILD/OfflineIMAP-offlineimap-8bc2f35/offlineimap/ui/__init__.pyc'>

Contains the current offlineimap.ui, and can be used for logging etc.

get_abort_event()

Checks if an abort signal had been sent

If the ‘skipsleep’ config option for this account had been set, with set_abort_event(config, 1) it will get cleared in this function. Ie, we will only skip one sleep and not all.

Returns:True, if the main thread had called set_abort_event() earlier, otherwise ‘False’.

get_local_folder(remotefolder)

Return the corresponding local folder for a given remotefolder

lock()

Lock the account, throwing an exception if it is locked already

serverdiagnostics()

Output diagnostics for all involved repositories

classmethod set_abort_event(config, signum)

Set skip sleep/abort event for all accounts

If we want to skip a current (or the next) sleep, or if we want to abort an autorefresh loop, the main thread can use set_abort_event() to send the corresponding signal. Signum = 1 implies that we want all accounts to abort or skip the current or next sleep phase. Signum = 2 will end the autorefresh loop, ie all accounts will return after they finished a sync. signum=3 means, abort NOW, e.g. on SIGINT or SIGTERM.

This is a class method, it will send the signal to all accounts.

sleeper()

Sleep if the account is set to autorefresh

Returns:0:timeout expired, 1: canceled the timer, 2:request to abort the program, 100: if configured to not sleep at all.

sync()

Synchronize the account once, then return

Assumes that self.remoterepos, self.localrepos, and self.statusrepos has already been populated, so it should only be called from the syncrunner() function.

unlock()

Unlock the account, deleting the lock file

OfflineImapError – A Notmuch execution error

exception OfflineImapError(reason, severity, errcode=None)

An Error during offlineimap synchronization

Parameters:

• reason – Human readable string suitable for logging
• severity (OfflineImapError.ERROR value) – denoting which operations should be aborted. E.g. a ERROR.MESSAGE can occur on a faulty message, but a ERROR.REPO occurs when the server is offline.
• errcode – optional number denoting a predefined error situation (which let’s us exit with a predefined exit value). So far, no errcodes have been defined yet.

This execption inherits directly from Exception and is raised on errors during the offlineimap execution. It has an attribute severity that denotes the severity level of the error.

class ERROR

Severity level of an Exception

• MESSAGE: Abort the current message, but continue with folder
• FOLDER_RETRY: Error syncing folder, but do retry
• FOLDER: Abort folder sync, but continue with next folder
• REPO: Abort repository sync, continue with next account
• CRITICAL: Immediately exit offlineimap

offlineimap.globals – module with global variables

Module offlineimap.globals provides the read-only storage for the global variables.

All exported module attributes can be set manually, but this practice is highly discouraged and shouldn’t be used. However, attributes of all stored variables can only be read, write access to them is denied.

Currently, we have only options attribute that holds command-line options as returned by OptionParser. The value of options must be set by set_options() prior to its first use.

options

You can access the values of stored options using the usual syntax, offlineimap.globals.options.<option-name>

set_options(source)

Sets the source for options variable