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 8.0.0.

OfflineImap can be imported as:

from offlineimap import OfflineImap

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()

__deletefolder(options)

__dumpstacks(context=1, sighandler_deep=2)

Signal handler: dump a stack trace for each existing thread.

__migratefmd5(options)

__parse_cmd_options()

__serverdiagnostics(options)

__sync(options)

Invoke the correct single/multithread syncing

self.config is supposed to have been correctly initialized already.

__sync_singlethreaded(list_accounts, profiledir)

Executed in singlethreaded mode only.

Parameters:

accs – A list of accounts that should be synced

_get_activeaccounts(options)

get_env_info()

run()

Parse the commandline and invoke everything

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 (str) 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.

In multi-threaded mode, one instance of this object is run per “account” thread.

Parameters:

• config (offlineimap.CustomConfig.CustomConfigParser) – Representing the offlineimap configuration file.

• name – A (str) string denoting the name of the Account as configured.

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.

getconf(option, default=<function CustomConfigDefault>)

Retrieves string from the configuration.

Arguments:

• option: option name whose value is to be retrieved;

• default: default return value if no such option exists.

getconf_xform(option, xforms, default=<function CustomConfigDefault>)

Retrieves string from the configuration transforming the result.

Arguments:

• option: option name whose value is to be retrieved;

• xforms: iterable that returns transform functions to be applied to the value of the option, both retrieved and default one;

• default: default value for string if no such option exists.

getconfboolean(option, default=<function CustomConfigDefault>)

Retrieves boolean value from the configuration.

Arguments:

• option: option name whose value is to be retrieved;

• default: default return value if no such option exists.

getconffloat(option, default=<function CustomConfigDefault>)

Retrieves floating-point value from the configuration.

Arguments:

• option: option name whose value is to be retrieved;

• default: default return value if no such option exists.

getconfig()

Returns CustomConfigParser object that we will use for all our actions.

Must be overriden in all classes that use this mix-in.

getconfint(option, default=<function CustomConfigDefault>)

Retrieves integer value from the configuration.

Arguments:

• option: option name whose value is to be retrieved;

• default: default return value if no such option exists.

getconflist(option, separator_re, default=<function CustomConfigDefault>)

Retrieves strings from the configuration and splits it into the list of strings.

Arguments:

• option: option name whose value is to be retrieved;

• separator_re: regular expression for separator to be used for split operation;

• default: default return value if no such option exists.

getsection()

Returns name of configuration section in which our class keeps its configuration.

Must be overriden in all classes that use this mix-in.

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.

syncrunner()

The target for both single and multi-threaded modes.

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 exception 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.