3.5. Hooks

Hooks are python callables that live in a module specified by hooksfile in the config.

Added in version 0.11: in newer versions of alot, hooksfile does not default to ~/.config/alot/hooks.py but instead needs to be explicitly set if you want to use hooks.

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