Configuration API#
Executive Summary#
99% of configuration use cases can be met with
Obtain an ODCConfig object from the most general possible arguments. |
Full API#
- class datacube.cfg.ODCConfig(paths=None, raw_dict=None, text=None)[source]#
Configuration finder/reader/parser.
Attributes
- allow_envvar_overrides: bool = True#
If True, environment variables can override the values explicitly specified in the supplied configuration.
Note that environments not explicitly specified in the supplied configuration (dynamic environments) can still be read from environment variables, even if this attribute is False.
- raw_text: str | None#
The raw configuration text being used, as read from the configuration file or supplied directly by the user. May be None if the user directly supplied configuration as a dictionary. May be in ini or yaml format. Does not include dynamic environments or values overridden by environment variables.
- raw_config: dict[str, dict[str, Any]]#
The raw dictionary form of the configuration, as supplied directly by the user, or as parsed from raw_text. Does not include dynamic environments or values overridden by environment variables.
- known_environments: dict[str, 'ODCEnvironment']#
A dictionary containing all environments defined in raw_config, plus any dynamic environments read so far. Environment themselves are not validated until read from.
- canonical_names: dict[str, list[str]]#
A dictionary mapping canonical environment names to all aliases for that environment.
When called with no args, reads the first config file found in the config path list is used. The config path list is taken from:
Environment variable $ODC_CONFIG_PATH (as a UNIX path style colon-separated path list)
Environment variable $DATACUBE_CONFIG_PATH (as a UNIX path style colon-separated path list) This is a deprecated legacy environment variable, and please note that it’s behaviour has changed slightly from datacube 1.8.x.
The default config search path (i.e. .cfg._DEFAULT_CONFIG_SEARCH_PATH)
If no config file is found at any of the paths in active path list, use the default configuration at , or if no such config file exists, use the default configuration (.cfg._DEFAULT_CONF). Configuration files may be in ini or yaml format. Environment variable overrides ARE applied.
Otherwise, user may supply one (and only one) of the following:
- Parameters:
paths (
str
|PathLike
|list
[str
|PathLike
] |None
) – The path of the configuration file, or a list of paths of candidate configuration files (the first in the list that can be read is used). If none of the supplied paths can be read, an error is raised. (Unlike calling with no arguments, the fallback default config is NOT used.) Configuration file may be in ini or yaml format. Environment variable overrides ARE applied.raw_dict (
dict
[str
,dict
[str
,Any
]] |None
) – A raw dictionary containing configuration data. Used as is - environment variable overrides are NOT applied.text (
str
|None
) – A string containing configuration data in ini or yaml format. Used as is - environment variable overrides are NOT applied.
- class datacube.cfg.ConfigException[source]#
Exception raised in the configuration API
- add_note()#
Exception.add_note(note) – add a note to the exception
- with_traceback()#
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class datacube.cfg.ODCEnvironment(cfg, name, raw, allow_env_overrides=True)[source]#
Configuration reader for an individual ODC environment.
Only configuration options with a registered option handler are able to be read. Configuration options may be read either as attributes on the ODCEnvironment objects or via the getitem dunder method.
E.g. env.index_driver or env[“index_driver”]
Attempting to access an unhandled or invalid option will raise a KeyError or AttributeError, as appropriate for the access method.
ODCEnvironment objects should only be instantiated by and acquired from an ODCConfig object.