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)¶ 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.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
-
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: - 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
-
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 -
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 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
- 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
¶
-
apply
(ui)¶ code that gets executed when this command is applied
- envelope (
-
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 -
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: - 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
-
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. -
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: - 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
-
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 -
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: - alias (str) – name to use for query string
- flush (bool) – immediately write out to the index
-
apply
(ui)¶ code that gets executed when this command is applied
-
class
alot.commands.globals.
RepeatCommand
(**kwargs)¶ repeat the command executed last time
-
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: - alias (str) – name to use for query string
- query (str or None) – query string to save
- flush (bool) – immediately write out to the index
-
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: - query (str) – notmuch querystring
- sort (str) – how to order results. Must be one of ‘oldest_first’, ‘newest_first’, ‘message_id’ or ‘unsorted’.
-
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 -
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: - envelope (
Envelope
) – email to edit - spawn (bool) – force spawning of editor in a new terminal
- refocus – m
- part (str) – which alternative to edit
-
apply
(ui)¶ code that gets executed when this command is applied
- envelope (
-
class
alot.commands.envelope.
EncryptCommand
(action=None, keyids=None, trusted=False, **kwargs)¶ Parameters: - action (str) – wether to encrypt/unencrypt/toggleencrypt
- keyid (str) – the id of the key to encrypt
- trusted (bool) – wether to filter keys and only use trusted ones
-
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 -
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
-
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.
-
apply
(ui)¶ code that gets executed when this command is applied
-
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
-
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
Parameters: - action (str) – whether to sign/unsign/toggle
- keyid (str) – which key id to use
-
apply
(ui)¶ code that gets executed when this command is applied
-
class
alot.commands.envelope.
TagCommand
(tags='', action='add', **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’
-
apply
(ui)¶ code that gets executed when this command is applied
-
class
alot.commands.envelope.
ToggleHeaderCommand
¶ toggle display of all headers
-
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, **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
Parameters: query (list of str) – new querystring given as list of strings as returned by argparse -
apply
(ui)¶ code that gets executed when this command is applied
-
-
class
alot.commands.search.
RefinePromptCommand
¶ prompt to change this buffers querystring
-
apply
(ui)¶ code that gets executed when this command is applied
-
-
class
alot.commands.search.
SaveQueryCommand
(alias, query=None, flush=True, **kwargs)¶ Parameters: - alias (str) – name to use for query string
- query (str or None) – query string to save
- flush (bool) – immediately write out to the index
-
apply
(ui)¶ code that gets executed when this command is applied
-
class
alot.commands.search.
TagCommand
(tags='', 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) – immediately write out to the index
-
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) -
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, **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
-
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
-
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: - 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
-
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-
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: - 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
- 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
-
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)
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 -
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: - 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
-
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: - all (bool) – save all, not only selected attachment
- path (str) – path to write to. if all is set, this must be a directory.
-
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: - 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) – immediately write out to the index
-
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
-
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”