User Interface

Alot sets up a widget tree and an mainloop in the constructor of alot.ui.UI. The visible area is a urwid.Frame, where the footer is used as a status line and the body part displays the currently active alot.buffers.Buffer.

To be able to bind keystrokes and translate them to Commands, keypresses are not propagated down the widget tree as is customary in urwid. Instead, the root widget given to urwids mainloop is a custom wrapper (alot.ui.Inputwrap) that interprets key presses. A dedicated SendKeypressCommand can be used to trigger key presses to the wrapped root widget and thereby accessing standard urwid behaviour.

In order to keep the interface non-blocking, alot makes use of twisted’s deferred - a framework that makes it easy to deal with callbacks. Many commands in alot make use of inline callbacks, which allow you to treat deferred-returning functions almost like syncronous functions. Consider the following example of a function that prompts for some input and acts on it:

from twisted.internet import defer

def greet(ui):  # ui is instance of alot.ui.UI
    name = yield ui.prompt(prefix='pls enter your name>')
    ui.notify('your name is: ' + name)

UI - the main component

class alot.ui.UI(dbman, log, accountman, initialcmd, colourmode)

This class integrates all components of alot and offers methods for user interaction like prompt(), notify() etc. It handles the urwid widget tree and mainloop (we use twisted) and is responsible for opening, closing and focussing buffers.

  • dbmanDBManager
  • loglogging.Logger
  • accountmanAccountManager
  • initialcmd (str) – commandline applied after setting up interface
  • colourmode (int in [1,16,256]) – determines which theme to chose
buffers = []

list of active buffers

current_buffer = None

points to currently active Buffer

dbman = None

Database manager (DBManager)

logger = None

logging.Logger used to write to log file

accountman = None

account manager (AccountManager)


applies a command

This calls the pre and post hooks attached to the command, as well as cmd.apply().

Parameters:cmd (Command) – an applicable command
prompt(prefix='>', text=u'', completer=None, tab=0, history=[])

prompt for text input

  • prefix (str) – text to print before the input field
  • text (str) – initial content of the input field
  • completer (alot.completion.Completer()) – completion object to use
  • tab (int) – number of tabs to press initially (to select completion results)
  • history (list of str) – history to be used for up/down keys

a twisted.defer.Deferred

choice(message, choices={'y': 'yes', 'n': 'no'}, select=None, cancel=None, msg_position='above')

prompt user to make a choice

  • message (unicode) – string to display before list of choices
  • choices (dict: keymap->choice (both str)) – dict of possible choices
  • select (str) – choice to return if enter/return is hit. Ignored if set to None.
  • cancel (str) – choice to return if escape is hit. Ignored if set to None.
  • msg_position (str) – determines if message is above or left of the prompt. Must be above or left.

a twisted.defer.Deferred

notify(message, priority='normal', timeout=0, block=False)

opens notification popup

  • message (str) – message to print
  • priority (str) – priority string, used to format the popup: currently, ‘normal’ and ‘error’ are defined. If you use ‘X’ here, the attribute ‘global_notify_X’ is used to format the popup.
  • timeout (int) – seconds until message disappears. Defaults to the value of ‘notify_timeout’ in the general config section. A negative value means never time out.
  • block (bool) – this notification blocks until a keypress is made

an urwid widget (this notification) that can be handed to clear_notify() for removal


clears notification popups. Call this to ged rid of messages that don’t time out.

Parameters:messages – The popups to remove. This should be exactly what notify() returned when creating the popup

register and focus new Buffer.


focus given Buffer.


closes given Buffer.

This it removes it from the bufferlist and calls its cleanup() method.


returns currently open buffers for a given subclass of alot.buffer.Buffer


A buffer defines a view to your data. It knows how to render itself, to interpret keypresses and is visible in the “body” part of the widget frame. Different modes are defined by subclasses of the following base class.

class alot.buffers.Buffer(ui, widget, name)

Abstract base class for buffers.


tells the buffer to (re)construct its visible content.


called before buffer is dismissed

Available modes are:

Mode Buffer Subclass
search SearchBuffer
thread ThreadBuffer
bufferlist BufferlistBuffer
taglist TagListBuffer
envelope EnvelopeBuffer
class alot.buffers.BufferlistBuffer(ui, filtfun=None)

selectable list of active buffers


returns the index of Buffer b in the global list of active buffers.


returns currently selected Buffer element from list

class alot.buffers.EnvelopeBuffer(ui, envelope)

message composition mode


toggles visibility of all envelope headers

class alot.buffers.SearchBuffer(ui, initialquery='')

shows a result set for a Thread query, one line per Thread


terminates the process that fills this buffers PipeWalker.


returns curently focussed alot.widgets.ThreadlineWidget from the result list.


returns currently selected Thread

class alot.buffers.ThreadBuffer(ui, thread)

shows a single mailthread as a (collapsible) tree of MessageWidgets.


