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)¶
ArgumentParser
that raisesCommandParseError
instead 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
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
- 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, **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”