4.5. Utils

alot.helper.RFC3156_canonicalize(text)

Canonicalizes plain text (MIME-encoded usually) according to RFC3156.

This function works as follows (in that order):

  1. Convert all line endings to \r\n (DOS line endings).

  2. Encode all occurrences of “From “ at the beginning of a line to “From=20” in order to prevent other mail programs to replace this with “> From” (to avoid MBox conflicts) and thus invalidate the signature.

Parameters:

text – text to canonicalize (already encoded as quoted-printable)

Return type:

str

alot.helper.call_cmd(cmdlist, stdin=None)

get a shell commands output, error message and return value and immediately return.

Warning

This returns with the first screen content for interactive commands.

Parameters:

  • cmdlist (list of str) – shellcommand to call, already splitted into a list accepted by subprocess.Popen()

  • stdin (str, bytes, or None) – string to pipe to the process

Returns:

triple of stdout, stderr, return value of the shell command

Return type:

str, str, int

async alot.helper.call_cmd_async(cmdlist, stdin=None)

Given a command, call that command asynchronously and return the output.

This function only handles OSError when creating the subprocess, any other exceptions raised either durring subprocess creation or while exchanging data with the subprocess are the caller’s responsibility to handle.

If such an OSError is caught, then returncode will be set to 1, and the error value will be set to the str() value of the exception.

Parameters:

stdin (str) – string to pipe to the process

Returns:

Tuple of stdout, stderr, returncode

Return type:

tuple[str, str, int]

alot.helper.get_notmuch_config_path()

Find the notmuch config file via env vars and default locations

alot.helper.get_xdg_env(env_name, fallback)

Used for XDG_* env variables to return fallback if unset or empty

alot.helper.guess_encoding(blob)

uses file magic to determine the encoding of the given data blob.

Parameters:

blob (data) – file content as read by file.read()

Returns:

encoding

Return type:

str

alot.helper.guess_mimetype(blob)

uses file magic to determine the mime-type of the given data blob.

Parameters:

blob (data) – file content as read by file.read()

Returns:

mime-type, falls back to ‘application/octet-stream’

Return type:

str

alot.helper.humanize_size(size)

Create a nice human readable representation of the given number (understood as bytes) using the “KiB” and “MiB” suffixes to indicate kibibytes and mebibytes. A kibibyte is defined as 1024 bytes (as opposed to a kilobyte which is 1000 bytes) and a mibibyte is 1024**2 bytes (as opposed to a megabyte which is 1000**2 bytes).

Parameters:

size (int) – the number to convert

Returns:

the human readable representation of size

Return type:

str

alot.helper.mailto_to_envelope(mailto_str)

Interpret mailto-string into a alot.db.envelope.Envelope

alot.helper.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.

Parameters:

  • path (str) – the path to the file contents

  • filename (str or None) – the file name to use in the generated MIME part

  • ctype (str or None) – the content type of the file contents in path

Returns:

the message MIME part storing the data from path

Return type:

subclasses of email.mime.base.MIMEBase

alot.helper.parse_mailcap_nametemplate(tmplate='%s')

this returns a prefix and suffix to be used in the tempfile module for a given mailcap nametemplate string

alot.helper.parse_mailto(mailto_str)

Interpret mailto-string

Parameters:

mailto_str (str) – the string to interpret. Must conform to :rfc:2368.

Returns:

the header fields and the body found in the mailto link as a tuple of length two

Return type:

tuple(dict(str->list(str)), str)

alot.helper.pretty_datetime(d)

translates datetime d to a “sup-style” human readable string.

>>> now = datetime.now()
>>> now.strftime('%c')
'Sat 31 Mar 2012 14:47:26 '
>>> pretty_datetime(now)
'just now'
>>> pretty_datetime(now - timedelta(minutes=1))
'1min ago'
>>> pretty_datetime(now - timedelta(hours=5))
'5h ago'
>>> pretty_datetime(now - timedelta(hours=12))
'02:54am'
>>> pretty_datetime(now - timedelta(days=1))
'yest 02pm'
>>> pretty_datetime(now - timedelta(days=2))
'Thu 02pm'
>>> pretty_datetime(now - timedelta(days=7))
'Mar 24'
>>> pretty_datetime(now - timedelta(days=356))
'Apr 2011'
alot.helper.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.

Parameters:

text (str) – the text to quote

Returns:

the quoted text

Return type:

str

alot.helper.shorten(string, maxlen)

shortens string if longer than maxlen, appending ellipsis

alot.helper.shorten_author_string(authors_string, maxlength)

Parse a list of authors concatenated as a text string (comma separated) and smartly adjust them to maxlength.

1) If the complete list of sender names does not fit in maxlength, it tries to shorten names by using only the first part of each.

2) If the list is still too long, hide authors according to the following priority:

  • First author is always shown (if too long is shorten with ellipsis)

  • If possible, last author is also shown (if too long, uses ellipsis)

  • If there are more than 2 authors in the thread, show the maximum of them. More recent senders have higher priority.

  • If it is finally necessary to hide any author, an ellipsis between first and next authors is added.

alot.helper.split_commandline(s)

splits semi-colon separated commandlines, ignoring quoted separators

alot.helper.split_commandstring(cmdstring)

split command string into a list of strings to pass on to subprocess.Popen and the like. This simply calls shlex.split but works also with unicode bytestrings.

alot.helper.string_decode(string, enc='ascii')

safely decodes string to unicode bytestring, respecting enc as a hint.

Parameters:

  • string (str or unicode) – the string to decode

  • enc (str) – a hint what encoding is used in string (‘ascii’, ‘utf-8’, …)

Returns:

the unicode decoded input string

Return type:

unicode

alot.helper.string_sanitize(string, tab_width=8)

strips, and replaces non-printable characters

Parameters:

tab_width (int or None) – number of spaces to replace tabs with. Read from globals.tabwidth setting if None

>>> string_sanitize(' foo\rbar ', 8)
' foobar '
>>> string_sanitize('foo\tbar', 8)
'foo     bar'
>>> string_sanitize('foo\t\tbar', 8)
'foo             bar'
alot.helper.try_decode(blob)

Guess the encoding of blob and try to decode it into a str.

Parameters:

blob (bytes) – The bytes to decode

Returns:

the decoded blob

Return type:

str

alot.helper.unicode_printable(c)

Checks if the given character is a printable Unicode character, i.e., not a private/unassigned character and not a control character other than tab or newline.