3.5. Hooks

Hooks are python callables that live in a module specified by hooksfile in the config. Per default this points to ~/.config/alot/hooks.py.

3.5.1. Pre/Post Command Hooks

For every COMMAND in mode MODE, the callables pre_MODE_COMMAND() and post_MODE_COMMAND() – if defined – will be called before and after the command is applied respectively. In addition callables pre_global_COMMAND() and post_global_COMMAND() can be used. They will be called if no specific hook function for a mode is defined. The signature for the pre-send hook in envelope mode for example looks like this:

pre_envelope_send(ui=None, dbm=None, cmd=None)
Parameters:
  • ui (alot.ui.UI) – the main user interface
  • dbm (alot.db.manager.DBManager) – a database manager
  • cmd (alot.commands.Command) – the Command instance that is being called

Consider this pre-hook for the exit command, that logs a personalized goodbye message:

import logging
from alot.settings.const import settings
def pre_global_exit(**kwargs):
    accounts = settings.get_accounts()
    if accounts:
        logging.info('goodbye, %s!' % accounts[0].realname)
    else:
        logging.info('goodbye!')

3.5.2. Other Hooks

Apart from command pre- and posthooks, the following hooks will be interpreted:

reply_prefix(realname, address, timestamp[, message=None, ui= None, dbm=None])

Is used to reformat the first indented line in a reply message. This defaults to ‘Quoting %s (%s)n’ % (realname, timestamp)’ unless this hook is defined

Parameters:
  • realname (str) – name or the original sender
  • address (str) – address of the sender
  • timestamp (datetime.datetime) – value of the Date header of the replied message
  • message (email.Message) – message object attached to reply
Return type:

string

forward_prefix(realname, address, timestamp[, message=None, ui= None, dbm=None])

Is used to reformat the first indented line in a inline forwarded message. This defaults to ‘Forwarded message from %s (%s)n’ % (realname, timestamp)’ if this hook is undefined

Parameters:
  • realname (str) – name or the original sender
  • address (str) – address of the sender
  • timestamp (datetime.datetime) – value of the Date header of the replied message
  • message (email.Message) – message object being forwarded
Return type:

string

pre_edit_translate(text[, ui= None, dbm=None])

Used to manipulate a message’s text before the editor is called. The text might also contain some header lines, depending on the settings edit_headers_whitelist and edit_header_blacklist.

Parameters:text (str) – text representation of mail as displayed in the interface and as sent to the editor
Return type:str
post_edit_translate(text[, ui= None, dbm=None])

used to manipulate a message’s text after the editor is called, also see pre_edit_translate

Parameters:text (str) – text representation of mail as displayed in the interface and as sent to the editor
Return type:str
text_quote(message)

used to transform a message into a quoted one

Parameters:message (str) – message to be quoted
Return type:str
timestamp_format(timestamp)

represents given timestamp as string

Parameters:timestamp (datetime) – timestamp to represent
Return type:str
touch_external_cmdlist(cmd, shell=shell, spawn=spawn, thread=thread)

used to change external commands according to given flags shortly before they are called.

Parameters:
  • cmd (list of str) – command to be called
  • shell (bool) – is this to be interpreted by the shell?
  • spawn (bool) – should be spawned in new terminal/environment
  • threads – should be called in new thread
Returns:

triple of amended command list, shell and thread flags

Return type:

list of str, bool, bool

reply_subject(subject)

used to reformat the subject header on reply

Parameters:subject (str) – subject to reformat
Return type:str
forward_subject(subject)

used to reformat the subject header on forward

Parameters:subject (str) – subject to reformat
Return type:str
pre_buffer_open(ui= None, dbm=None, buf=buf)

run before a new buffer is opened

Parameters:buf (alot.buffer.Buffer) – buffer to open
post_buffer_open(ui=None, dbm=None, buf=buf)

run after a new buffer is opened

Parameters:buf (alot.buffer.Buffer) – buffer to open
pre_buffer_close(ui=None, dbm=None, buf=buf)

run before a buffer is closed

Parameters:buf (alot.buffer.Buffer) – buffer to open
post_buffer_close(ui=None, dbm=None, buf=buf, success=success)

run after a buffer is closed

Parameters:
  • buf (alot.buffer.Buffer) – buffer to open
  • success (boolean) – true if successfully closed buffer
pre_buffer_focus(ui=None, dbm=None, buf=buf)

run before a buffer is focused

Parameters:buf (alot.buffer.Buffer) – buffer to open
post_buffer_focus(ui=None, dbm=None, buf=buf, success=success)

run after a buffer is focused

Parameters:
  • buf (alot.buffer.Buffer) – buffer to open
  • success (boolean) – true if successfully focused buffer
exit()

run just before the program exits

sanitize_attachment_filename(filename=None, prefix='', suffix='')

returns prefix and suffix for a sanitized filename to use while opening an attachment. The prefix and suffix are used to open a file named prefix + XXXXXX + suffix in a temporary directory.

Parameters:
  • filename (str or None) – filename provided in the email (can be None)
  • prefix (str) – prefix string as found on mailcap
  • suffix (str) – suffix string as found on mailcap
Returns:

tuple of prefix and suffix

Return type:

(str, str)

loop_hook(ui=None)

Run on a period controlled by _periodic_hook_frequency

Parameters:ui (alot.ui.UI) – the main user interface