4.5. User Settings¶
Alot sets up a SettingsManager
to access user settings
defined in different places uniformly.
There are four types of user settings:
what? | location | accessible via |
---|---|---|
alot config | ~/.config/alot/config
or given by command option -c. |
SettingsManager.get() |
hooks – user provided python code | ~/.config/alot/hooks.py
or as given by the hooksfile
config value |
SettingsManager.get_hook() |
notmuch config | ~/.notmuchrc
or given by command option -n |
SettingsManager.get_notmuch_setting() |
mailcap – defines shellcommands to handle mime types | ~/.mailcap
(/etc/mailcap ) |
SettingsManager.mailcap_find_match() |
4.5.1. Settings Manager¶
-
class
alot.settings.manager.
SettingsManager
(alot_rc=None, notmuch_rc=None)¶ Organizes user settings
Parameters: - alot_rc (str) – path to alot’s config file
- notmuch_rc (str) – path to notmuch’s config file
-
get
(key, fallback=None)¶ look up global config values from alot’s config
Parameters: - key (str) – key to look up
- fallback (str) – fallback returned if key is not present
Returns: config value with type as specified in the spec-file
-
get_account_by_address
(address)¶ returns
Account
for a given email address (str)Parameters: address (string) – address to look up Return type: Account
or None
-
get_accounts
()¶ returns known accounts
Return type: list of Account
-
get_addressbooks
(order=None, append_remaining=True)¶ returns list of all defined
AddressBook
objects
-
get_addresses
()¶ returns addresses of known accounts including all their aliases
-
get_hook
(key)¶ return hook (callable) identified by key
-
get_keybinding
(mode, key)¶ look up keybinding from MODE-maps sections
Parameters: - mode (str) – mode identifier
- key (str) – urwid-style key identifier
Returns: a command line to be applied upon keypress
Return type: str
-
get_keybindings
(mode)¶ look up keybindings from MODE-maps sections
Parameters: mode (str) – mode identifier Returns: dictionaries of key-cmd for global and specific mode Return type: 2-tuple of dicts
-
get_main_addresses
()¶ returns addresses of known accounts without its aliases
-
get_notmuch_setting
(section, key, fallback=None)¶ look up config values from notmuch’s config
Parameters: - section (str) – key is in
- key (str) – key to look up
- fallback (str) – fallback returned if key is not present
Returns: config value with type as specified in the spec-file
looks up user’s preferred way to represent a given tagstring.
Parameters: - tag (str) – tagstring
- onebelow_normal (urwid.AttrSpec) – attribute that shines through if unfocussed
- onebelow_focus (urwid.AttrSpec) – attribute that shines through if focussed
If onebelow_normal or onebelow_focus is given these attributes will be used as fallbacks for fg/bg values ‘’ and ‘default’.
- This returns a dictionary mapping
normal: to urwid.AttrSpec
used if unfocussedfocussed: to urwid.AttrSpec
used if focussedtranslated: to an alternative string representation
-
get_theming_attribute
(mode, name, part=None)¶ looks up theming attribute
Parameters: - mode (str) – ui-mode (e.g. search,`thread`...)
- name (str) – identifier of the atttribute
Return type: urwid.AttrSpec
-
get_threadline_theming
(thread)¶ looks up theming info a threadline displaying a given thread. This wraps around
get_threadline_theming()
, filling in the current colour mode.Parameters: thread (alot.db.thread.Thread) – thread to theme
-
mailcap_find_match
(*args, **kwargs)¶ Propagates
mailcap.find_match()
but caches the mailcap (first argument)
-
read_config
(path)¶ parse alot’s config file from path
-
read_notmuch_config
(path)¶ parse notmuch’s config file from path
-
represent_datetime
(d)¶ turns a given datetime obj into a unicode string representation. This will:
- look if a fixed ‘timestamp_format’ is given in the config
- check if a ‘timestamp_format’ hook is defined
- use
pretty_datetime()
as fallback
-
set
(key, value)¶ setter for global config values
Parameters: - key (str) – config option identifies
- value (depends on the specfile
alot.rc.spec
) – option to set
4.5.3. Utils¶
-
alot.settings.utils.
read_config
(configpath=None, specpath=None, checks=None)¶ get a (validated) config object for given config file path.
Parameters: - configpath (str) – path to config-file
- specpath (str) – path to spec-file
- checks (dict str->callable,) – custom checks to use for validator. see validate docs
Raises: Return type: configobj.ConfigObj
-
alot.settings.utils.
resolve_att
(a, fallback)¶ replace ‘’ and ‘default’ by fallback values
4.5.4. Themes¶
-
class
alot.settings.theme.
Theme
(path)¶ Colour theme
Parameters: path (str) – path to theme file Raises: ConfigError
-
get_attribute
(colourmode, mode, name, part=None)¶ returns requested attribute
Parameters: - mode (str) – ui-mode (e.g. search,`thread`...)
- name (str) – of the atttribute
- colourmode (int) – colour mode; in [1, 16, 256]
Return type: urwid.AttrSpec
-
get_threadline_theming
(thread, colourmode)¶ look up how to display a Threadline wiidget in search mode for a given thread.
Parameters: - thread (alot.db.thread.Thread) – Thread to theme Threadline for
- colourmode (int) – colourmode to use, one of 1,16,256.
- This will return a dict mapping
normal: to urwid.AttrSpec, focus: to urwid.AttrSpec, parts: to a list of strings indentifying subwidgets to be displayed in this order. - Moreover, for every part listed this will map ‘part’ to a dict mapping
normal: to urwid.AttrSpec, focus: to urwid.AttrSpec, width: to a tuple indicating the width of the subpart. This is either (‘fit’, min, max) to force the widget to be at least min and at most max characters wide, or (‘weight’, n) which makes it share remaining space with other ‘weight’ parts. alignment: where to place the content if shorter than the widget. This is either ‘right’, ‘left’ or ‘center’.
-
4.5.5. Accounts¶
-
class
alot.account.
Account
(address=None, aliases=None, alias_regexp=None, realname=None, gpg_key=None, signature=None, signature_filename=None, signature_as_attachment=False, sent_box=None, sent_tags=None, draft_box=None, draft_tags=None, abook=None, sign_by_default=False, encrypt_by_default=u'none', **_)¶ Datastructure that represents an email account. It manages this account’s settings, can send and store mails to maildirs (drafts/send).
Note
This is an abstract class that leaves
send_mail()
unspecified. SeeSendmailAccount
for a subclass that uses a sendmail command to send out mails.-
get_addresses
()¶ return all email addresses connected to this account, in order of their importance
-
send_mail
(mail)¶ sends given mail
Parameters: mail ( email.message.Message
or string) – the mail to sendReturns: a Deferred that errs back with a class:SendingMailFailed, containing a reason string if an error occured.
-
store_draft_mail
(mail)¶ stores mail (
email.message.Message
or str) as draft ifdraft_box
is set.
-
static
store_mail
(mbx, mail)¶ stores given mail in mailbox. If mailbox is maildir, set the S-flag and return path to newly added mail. Oherwise this will return None.
Parameters: - mbx (
mailbox.Mailbox
) – mailbox to use - mail (
email.message.Message
or str) – the mail to store
Returns: absolute path of mail-file for Maildir or None if mail was successfully stored
Return type: str or None
Raises: StoreMailError
- mbx (
-
store_sent_mail
(mail)¶ stores mail (
email.message.Message
or str) in send-store ifsent_box
is set.
-
abook
= None¶ addressbook (
addressbook.AddressBook
) managing this accounts contacts
-
address
= None¶ this accounts main email address
-
alias_regexp
= []¶ regex matching alternative addresses
-
aliases
= []¶ list of alternative addresses
-
gpg_key
= None¶ gpg fingerprint for this account’s private key
-
realname
= None¶ real name used to format from-headers
-
signature
= None¶ signature to append to outgoing mails
-
signature_as_attachment
= None¶ attach signature file instead of appending its content to body text
-
signature_filename
= None¶ filename of signature file in attachment
-
-
class
alot.account.
SendmailAccount
(cmd, **kwargs)¶ Account
that pipes a message to a sendmail shell command for sendingParameters: cmd (str) – sendmail command to use for this account -
send_mail
(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
-
4.5.6. Addressbooks¶
-
class
alot.addressbook.
AddressBook
(ignorecase=True)¶ can look up email addresses and realnames for contacts.
Note
This is an abstract class that leaves
get_contacts()
unspecified. SeeAbookAddressBook
andExternalAddressbook
for implementations.-
get_contacts
()¶ list all contacts tuples in this abook as (name, email) tuples
-
lookup
(query='')¶ looks up all contacts where name or address match query
-
-
class
alot.addressbook.abook.
AbookAddressBook
(path='~/.abook/addressbook', **kwargs)¶ AddressBook
that parses abook’s config/database filesParameters: path (str) – path to abook addressbook file
-
class
alot.addressbook.external.
ExternalAddressbook
(commandline, regex, reflags=0, external_filtering=True, **kwargs)¶ AddressBook
that parses a shell command’s outputParameters: - commandline (str) – commandline
- regex (str) – regular expression used to match contacts in commands output to stdout. Must define subparts named “email” and “name”.
- reflags (str) – flags to use with regular expression.
Use the constants defined in
re
here (re.IGNORECASE etc.) - external_filtering (bool) – if True the command is fired with the given search string as parameter and the result is not filtered further. If set to False, the command is fired without additional parameters and the result list is filtered according to the search string.