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):
Convert all line endings to \r\n (DOS line endings).
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, env=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_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.
libmagic_version_at_least
(version)¶ checks if the libmagic library installed is more recent than a given version.
- Parameters
version – minimum version expected in the form XYY (i.e. 5.14 -> 514) with XYY >= 513
-
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
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