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 raises CommandParseError
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
|
>>> cmd = alot.commands.commandfactory('save --all /foo', mode='thread')
>>> cmd
<alot.commands.thread.SaveAttachmentCommand object at 0x272cf10
>>> cmd.all
True
>>> cmd.path
u'/foo'
-
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))
|
>>> (cmd, parser, kwargs) = lookup_command('save', 'thread')
>>> cmd
<class 'alot.commands.thread.SaveAttachmentCommand'>
-
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={}, arguments=[])
Decorator used to register a Command as
handler for command name in mode so that it
can be looked up later using lookup_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:
@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.CommandSequenceCommand(cmdline='', **kwargs)
Meta-Command that just applies a sequence of given Commands in order
-
class alot.commands.globals.ComposeCommand(envelope=None, headers={}, template=None, sender=u'', subject=u'', to=[], cc=[], bcc=[], attach=None, omit_signature=False, spawn=None, **kwargs)
compose a new email
Parameters: |
- envelope (Envelope) – use existing envelope
- headers – 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
|
-
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
shut down cleanly
-
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=None, **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.RepeatCommand(**kwargs)
Repeats the command executed last time
-
class alot.commands.globals.SearchCommand(query, sort=None, **kwargs)
open a new search buffer
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=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=None, **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
|
-
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.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’
- all (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, **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
|
-
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, 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
- spawn (bool) – force spawning of editor in a new terminal
|
-
clear_my_address(my_addresses, value)
return recipient header without the addresses in my_addresses
-
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”
|