docs/source/configuration/hooks.rst
.. _config.hooks:
Hooks
=====
Hooks are python callables that live in a module specified by `hooksfile` in
the config. Per default this points to :file:`~/.config/alot/hooks.py`.
Pre/Post Command Hooks
----------------------
For every :ref:`COMMAND <usage.commands>` in mode :ref:`MODE <modes>`, the
callables :func:`pre_MODE_COMMAND` and :func:`post_MODE_COMMAND` -- if defined
-- will be called before and after the command is applied respectively. In
addition callables :func:`pre_global_COMMAND` and :func:`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:
.. py:function:: pre_envelope_send(ui=None, dbm=None, cmd=None)
:param ui: the main user interface
:type ui: :class:`alot.ui.UI`
:param dbm: a database manager
:type dbm: :class:`alot.db.manager.DBManager`
:param cmd: the Command instance that is being called
:type cmd: :class:`alot.commands.Command`
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!')
Other Hooks
-----------
Apart from command pre- and posthooks, the following hooks will be interpreted:
.. py:function:: 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
:param realname: name or the original sender
:type realname: str
:param address: address of the sender
:type address: str
:param timestamp: value of the Date header of the replied message
:type timestamp: :obj:`datetime.datetime`
:param message: message object attached to reply
:type message: :obj:`email.Message`
:rtype: string
.. py:function:: 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
:param realname: name or the original sender
:type realname: str
:param address: address of the sender
:type address: str
:param timestamp: value of the Date header of the replied message
:type timestamp: :obj:`datetime.datetime`
:param message: message object being forwarded
:type message: :obj:`email.Message`
:rtype: string
.. _pre-edit-translate:
.. py:function:: 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
:ref:`edit_headers_whitelist <edit-headers-whitelist>` and
:ref:`edit_header_blacklist <edit-headers-blacklist>`.
:param text: text representation of mail as displayed in the interface and
as sent to the editor
:type text: str
:rtype: str
.. py:function:: post_edit_translate(text[, ui= None, dbm=None])
used to manipulate a message's text *after* the editor is called, also see
:ref:`pre_edit_translate <pre-edit-translate>`
:param text: text representation of mail as displayed in the interface and
as sent to the editor
:type text: str
:rtype: str
.. py:function:: text_quote(message)
used to transform a message into a quoted one
:param message: message to be quoted
:type message: str
:rtype: str
.. py:function:: timestamp_format(timestamp)
represents given timestamp as string
:param timestamp: timestamp to represent
:type timestamp: `datetime`
:rtype: str
.. py:function:: touch_external_cmdlist(cmd, shell=shell, spawn=spawn, thread=thread)
used to change external commands according to given flags shortly
before they are called.
:param cmd: command to be called
:type cmd: list of str
:param shell: is this to be interpreted by the shell?
:type shell: bool
:param spawn: should be spawned in new terminal/environment
:type spawn: bool
:param threads: should be called in new thread
:type thread: bool
:returns: triple of amended command list, shell and thread flags
:rtype: list of str, bool, bool
.. py:function:: reply_subject(subject)
used to reformat the subject header on reply
:param subject: subject to reformat
:type subject: str
:rtype: str
.. py:function:: forward_subject(subject)
used to reformat the subject header on forward
:param subject: subject to reformat
:type subject: str
:rtype: str
.. py:function:: pre_buffer_open(ui= None, dbm=None, buf=buf)
run before a new buffer is opened
:param buf: buffer to open
:type buf: alot.buffer.Buffer
.. py:function:: post_buffer_open(ui=None, dbm=None, buf=buf)
run after a new buffer is opened
:param buf: buffer to open
:type buf: alot.buffer.Buffer
.. py:function:: pre_buffer_close(ui=None, dbm=None, buf=buf)
run before a buffer is closed
:param buf: buffer to open
:type buf: alot.buffer.Buffer
.. py:function:: post_buffer_close(ui=None, dbm=None, buf=buf, success=success)
run after a buffer is closed
:param buf: buffer to open
:type buf: alot.buffer.Buffer
:param success: true if successfully closed buffer
:type success: boolean
.. py:function:: pre_buffer_focus(ui=None, dbm=None, buf=buf)
run before a buffer is focused
:param buf: buffer to open
:type buf: alot.buffer.Buffer
.. py:function:: post_buffer_focus(ui=None, dbm=None, buf=buf, success=success)
run after a buffer is focused
:param buf: buffer to open
:type buf: alot.buffer.Buffer
:param success: true if successfully focused buffer
:type success: boolean
.. py:function:: exit()
run just before the program exits
.. py:function:: 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.
:param filename: filename provided in the email (can be None)
:type filename: str or None
:param prefix: prefix string as found on mailcap
:type prefix: str
:param suffix: suffix string as found on mailcap
:type suffix: str
:returns: tuple of `prefix` and `suffix`
:rtype: (str, str)
.. py:function:: loop_hook(ui=None)
Run on a period controlled by :ref:`_periodic_hook_frequency <periodic-hook-frequency>`
:param ui: the main user interface
:type ui: :class:`alot.ui.UI`