diff options
| -rw-r--r-- | alot/__main__.py | 2 | ||||
| -rw-r--r-- | alot/account.py | 10 | ||||
| -rw-r--r-- | alot/buffers.py | 4 | ||||
| -rw-r--r-- | alot/completion.py | 18 | ||||
| -rw-r--r-- | alot/helper.py | 32 | ||||
| -rw-r--r-- | alot/ui.py | 10 |
6 files changed, 72 insertions, 4 deletions
diff --git a/alot/__main__.py b/alot/__main__.py index d68b5b87..13679cb9 100644 --- a/alot/__main__.py +++ b/alot/__main__.py @@ -16,6 +16,8 @@ from alot.commands import CommandParseError, COMMANDS def main(): + """The main entry point to alot. It parses the command line and prepares + for the user interface main loop to run.""" # set up the parser to parse the command line options. parser = argparse.ArgumentParser() parser.add_argument('-v', '--version', action='version', diff --git a/alot/account.py b/alot/account.py index 5e66e9bf..c8b83418 100644 --- a/alot/account.py +++ b/alot/account.py @@ -178,6 +178,7 @@ class Account(object): class SendmailAccount(Account): """:class:`Account` that pipes a message to a `sendmail` shell command for sending""" + def __init__(self, cmd, **kwargs): """ :param cmd: sendmail command to use for this account @@ -187,13 +188,22 @@ class SendmailAccount(Account): self.cmd = cmd def send_mail(self, mail): + """Pipe the given mail to the configured sendmail command. Display a + short message on success or a notification on error. + :param mail: the mail to send out + :type mail: str + :returns: the deferred that calls the sendmail command + :rtype: `twisted.internet.defer.Deferred` + """ cmdlist = split_commandstring(self.cmd) def cb(out): + """The callback used on success.""" logging.info('sent mail successfully') logging.info(out) def errb(failure): + """The callback used on error.""" termobj = failure.value errmsg = '%s failed with code %s:\n%s' % \ (self.cmd, termobj.exitCode, str(failure.value)) diff --git a/alot/buffers.py b/alot/buffers.py index 8dcb7352..36baf00a 100644 --- a/alot/buffers.py +++ b/alot/buffers.py @@ -111,6 +111,7 @@ class BufferlistBuffer(Buffer): return bufferlinewidget.get_buffer() def focus_first(self): + """Focus the first line in the buffer list.""" self.body.set_focus(0) @@ -441,9 +442,11 @@ class ThreadBuffer(Buffer): # needed for ui.get_deep_focus.. def get_focus(self): + "Get the focus from the underlying body widget." return self.body.get_focus() def set_focus(self, pos): + "Set the focus in the underlying body widget." logging.debug('setting focus to %s ', pos) self.body.set_focus(pos) @@ -658,6 +661,7 @@ class TagListBuffer(Buffer): self.taglist.set_focus(focusposition % len(displayedtags)) def focus_first(self): + """Focus the first line in the tag list.""" self.body.set_focus(0) def focus_last(self): diff --git a/alot/completion.py b/alot/completion.py index 41d04b8d..ac4c165a 100644 --- a/alot/completion.py +++ b/alot/completion.py @@ -521,16 +521,34 @@ class CommandLineCompleter(Completer): class PathCompleter(Completer): + """completion for paths""" + def complete(self, original, pos): if not original: return [('~/', 2)] prefix = os.path.expanduser(original[:pos]) def escape(path): + """Escape all backslashes and spaces in given path with a + backslash. + + :param path: the path to escape + :type path: str + :returns: the escaped path + :rtype: str + """ return path.replace('\\', '\\\\').replace(' ', r'\ ') def deescape(escaped_path): + """Remove escaping backslashes in front of spaces and backslashes. + + :param escaped_path: a path potentially with escaped spaces and + backslashs + :type escaped_path: str + :returns: the actual path + :rtype: str + """ return escaped_path.replace('\\ ', ' ').replace('\\\\', '\\') def prep(path): diff --git a/alot/helper.py b/alot/helper.py index b33c0125..52946f99 100644 --- a/alot/helper.py +++ b/alot/helper.py @@ -433,6 +433,20 @@ def libmagic_version_at_least(version): # TODO: make this work on blobs, not paths def mimewrap(path, filename=None, ctype=None): + """Take the contents of the given path and wrap them into an email MIME + part according to the content type. The content type is auto detected from + the actual file contents and the file name if it is not given. + + :param path: the path to the file contents + :type path: str + :param filename: the file name to use in the generated MIME part + :type filename: str or None + :param ctype: the content type of the file contents in path + :type ctype: str or None + :returns: the message MIME part storing the data from path + :rtype: subclasses of email.mime.base.MIMEBase + """ + with open(path, 'rb') as f: content = f.read() if not ctype: @@ -470,6 +484,15 @@ def mimewrap(path, filename=None, ctype=None): def shell_quote(text): + """Escape the given text for passing it to the shell for interpretation. + The resulting string will be parsed into one "word" (in the sense used in + the shell documentation, see sh(1)) by the shell. + + :param text: the text to quote + :type text: str + :returns: the quoted text + :rtype: str + """ return "'%s'" % text.replace("'", """'"'"'""") @@ -485,6 +508,15 @@ def tag_cmp(a, b): def humanize_size(size): + """Create a nice human readable representation of the given number + (understood as bytes) using the "K" and "M" suffixes to indicate kilo- and + megabytes. They are understood to be 1024 based. + + :param size: the number to convert + :type size: int + :returns: the human readable representation of size + :rtype: str + """ for factor, format_string in ((1, '%i'), (1024, '%iK'), (1024 * 1024, '%.1fM')): @@ -137,8 +137,8 @@ class UI(object): self._unlock_callback() # otherwise interpret keybinding else: - # define callback that resets input queue def clear(*_): + """Callback that resets the input queue.""" if self._alarm is not None: self.mainloop.remove_alarm(self._alarm) self.input_queue = [] @@ -290,8 +290,8 @@ class UI(object): oldroot = self.mainloop.widget def select_or_cancel(text): - # restore main screen and invoke callback - # (delayed return) with given text + """Restore the main screen and invoce the callback (delayed return) + with the given text.""" self.mainloop.widget = oldroot self._passall = False d.callback(text) @@ -497,6 +497,8 @@ class UI(object): oldroot = self.mainloop.widget def select_or_cancel(text): + """Restore the main screen and invoce the callback (delayed return) + with the given text.""" self.mainloop.widget = oldroot self._passall = False d.callback(text) @@ -650,8 +652,8 @@ class UI(object): :type cmd: :class:`~alot.commands.Command` """ if cmd: - # define (callback) function that invokes post-hook def call_posthook(_): + """Callback function that will invoke the post-hook.""" if cmd.posthook: logging.info('calling post-hook') return defer.maybeDeferred(cmd.posthook, |