4.5. User Settings

Alot sets up a SettingsManager to access user settings defined in different places uniformly. There are four types of user settings:

what? location accessible via
alot config ~/.config/alot/config or given by command option -c. SettingsManager.get()
hooks – user provided python code ~/.config/alot/hooks.py or as given by the hooksfile config value SettingsManager.get_hook()
notmuch config ~/.notmuchrc or given by command option -n SettingsManager.get_notmuch_setting()
mailcap – defines shellcommands to handle mime types ~/.mailcap (/etc/mailcap) SettingsManager.mailcap_find_match()

4.5.1. Settings Manager

class alot.settings.manager.SettingsManager(alot_rc=None, notmuch_rc=None)

Organizes user settings

  • alot_rc (str) – path to alot’s config file
  • notmuch_rc (str) – path to notmuch’s config file
get(key, fallback=None)

look up global config values from alot’s config

  • key (str) – key to look up
  • fallback (str) – fallback returned if key is not present

config value with type as specified in the spec-file


returns Account for a given email address (str)

Parameters:address (string) – address to look up
Return type:Account or None

returns known accounts

Return type:list of Account
get_addressbooks(order=None, append_remaining=True)

returns list of all defined AddressBook objects


returns addresses of known accounts including all their aliases


return hook (callable) identified by key

get_keybinding(mode, key)

look up keybinding from MODE-maps sections

  • mode (str) – mode identifier
  • key (str) – urwid-style key identifier

a command line to be applied upon keypress

Return type:



look up keybindings from MODE-maps sections

Parameters:mode (str) – mode identifier
Returns:dictionaries of key-cmd for global and specific mode
Return type:2-tuple of dicts

returns addresses of known accounts without its aliases

get_notmuch_setting(section, key, fallback=None)

look up config values from notmuch’s config

  • section (str) – key is in
  • key (str) – key to look up
  • fallback (str) – fallback returned if key is not present

config value with type as specified in the spec-file

get_tagstring_representation(tag, onebelow_normal=None, onebelow_focus=None)

looks up user’s preferred way to represent a given tagstring.

  • tag (str) – tagstring
  • onebelow_normal (urwid.AttrSpec) – attribute that shines through if unfocussed
  • onebelow_focus (urwid.AttrSpec) – attribute that shines through if focussed

If onebelow_normal or onebelow_focus is given these attributes will be used as fallbacks for fg/bg values ‘’ and ‘default’.

This returns a dictionary mapping
normal:to urwid.AttrSpec used if unfocussed
focussed:to urwid.AttrSpec used if focussed
translated:to an alternative string representation
get_theming_attribute(mode, name, part=None)

looks up theming attribute

  • mode (str) – ui-mode (e.g. search,`thread`...)
  • name (str) – identifier of the atttribute
Return type:



looks up theming info a threadline displaying a given thread. This wraps around get_threadline_theming(), filling in the current colour mode.

Parameters:thread (alot.db.thread.Thread) – thread to theme
mailcap_find_match(*args, **kwargs)

Propagates mailcap.find_match() but caches the mailcap (first argument)


parse alot’s config file from path


parse notmuch’s config file from path


turns a given datetime obj into a unicode string representation. This will:

  1. look if a fixed ‘timestamp_format’ is given in the config
  2. check if a ‘timestamp_format’ hook is defined
  3. use pretty_datetime() as fallback
set(key, value)

setter for global config values

  • key (str) – config option identifise
  • value (depends on the specfile alot.rc.spec) – option to set

4.5.2. Errors

exception alot.settings.errors.ConfigError

could not parse user config

4.5.3. Utils

alot.settings.utils.read_config(configpath=None, specpath=None, checks=None)

get a (validated) config object for given config file path.

  • configpath (str) – path to config-file
  • specpath (str) – path to spec-file
  • checks (dict str->callable,) – custom checks to use for validator. see validate docs


Return type:


alot.settings.utils.resolve_att(a, fallback)

replace ‘’ and ‘default’ by fallback values

4.5.4. Themes

class alot.settings.theme.Theme(path)

Colour theme

