# 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