Package: gconf
gconfManaging a config globally throughout a Python applicationOverviewWith gconf, yaml configuration files can be loaded on module-scope
such that its values can be accessed from anywhere in a running application.UsageLoading yaml filesOne or more yaml configuration files are loaded globally from path-like objects,
usually in a program's main function.
The resulting configuration is an overlay of all loaded configurations
with those that were loaded later taking precedence.Loading a single config file:gconf.load('conf.yml')Loading multiple config files at once:gconf.load('conf1.yml','conf2.yml')Loading multiple config files one after the other:gconf.load('conf1.yml')gconf.load('conf2.yml')The two examples above produce an identical result.
In both casesconfig2takes precedence overconfig1and overrides its values.Each invocation ofloadreturns a list of all paths that have actually been loaded.Loading the first config from a list of paths:gconf.load_first('conf1.yml','conf2.yml')Ifconf1.ymlexists, it is loaded andconf2.ymlis ignored.
ifconf1.ymldoes not exist,conf2.ymlis loaded.load_firstreturns the path that has actually been loaded.All loading functions raise aFileNotFoundErrorif no file is found.
This can be prevented by setting the keyword-argumentrequired=False.Manually adding valuesA dict can be added to the config from within the application.
This is equivalent to loading a config file with the same content
and overrides values if they are already present or adds them if not.gconf.add({'parent':{'child':'new child'}})Warning: using this functionality, it is possible to the gconf module as a store for global variables.
Global variables are a code smell and should not be used!
Please use thegconf.add()function only if you know exactly what you are doing.Accessing config valuesThere are several ways of addressing the values that are stored in the config,
all of them using the module-levelgetmethod.Dot-notationgconf.get('parent.child.some value')String argumentsgconf.get('parent','child','some value')A mix of bothgconf.get('parent.child','some value')Top-level item as dictionarygconf.get()['parent']['child']['some value']Some intermediate item as dictionarygconf.get('parent')['child']['some value']To access list items, simply use their index in the pathgconf.get('list.3')Default valueThegetmethod accepts adefaultargument, which is returned
if the specified item does not exist:gconf.get('non-existing',default=default_value)This even works for falsey values likeFalse,Noneor the empty string.Environment Variables OverrideConfig values are overridden by environment variables. As keys of environment variables are uppercase with
underscores by convention, gconf expects them in that way. The conversion rules are:GCONF_prefix is added to avoid conflictshierarchy levels are separated by underscorespaces are replaced by underscoreall text is in all-capsExamples:gconf.getenvironment varparent.some childGCONF_PARENT_SOME_CHILDlist.0.entryGCONF_LIST_0_ENTRYErrorsIf an attempt is made at loading non-existing files andrequired=True(the default), anFileNotFoundErroris raised.If nodefaultis provided, an attempt to access a non-existing item raises aKeyError.Temporary overrideParts of the config can be temporarily overridden through a context manager.
Pass it a dictionary that overlays the existing one:withgconf.override_conf({'parent':{'child':'override_value'}}):gconf.get('parent.child')# => 'override_value'gconf.get('parent.child')# => 'original_value'To temporarily remove parts of the config theDELETEDconstant can be used:importgconfwithgconf.override_conf({'parent':{'child':gconf.DELETED}}):gconf.get('parent.child')# => KeyErrorgconf.get('parent.child')# => 'original_value'ResettingThe global gconf dict can be completely reset.gconf.reset()