Parameters:path (str) – path to theme file
get_attribute(colourmode, mode, name, part=None)

returns requested attribute

  • mode (str) – ui-mode (e.g. search,`thread`...)
  • name (str) – of the atttribute
  • colourmode (int) – colour mode; in [1, 16, 256]
Return type:


get_threadline_theming(thread, colourmode)

look up how to display a Threadline wiidget in search mode for a given thread.

  • thread (alot.db.thread.Thread) – Thread to theme Threadline for
  • colourmode (int) – colourmode to use, one of 1,16,256.
This will return a dict mapping
normal:to urwid.AttrSpec,
focus:to urwid.AttrSpec,
parts:to a list of strings indentifying subwidgets to be displayed in this order.
Moreover, for every part listed this will map ‘part’ to a dict mapping
normal:to urwid.AttrSpec,
focus:to urwid.AttrSpec,
width:to a tuple indicating the width of the subpart. This is either (‘fit’, min, max) to force the widget to be at least min and at most max characters wide, or (‘weight’, n) which makes it share remaining space with other ‘weight’ parts.
alignment:where to place the content if shorter than the widget. This is either ‘right’, ‘left’ or ‘center’.

4.5.5. Accounts

class alot.account.Account(address=None, aliases=None, alias_regexp=None, realname=None, gpg_key=None, signature=None, signature_filename=None, signature_as_attachment=False, sent_box=None, sent_tags=None, draft_box=None, draft_tags=None, abook=None, sign_by_default=False, encrypt_by_default=u'none', **_)

Datastructure that represents an email account. It manages this account’s settings, can send and store mails to maildirs (drafts/send).


This is an abstract class that leaves send_mail() unspecified. See SendmailAccount for a subclass that uses a sendmail command to send out mails.


return all email addresses connected to this account, in order of their importance


sends given mail

Parameters:mail (email.message.Message or string) – the mail to send
Returns:a Deferred that errs back with a class:SendingMailFailed, containing a reason string if an error occured.

stores mail (email.message.Message or str) as draft if draft_box is set.

static store_mail(mbx, mail)

stores given mail in mailbox. If mailbox is maildir, set the S-flag and return path to newly added mail. Oherwise this will return None.


absolute path of mail-file for Maildir or None if mail was successfully stored

Return type:

str or None




stores mail (email.message.Message or str) in send-store if sent_box is set.

abook = None

addressbook (addressbook.AddressBook) managing this accounts contacts

address = None

this accounts main email address

alias_regexp = []

regex matching alternative addresses

aliases = []

list of alternative addresses

gpg_key = None

gpg fingerprint for this account’s private key

realname = None

real name used to format from-headers

signature = None

signature to append to outgoing mails

signature_as_attachment = None

attach signature file instead of appending its content to body text

signature_filename = None

filename of signature file in attachment

class alot.account.SendmailAccount(cmd, **kwargs)

Account that pipes a message to a sendmail shell command for sending

Parameters:cmd (str) – sendmail command to use for this account

4.5.6. Addressbooks

class alot.addressbook.AddressBook(ignorecase=True)

can look up email addresses and realnames for contacts.


This is an abstract class that leaves get_contacts() unspecified. See AbookAddressBook and ExternalAddressbook for implementations.


list all contacts tuples in this abook as (name, email) tuples


looks up all contacts where name or address match query

class alot.addressbook.abook.AbookAddressBook(path='~/.abook/addressbook', **kwargs)

AddressBook that parses abook’s config/database files

Parameters:path (str) – path to abook addressbook file
class alot.addressbook.external.ExternalAddressbook(commandline, regex, reflags=0, external_filtering=True, **kwargs)

AddressBook that parses a shell command’s output

  • commandline (str) – commandline
  • regex (str) – regular expression used to match contacts in commands output to stdout. Must define subparts named “email” and “name”.
  • reflags (str) – flags to use with regular expression. Use the constants defined in re here (re.IGNORECASE etc.)
  • external_filtering (bool) – if True the command is fired with the given search string as parameter and the result is not filtered further. If set to False, the command is fired without additional parameters and the result list is filtered according to the search string.