4.6. 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(ui)¶
code that gets executed when this command is applied
- class alot.commands.CommandParseError¶
could not parse commandline string
- class alot.commands.CommandArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)¶
ArgumentParserthat raisesCommandParseErrorinstead of printing to sys.stderr
- alot.commands.lookup_command(cmdname, mode)¶
returns commandclass, argparser and forced parameters used to construct a command for cmdname when called in mode.
- Parameters:
- Return type:
(
Command,ArgumentParser, dict(str->dict))
- alot.commands.lookup_parser(cmdname, mode)¶
returns the
CommandArgumentParserused 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
Commandas handler for command name in mode so that it can be looked up later usinglookup_command().Consider this example that shows how a
Commandclass 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.6.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
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.BufferFocusCommand(buffer=None, index=None, offset=0, **kwargs)¶
focus a
Buffer- Parameters:
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.CallCommand(command, **kwargs)¶
execute python code
- Parameters:
command (str) – python command string to call
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.ComposeCommand(envelope=None, headers=None, template=None, sender='', tags=None, subject='', 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 envelopeheaders (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
tags (list(str)) – Comma-separated list of tags to apply to message
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
- exception ApplyError¶
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.ConfirmCommand(msg=None, **kwargs)¶
Prompt user to confirm a sequence of commands.
- Parameters:
msg (List[str]) – Additional message to prompt the user with
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.EditCommand(path, spawn=None, thread=None, **kwargs)¶
edit a file
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.ExitCommand(_prompt=True, **kwargs)¶
Shut down cleanly.
- Parameters:
_prompt (bool) – For internal use only, used to control prompting to close without sending, and is used by the BufferCloseCommand if settings change after yielding to the UI.
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.ExternalCommand(cmd, stdin=None, shell=False, spawn=False, refocus=True, thread=False, on_success=None, **kwargs)¶
run external command
- Parameters:
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
- async apply(ui)¶
code that gets executed when this command is applied
- 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
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.HelpCommand(commandname='', **kwargs)¶
display help for a command (use ‘bindings’ to display all keybindings interpreted in current mode)
- Parameters:
commandname (str) – command to document
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.MoveCommand(movement=None, **kwargs)¶
move in widget
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.NamedQueriesCommand(filtfun=<class 'bool'>, **kwargs)¶
opens named queries buffer
- Parameters:
filtfun (callable (str->bool)) – filter to apply to displayed list
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.OpenBufferlistCommand(filtfun=<function OpenBufferlistCommand.<lambda>>, **kwargs)¶
open a list of active buffers
- Parameters:
filtfun (callable (str->bool)) – filter to apply to displayed list
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.PromptCommand(startwith='', **kwargs)¶
prompts for commandline and interprets it upon select
- Parameters:
startwith (str) – initial content of the prompt widget
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.PythonShellCommand¶
open an interactive python shell for introspection
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.RefreshCommand¶
refresh the current buffer
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.ReloadCommand¶
Reload configuration.
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.RemoveQueryCommand(alias, flush=True, **kwargs)¶
remove named query string for given alias
- Parameters:
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.RepeatCommand(**kwargs)¶
repeat the command executed last time
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.SaveQueryCommand(alias, query=None, flush=True, **kwargs)¶
save alias for query string
- Parameters:
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.globals.SearchCommand(query, sort=None, **kwargs)¶
open a new search buffer. Search obeys the notmuch search.exclude_tags setting.
- Parameters:
- apply(ui)¶
code that gets executed when this command is applied
4.6.2. Envelope¶
- class alot.commands.envelope.AttachCommand(path, **kwargs)¶
attach files to the mail
- Parameters:
path (str) – files to attach (globable string)
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.BodyConvertCommand(action=None, cmd=None)¶
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.ChangeDisplaymodeCommand(part=None, **kwargs)¶
change wich body alternative is shown
- Parameters:
part – which part to show
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.DetachCommand(files=None, **kwargs)¶
remove attachments from current envelope
- Parameters:
files (str) – attached file glob to remove
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.EditCommand(envelope=None, spawn=None, refocus=True, part=None, **kwargs)¶
edit mail
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.EncryptCommand(action=None, keyids=None, trusted=False, **kwargs)¶
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.RefineCommand(key='', **kwargs)¶
prompt to change the value of a header
- Parameters:
key (str) – key of the header to change
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.RemoveHtmlCommand¶
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.SaveCommand¶
save draft
- async apply(ui)¶
code that gets executed when this command is applied
- 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.
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.SetCommand(key, value, append=False, **kwargs)¶
set header value
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.SignCommand(action=None, keyid=None, **kwargs)¶
toggle signing this email
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.envelope.TagCommand(tags='', action='add', **kwargs)¶
manipulate message tags
- Parameters:
- apply(ui)¶
code that gets executed when this command is applied
4.6.3. Bufferlist¶
4.6.4. Search¶
- class alot.commands.search.MoveFocusCommand(movement=None, **kwargs)¶
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.search.OpenThreadCommand(thread=None, all_folded=False, **kwargs)¶
open thread in a new buffer
- Parameters:
thread (
Thread) – thread to open (Uses focussed thread if unset)
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.search.RefineCommand(query=None, sort=None, **kwargs)¶
refine the querystring of this buffer
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.search.RefinePromptCommand¶
prompt to change this buffers querystring
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.search.SaveQueryCommand(alias, query=None, flush=True, **kwargs)¶
- Parameters:
- apply(ui)¶
code that gets executed when this command is applied
4.6.5. Taglist¶
4.6.6. Namedqueries¶
4.6.7. 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)
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.ChangeDisplaymodeCommand(query=None, visible=None, raw=None, all_headers=None, indent=None, mimetree=None, mimepart=False, **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)
indent ('+', '-', or int) – message/reply indentation
mimetree (True, False, 'toggle' or None) – show the mime tree of the message
- apply(ui)¶
code that gets executed when this command is applied
- 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
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.ForwardCommand(message=None, attach=True, spawn=None, **kwargs)¶
forward message
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.MoveFocusCommand(movement=None, **kwargs)¶
- apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.OpenAttachmentCommand(attachment, **kwargs)¶
displays an attachment according to mailcap
- Parameters:
attachment (
Attachment) – attachment to open
- async apply(ui)¶
code that gets executed when this command is applied
- 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:
all (bool) – pipe all, not only selected message
separately (bool) – call command once per message
background (bool) – do not suspend the interface
shell (bool) – let the shell interpret the command
notify_stdout (bool) – display command’s stdout as notification message
format (str) – what to pipe to the processes stdin. one of: ‘raw’: message content as is, ‘decoded’: message content, decoded quoted printable, ‘id’: message ids, separated by newlines, ‘filepath’: paths to message files on disk
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
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.PrintCommand(all=False, separately=False, raw=False, add_tags=False, **kwargs)¶
print message(s)
- 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
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.ReplyCommand(message=None, all=False, listreply=None, spawn=None, **kwargs)¶
reply to message
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.SaveAttachmentCommand(all=False, path=None, **kwargs)¶
save attachment(s)
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.TagCommand(tags='', action='add', all=False, flush=True, **kwargs)¶
manipulate message tags
- Parameters:
- async apply(ui)¶
code that gets executed when this command is applied
- class alot.commands.thread.ThreadSelectCommand¶
select focussed element: - if it is a message summary, toggle visibility of the message; - if it is an attachment line, open the attachment - if it is a mimepart, toggle visibility of the mimepart
- async apply(ui)¶
code that gets executed when this command is applied
- 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”