13.2.8. Settings class

class keypirinha.Settings(settings_id)

A class to access the Settings of a Package/Plugin.

It is not meant to be instantiated manually: Plugin.load_settings() should be called instead, or settings().

get(key, section=None, fallback=None, unquote=False)

Get the string value of the specified key in section.

Parameters

  • key (str) – The name of the setting to find

  • section (str) – You can optionally specify a section name. Otherwise the key will be searched in the default section.

  • fallback (any) – A fallback value in case key does not exist in the specified section.

  • unquote (bool) – Unquote the resulting value if it is encapsulated by a pair of single-quotes ' or by a pair of double-quotes ".

Returns

The found value, or fallback in case key was not found in section.

Return type

str

get_bool(key, section=None, fallback=None)

A specialized get() to read boolean values.

Values 1, y, yes, t, true, on, enable and enabled are evaluated to True. Values 0, n, no, f, false, off, disable and disabled are evaluated to False. The fallback argument is returned otherwise.

Note

The read value, if any, is unquoted then stripped first.

get_enum(key, section=None, fallback=None, enum=[], case_sensitive=False, unquote=True)

A specialized get() to read enum values.

The enum argument is the list of accepted string values. Comparison depends on the case_sensitive argument.

The fallback argument is returned in case none of the enumerated values matches to the read value, or if the setting was not found.

Note

The read value, if any, is unquoted (depending on the unquote argument) then stripped before being compared.

get_float(key, section=None, fallback=None, min=None, max=None)

A specialized get() to read float values.

If the read value is successfully casted/converted to a float, it is capped against min and max optional boundaries.

The fallback argument is returned in case the setting was not found or the format of the read value is incorrect.

Note

The read value, if any, is unquoted then stripped first.

get_int(key, section=None, fallback=None, min=None, max=None)

A specialized get() to read integer values.

If the read value is successfully converted to an integer, it is capped against optional boundaries min and/or max.

The fallback argument is returned in case the setting was not found or the format of the read value is incorrect.

Note

  • The int(value, base=0) expression is used to convert the read string value. So decimal representations are accepted as well as the hexadecimal (e.g. 0xA3), the octal (e.g. 0o17) and the binary (e.g. 0b110) ones.

  • The read value, if any, is unquoted then stripped first.

get_mapped(key, section=None, fallback=None, map={}, case_sensitive=False, unquote=True)

A specialized get() to read mapped values.

The map argument is a dictionary where keys are strings that are expected to be read from the configuration data (similar behavior to get_enum()), and their respective values are the ones that are returned by this method in case one of the keys has been matched.

Comparison of the read value and the keys depend on the case_sensitive argument.

The fallback argument is returned in case none of the keys matches to the read value, or if the setting was not found.

Note

The read value, if any, is unquoted (depending on the unquote argument) then stripped before being compared.

get_multiline(key, section=None, fallback=[], keep_empty_lines=False)

A specialized get() to read multiline values. It returns a list of lines (strings).

A copy of the fallback argument is returned if the setting was not found or if the read value is empty (i.e. no line remains after the keep_empty_lines option has been applied).

get_stripped(key, section=None, fallback=None, unquote=True)

Same as get() but str.strip() the value and returns fallback if the value is empty or not found.

Warning

The read value is unquoted before being stripped if the unquote argument is true, which means that if configuration value is " X " for example, X will be returned (i.e. no quotes, no spaces).

has(key, section=None)

Check the existence of a key in a section and return a boolean.

has_section(section)

Check the existence of section and return a boolean.

keys(section=None)

Return a list of the keys found in section, or an empty list.

sections()

Return a list of the loaded sections, or an empty list.