4.7. Commands¶
User actions are represented by Command
objects that can then be triggered by
alot.ui.UI.apply_command()
.
Command-line strings given by the user via the prompt or key bindings can be translated to
Command
objects using alot.commands.commandfactory()
.
Specific actions are defined as subclasses of Command
and can be registered
to a global command pool using the registerCommand
decorator.
Note
that the return value
of commandfactory()
depends on the current mode the user interface is in.
The mode identifier is a string that is uniquely defined by the currently focuses
Buffer
.
Note
The names of the commands available to the user in any given mode do not correspond one-to-one to these subclasses. You can register a Command multiple times under different names, with different forced constructor parameters and so on. See for instance the definition of BufferFocusCommand in ‘commands/globals.py’:
@registerCommand(MODE, 'bprevious', forced={'offset': -1},
help='focus previous buffer')
@registerCommand(MODE, 'bnext', forced={'offset': +1},
help='focus next buffer')
class BufferFocusCommand(Command):
def __init__(self, buffer=None, offset=0, **kwargs):
...
-
class
alot.commands.
Command
¶ base class for commands
-
apply
(caller)¶ code that gets executed when this command is applied
-
-
class
alot.commands.
CommandParseError
¶ could not parse commandline string
-
class
alot.commands.
CommandArgumentParser
(*args, **kwargs)¶ ArgumentParser
that raisesCommandParseError
instead of printing to sys.stderr
-
alot.commands.
commandfactory
(cmdline, mode='global')¶ parses cmdline and constructs a
Command
.Parameters: - cmdline (str) – command line to interpret
- mode (str) – mode identifier
-
alot.commands.
lookup_command
(cmdname, mode)¶ returns commandclass, argparser and forced parameters used to construct a command for cmdname when called in mode.
Parameters: - cmdname (str) – name of the command to look up
- mode (str) – mode identifier
Return type: (
Command
,ArgumentParser
, dict(str->dict))
-
alot.commands.
lookup_parser
(cmdname, mode)¶ returns the
CommandArgumentParser
used to construct a command for cmdname when called in mode.
-
class
alot.commands.
registerCommand
(mode, name, help=None, usage=None, forced=None, arguments=None)¶ Decorator used to register a
Command
as handler for command name in mode so that it can be looked up later usinglookup_command()
.Consider this example that shows how a
Command
class definition is decorated to register it as handler for ‘save’ in mode ‘thread’ and add boolean and string arguments:.. code-block::
- @registerCommand(‘thread’, ‘save’, arguments=[
- ([‘–all’], {‘action’: ‘store_true’, ‘help’:’save all’}), ([‘path’], {‘nargs’:’?’, ‘help’:’path to save to’})], help=’save attachment(s)’)
- class SaveAttachmentCommand(Command):
- pass
Parameters: - mode (str) – mode identifier
- name (str) – command name to register as
- help (str) – help string summarizing what this command does
- usage (str) – overides the auto generated usage string
- forced (dict (str->str)) – keyword parameter used for commands constructor
- arguments (list of (list of str, dict (str->str)) – list of arguments given as pairs (args, kwargs)
accepted by
argparse.ArgumentParser.add_argument()
.
4.7.1. Globals¶
-
class
alot.commands.globals.
BufferCloseCommand
(buffer=None, force=False, redraw=True, **kwargs)¶ close a buffer
Parameters: - buffer (alot.buffers.Buffer) – the buffer to close or None for current
- force (bool) – force buffer close
-
class
alot.commands.globals.
BufferFocusCommand
(buffer=None, index=None, offset=0, **kwargs)¶ focus a
Buffer
Parameters: - buffer (alot.buffers.Buffer) – the buffer to focus or None
- index (int) – index (in bufferlist) of the buffer to focus.
- offset (int) – position of the buffer to focus relative to the currently focussed one. This is used only if buffer is set to None
-
class
alot.commands.globals.
CallCommand
(command, **kwargs)¶ Executes python code
Parameters: command (str) – python command string to call
-
class
alot.commands.globals.
ComposeCommand
(envelope=None, headers=None, template=None, sender=u'', subject=u'', to=None, cc=None, bcc=None, attach=None, omit_signature=False, spawn=None, rest=None, encrypt=False, **kwargs)¶ compose a new email
Parameters: - envelope (
Envelope
) – use existing envelope - headers (dict (str->str)) – forced header values
- template (str) – name of template to parse into the envelope after creation. This should be the name of a file in your template_dir
- sender (str) – From-header value
- subject (str) – Subject-header value
- to (str) – To-header value
- cc (str) – Cc-header value
- bcc (str) – Bcc-header value
- attach (str) – Path to files to be attached (globable)
- omit_signature (bool) – do not attach/append signature
- spawn (bool) – force spawning of editor in a new terminal
- rest (list(str)) – remaining parameters. These can start with ‘mailto’ in which case it is interpreted as mailto string. Otherwise it will be interpreted as recipients (to) header
- encrypt (bool) – if the email should be encrypted
- envelope (
-
class
alot.commands.globals.
EditCommand
(path, spawn=None, thread=None, **kwargs)¶ edit a file
Parameters: - path (str) – path to the file to be edited
- spawn (bool) – force running edtor in a new terminal
- thread (bool) – run asynchronously, don’t block alot
-
class
alot.commands.globals.
ExitCommand
(_prompt=True, **kwargs)¶ Shut down cleanly.
The _prompt variable is for internal use only, it’s used to control prompting to close without sending, and is used by the BufferCloseCommand if settings change after yielding to the UI.
-
class
alot.commands.globals.
ExternalCommand
(cmd, stdin=None, shell=False, spawn=False, refocus=True, thread=False, on_success=None, **kwargs)¶ run external command
Parameters: - cmd (list or str) – the command to call
- stdin (file or str) – input to pipe to the process
- spawn (bool) – run command in a new terminal
- shell (bool) – let shell interpret command string
- thread (bool) – run asynchronously, don’t block alot
- refocus (bool) – refocus calling buffer after cmd termination
- on_success (callable) – code to execute after command successfully exited
-
class
alot.commands.globals.
FlushCommand
(callback=None, silent=False, **kwargs)¶ flush write operations or retry until committed
Parameters: callback (callable) – function to call after successful writeout
-
class
alot.commands.globals.
HelpCommand
(commandname='', **kwargs)¶ display help for a command. Use ‘bindings’ to display all keybings interpreted in current mode.’
Parameters: commandname (str) – command to document
-
class
alot.commands.globals.
MoveCommand
(movement=None, **kwargs)¶ move in widget
-
class
alot.commands.globals.
OpenBufferlistCommand
(filtfun=<function <lambda>>, **kwargs)¶ open a list of active buffers
Parameters: filtfun (callable (str->bool)) – filter to apply to displayed list
-
class
alot.commands.globals.
PromptCommand
(startwith='', **kwargs)¶ prompts for commandline and interprets it upon select
Parameters: startwith (str) – initial content of the prompt widget
-
class
alot.commands.globals.
PythonShellCommand
¶ open an interactive python shell for introspection
-
class
alot.commands.globals.
RefreshCommand
¶ refresh the current buffer
-
class
alot.commands.globals.
ReloadCommand
¶ Reload configuration.
-
class
alot.commands.globals.
RepeatCommand
(**kwargs)¶ Repeats the command executed last time
-
class
alot.commands.globals.
SearchCommand
(query, sort=None, **kwargs)¶ open a new search buffer. Search obeys the notmuch search.exclude_tags setting.
Parameters: - query (str) – notmuch querystring
- sort (str) – how to order results. Must be one of ‘oldest_first’, ‘newest_first’, ‘message_id’ or ‘unsorted’.
-
class
alot.commands.globals.
TagListCommand
(filtfun=<function <lambda>>, tags=None, **kwargs)¶ opens taglist buffer
Parameters: filtfun (callable (str->bool)) – filter to apply to displayed list
4.7.2. Envelope¶
-
class
alot.commands.envelope.
AttachCommand
(path, **kwargs)¶ attach files to the mail
Parameters: path (str) – files to attach (globable string)
-
class
alot.commands.envelope.
EditCommand
(envelope=None, spawn=None, refocus=True, **kwargs)¶ edit mail
Parameters: - envelope (
Envelope
) – email to edit - spawn (bool) – force spawning of editor in a new terminal
- refocus – m
- envelope (
-
class
alot.commands.envelope.
RefineCommand
(key='', **kwargs)¶ prompt to change the value of a header
Parameters: key (str) – key of the header to change
-
class
alot.commands.envelope.
SaveCommand
¶ save draft
-
class
alot.commands.envelope.
SendCommand
(mail=None, envelope=None, **kwargs)¶ send mail
Parameters: - mail – email to send
- envelope (alot.db.envelope.envelope) – envelope to use to construct the outgoing mail. This will be ignored in case the mail parameter is set.
-
class
alot.commands.envelope.
SetCommand
(key, value, append=False, **kwargs)¶ set header value
Parameters: - key (str) – key of the header to change
- value (str) – new value
-
class
alot.commands.envelope.
SignCommand
(action=None, keyid=None, **kwargs)¶ toggle signing this email
Parameters: - action (str) – whether to sign/unsign/toggle
- keyid (str) – which key id to use
-
class
alot.commands.envelope.
TagCommand
(tags=u'', action='add', **kwargs)¶ manipulate message tags
Parameters: - tags (unicode) – comma separated list of tagstrings to set
- action (str) – adds tags if ‘add’, removes them if ‘remove’, adds tags and removes all other if ‘set’ or toggle individually if ‘toggle’
-
class
alot.commands.envelope.
ToggleHeaderCommand
¶ toggle display of all headers
-
class
alot.commands.envelope.
UnattachCommand
(hint=None, **kwargs)¶ remove attachments from current envelope
Parameters: hint (str) – which attached file to remove
-
class
alot.commands.envelope.
UnsetCommand
(key, **kwargs)¶ remove header field
Parameters: key (str) – key of the header to remove
4.7.3. Bufferlist¶
-
class
alot.commands.bufferlist.
BufferCloseCommand
¶ close focussed buffer
-
class
alot.commands.bufferlist.
BufferFocusCommand
¶ focus selected buffer
4.7.4. Search¶
-
class
alot.commands.search.
OpenThreadCommand
(thread=None, **kwargs)¶ open thread in a new buffer
Parameters: thread ( Thread
) – thread to open (Uses focussed thread if unset)
-
class
alot.commands.search.
RefineCommand
(query=None, sort=None, **kwargs)¶ refine the querystring of this buffer
Parameters: query (list of str) – new querystring given as list of strings as returned by argparse
-
class
alot.commands.search.
RefinePromptCommand
¶ prompt to change this buffers querystring
-
class
alot.commands.search.
RetagPromptCommand
¶ prompt to retag selected threads’ tags
-
class
alot.commands.search.
TagCommand
(tags=u'', action='add', allmessages=False, flush=True, **kwargs)¶ manipulate message tags
Parameters: - tags (str) – comma separated list of tagstrings to set
- action (str) – adds tags if ‘add’, removes them if ‘remove’, adds tags and removes all other if ‘set’ or toggle individually if ‘toggle’
- allmessages (bool) – tag all messages in search result
- flush (bool) – imediately write out to the index
4.7.5. Taglist¶
-
class
alot.commands.taglist.
TaglistSelectCommand
¶ search for messages with selected tag
4.7.6. Thread¶
-
class
alot.commands.thread.
BounceMailCommand
(message=None, **kwargs)¶ directly re-send selected message
Parameters: message (alot.db.message.Message) – message to bounce (defaults to selected message)
-
class
alot.commands.thread.
ChangeDisplaymodeCommand
(query=None, visible=None, raw=None, all_headers=None, **kwargs)¶ fold or unfold messages
Parameters: - query (str) – notmuch query string used to filter messages to affect
- visible (True, False, 'toggle' or None) – unfold if True, fold if False, ignore if None
- raw (True, False, 'toggle' or None) – display raw message text.
- all_headers (True, False, 'toggle' or None) – show all headers (only visible if not in raw mode)
-
class
alot.commands.thread.
EditNewCommand
(message=None, spawn=None, **kwargs)¶ edit message in as new
Parameters: - message (alot.db.message.Message) – message to reply to (defaults to selected message)
- spawn (bool) – force spawning of editor in a new terminal
-
class
alot.commands.thread.
ForwardCommand
(message=None, attach=True, spawn=None, **kwargs)¶ forward message
Parameters: - message (alot.db.message.Message) – message to forward (defaults to selected message)
- attach (bool) – attach original mail instead of inline quoting its body
- spawn (bool) – force spawning of editor in a new terminal
-
class
alot.commands.thread.
OpenAttachmentCommand
(attachment, **kwargs)¶ displays an attachment according to mailcap
Parameters: attachment ( Attachment
) – attachment to open
-
class
alot.commands.thread.
PipeCommand
(cmd, all=False, separately=False, background=False, shell=False, notify_stdout=False, format='raw', add_tags=False, noop_msg='no command specified', confirm_msg='', done_msg=None, field_key='copiousoutput', **kwargs)¶ pipe message(s) to stdin of a shellcommand
Parameters: - cmd (str or list of str) – shellcommand to open
- all (bool) – pipe all, not only selected message
- separately (bool) – call command once per message
- background (bool) – do not suspend the interface
- notify_stdout (bool) – display command’s stdout as notification message
- shell – let the shell interpret the command
- add_tags (bool) – add ‘Tags’ header to the message
- noop_msg (str) – error notification to show if cmd is empty
- confirm_msg (str) – confirmation question to ask (continues directly if unset)
- done_msg (str) – notification message to show upon success
- field_key (str) – malcap field key for decoding
-
class
alot.commands.thread.
PrintCommand
(all=False, separately=False, raw=False, add_tags=False, **kwargs)¶ print message(s)
Parameters: - all (bool) – print all, not only selected messages
- separately (bool) – call print command once per message
- raw (bool) – pipe raw message string to print command
- add_tags (bool) – add ‘Tags’ header to the message
-
class
alot.commands.thread.
RemoveCommand
(all=False, **kwargs)¶ remove message(s) from the index
Parameters: all (bool) – remove all messages from thread, not just selected one
-
class
alot.commands.thread.
ReplyCommand
(message=None, all=False, listreply=None, spawn=None, **kwargs)¶ reply to message
Parameters: - message (alot.db.message.Message) – message to reply to (defaults to selected message)
- all (bool) – group reply; copies recipients from Bcc/Cc/To to the reply
- listreply (bool) – reply to list; autodetect if unset and enabled in config
- spawn (bool) – force spawning of editor in a new terminal
-
static
clear_my_address
(my_addresses, value)¶ return recipient header without the addresses in my_addresses
Parameters: - my_addresses (list(str)) – a list of my email addresses (no real name part)
- value (list(str)) – a list of recipient or sender strings (with or without real names as taken from email headers)
Returns: a new, potentially shortend list
Return type: list(str)
-
static
ensure_unique_address
(recipients)¶ clean up a list of name,address pairs so that no address appears multiple times.
-
class
alot.commands.thread.
SaveAttachmentCommand
(all=False, path=None, **kwargs)¶ save attachment(s)
Parameters: - all (bool) – save all, not only selected attachment
- path (str) – path to write to. if all is set, this must be a directory.
-
class
alot.commands.thread.
TagCommand
(tags=u'', action='add', all=False, flush=True, **kwargs)¶ manipulate message tags
Parameters: - tags (str) – comma separated list of tagstrings to set
- action (str) – adds tags if ‘add’, removes them if ‘remove’, adds tags and removes all other if ‘set’ or toggle individually if ‘toggle’
- all (bool) – tag all messages in thread
- flush (bool) – imediately write out to the index
-
class
alot.commands.thread.
ThreadSelectCommand
¶ select focussed element. The fired action depends on the focus: - if message summary, this toggles visibility of the message, - if attachment line, this opens the attachment
-
alot.commands.thread.
determine_sender
(mail, action='reply')¶ Inspect a given mail to reply/forward/bounce and find the most appropriate account to act from and construct a suitable From-Header to use.
Parameters: - mail (email.message.Message) – the email to inspect
- action (str) – intended use case: one of “reply”, “forward” or “bounce”