returns the displayed Thread


returns focussed MessageWidget


returns focussed Message


returns all MessageWidgets displayed in this thread-tree.


unfolds those MessageWidgets that represent Messages matching querystring.

class alot.buffers.TagListBuffer(ui, alltags=[], filtfun=None)

selectable list of tagstrings present in the database


returns selected tagstring


What follows is a list of the non-standard urwid widgets used in alot. Some of them respect user settings, themes in particular.

class alot.widgets.ThreadlineWidget(tid, dbman)

selectable line widget that represents a Thread in the SearchBuffer.

Respected settings:
  • general.display_content_in_threadline
  • general.timestamp_format
  • general.authors_maxlength
Theme settings:
  • search_thread, search_thread_focus
  • search_thread_date, search_thread_date_focus
  • search_thread_mailcount, search_thread_mailcount_focus
  • search_thread_authors, search_thread_authors_focus
  • search_thread_subject, search_thread_subject_focus
  • search_thread_content, search_thread_content_focus
class alot.widgets.BufferlineWidget(buffer)

selectable text widget that represents a Buffer in the BufferlistBuffer.

class alot.widgets.TagWidget(tag)

text widget that renders a tagstring.

It looks up the string it displays in the tag-translate section of the config as well as custom theme settings for its tag.

class alot.widgets.MessageWidget(message, even=False, folded=True, depth=0, bars_at=[])

Flow widget that renders a Message.

Respected settings:
  • general.displayed_headers
  • message (alot.db.Message) – the message to display
  • even (bool) – use messagesummary_even theme for summary
  • folded (bool) – fold message initially
  • depth (int) – number of characters to shift content to the right
  • bars_at (list(bool)) – defines for each column of the indentation whether to use a vertical bar instead of a space.

toggles if message headers are shown


get contained :class`~alot.message.Message`


get contained email

class alot.widgets.MessageSummaryWidget(message, even=True)

one line summary of a Message.

Theme settings:
  • thread_summary_even
  • thread_summary_odd
  • thread_summary_focus
  • message (alot.db.Message) – a message
  • even (bool) – even entry in a pile of messages? Used for theming.
class alot.widgets.HeadersList(headerslist)

renders a pile of header values as key/value list

Theme settings:
  • thread_header
  • thread_header_key
  • thread_header_value
class alot.widgets.MessageBodyWidget(msg)

displays printable parts of an email

Theme settings:
  • thread_body
class alot.widgets.AttachmentWidget(attachment, selectable=True)

one-line summary of an Attachment.

Theme settings:
  • thread_attachment
  • thread_attachment_focus


alot.ui.UI.prompt() allows tab completion using a Completer object handed as ‘completer’ parameter. alot.completion defines several subclasses for different occasions like completing email addresses from an AddressBook, notmuch tagstrings. Some of these actually build on top of each other; the QueryCompleter for example uses a TagsCompleter internally to allow tagstring completion after “is:” or “tag:” keywords when typing a notmuch querystring.

All these classes overide the method complete, which for a given string and cursor position in that string returns a list of tuples (completed_string, new_cursor_position) that are taken to be the completed values. Note that completed_string does not need to have the original string as prefix.

class alot.completion.Completer

base class for completers

complete(original, pos)

returns a list of completions and cursor positions for the string original from position pos on.

  • original (str) – the string to complete
  • pos – starting position to complete from

pairs of completed string and cursor position in the new string

Return type:

list of (str, int)

relevant_part(original, pos, sep=' ')

calculates the subword in a sep-splitted list of substrings of original that pos is ia.n

class alot.completion.QueryCompleter(dbman, accountman)

completion for a notmuch query string

  • dbman (DBManager) – used to look up avaliable tagstrings
  • accountman (AccountManager) – used to look up known addresses to complete ‘from’ and ‘to’ queries
class alot.completion.TagsCompleter(dbman)

completion for a comma separated list of tagstrings

Parameters:dbman (DBManager) – used to look up avaliable tagstrings
class alot.completion.ContactsCompleter(abooks, addressesonly=False)

completes contacts

  • abooks (list of AddresBook) – used to look up email addresses
  • addressesonly (bool) – only insert address, not the realname of the contact
class alot.completion.AccountCompleter(accountman)

completes users’ own mailaddresses

Parameters:accountman (AccountManager) – used to look up the list of addresses
class alot.completion.CommandCompleter(mode)

completes commands

Parameters:mode (str) – mode identifier
class alot.completion.CommandLineCompleter(dbman, accountman, mode)

completion for commandline

  • dbman (DBManager) – used to look up avaliable tagstrings
  • accountman (AccountManager) – used to look up known addresses to complete ‘from’ and ‘to’ queries
  • mode (str) – mode identifier
class alot.completion.PathCompleter

completion for paths

Project Versions

Table Of Contents

Previous topic

Email Database

Next topic

Accessing User Settings