Settings object API

This page documents the Settings object and its API.

class ycsettings.settings.Settings(*sources, search_first=['env', 'env_settings_uri'], case_sensitive=False, raise_exception=False, warn_missing=False, env_settings_uri_keys=['SETTINGS_URI'], dict_settings_uri_keys=['settings', 'settings_uri'], object_settings_uri_keys=['settings', 'settings_uri'])

This class manages the lookup and prioritizing of setting variables in multiple different sources. Supported sources include:

• Environment (env): The OS environment, i.e., os.environ
• URI/files: Handles different file types including: JSON, YAML, and INI
• Python modules: Python modules similar to Django settings module; it can be a .py file or module path
• Dictionary-like objects: Objects with the items attribute
• Arbitrary objects: All __dict__ entries not starting with __ are used as settings

If settings_uri is found in the environment (SETTINGS_URI), dictionary, or arbitrary object, it will also load the corresponding settings URI in addition to the object itself. This way, it can autoload from SETTINGS_URI in the environment and argparse.Namespace. For example,

parser = ArgumentParser(description='Hello World!')
parser.add_argument('settings_uri', type=str, metavar='<config_file>', help='Positional option')
A = parser.parse_args()

settings = Settings(A, warn_missing=False)

The file specified in A.settings_uri will be loaded.

__init__(*sources, search_first=['env', 'env_settings_uri'], case_sensitive=False, raise_exception=False, warn_missing=False, env_settings_uri_keys=['SETTINGS_URI'], dict_settings_uri_keys=['settings', 'settings_uri'], object_settings_uri_keys=['settings', 'settings_uri'])

Initializes the Settings object.

Parameters:

• sources (list) – list of sources to search for settings
• search_first (list) – list of sources which will be searched first before any other sources specified in sources.
• case_sensitive (bool) – whether to make case sensitive comparisons for settings key
• raise_exception (bool) – whether to raise a MissingSettingException exception when the setting is not found
• warn_missing (bool) – whether to display a warning when the setting is not found
• env_settings_uri_keys (str) – keys to find settings in the environment; if multiple keys are found, they’ll all be used
• dict_settings_uri_keys (str) – keys to find settings in a dict()-like object; if multiple keys are found, they’ll all be used
• object_settings_uri_keys (str) – keys to find settings in an arbitrary object; if multiple keys are found, they’ll all be used

get(key, *, default=None, cast_func=None, case_sensitive=None, raise_exception=None, warn_missing=None, use_cache=True, additional_sources=[])

Gets the setting specified by key. For efficiency, we cache the retrieval of settings to avoid multiple searches through the sources list.

Parameters:

• key (str) – settings key to retrieve
• default (str) – use this as default value when the setting key is not found
• cast_func (func) – cast the value of the settings using this function
• case_sensitive (bool) – whether to make case sensitive comparisons for settings key
• raise_exception (bool) – whether to raise a MissingSettingException exception when the setting is not found
• warn_missing (bool) – whether to display a warning when the setting is not found
• additional_sources (list) – additional sources to search for the key; note that the values obtained here could be cached in a future call

Returns:

the setting value

Return type:

str

getbool(key, **kwargs)

Gets the setting value as a bool() by cleverly recognizing true values.

Return type:bool

getdict(key, **kwargs)

Gets the setting value as a dict.

Return type:dict

getfloat(key, **kwargs)

Gets the setting value as a float.

Return type:float

getint(key, **kwargs)

Gets the setting value as a int.

Return type:int

getlist(key, delimiter=', ', **kwargs)

Gets the setting value as a list; it splits the string using delimiter.

Parameters:delimiter (str) – split the value using this delimiter Return type:list

getnjobs(key, **kwargs)

Gets the setting value as an integer relative to the number of CPU. See ycsettings.settings.parse_n_jobs() for parsing rules.

Return type:int

getserialized(key, decoder_func=None, **kwargs)

Gets the setting value as a dict or list trying json.loads(), followed by yaml.load().

Return type:dict, list

geturi(key, **kwargs)

Gets the setting value as a urllib.parse.ParseResult.

Return type:urllib.parse.ParseResult

ycsettings.settings.parse_n_jobs(s)

This function parses a “math”-like string as a function of CPU count. It is useful for specifying the number of jobs.

For example, on an 8-core machine:

assert parse_n_jobs('0.5 * n') == 4
assert parse_n_jobs('2n') == 16
assert parse_n_jobs('n') == 8
assert parse_n_jobs('4') == 4

Parameters:s (str) – string to parse for number of CPUs