ConfigSubset

class lsst.daf.butler.ConfigSubset(other=None, validate=True, mergeDefaults=True, searchPaths=None)

Bases: lsst.daf.butler.Config

Config representing a subset of a more general configuration.

Subclasses define their own component and when given a configuration that includes that component, the resulting configuration only includes the subset. For example, your config might contain schema if it’s part of a global config and that subset will be stored. If schema can not be found it is assumed that the entire contents of the configuration should be used.

Default values are read from the environment or supplied search paths using the default configuration file name specified in the subclass. This allows a configuration class to be instantiated without any additional arguments.

Additional validation can be specified to check for keys that are mandatory in the configuration.

Parameters:

other : Config or str or dict

Argument specifying the configuration information as understood by Config

validate : bool, optional

If True required keys will be checked to ensure configuration consistency.

mergeDefaults : bool, optional

If True defaults will be read and the supplied config will be combined with the defaults, with the supplied valiues taking precedence.

searchPaths : list or tuple, optional

Explicit additional paths to search for defaults. They should be supplied in priority order. These paths have higher priority than those read from the environment in ConfigSubset.defaultSearchPaths().

Attributes Summary

component	Component to use from supplied config.
defaultConfigFile	Name of the file containing defaults for this config class.
includeKey
requiredKeys	Keys that are required to be specified in the configuration.

Methods Summary

asArray(name)	Get a value as an array.
clear()
copy()
defaultSearchPaths()	Read the environment to determine search paths to use for global defaults.
dump(output)	Writes the config to a yaml stream.
dumpToFile(path)	Writes the config to a file.
get(k[,d])
items()
keys()
merge(other)	Like Config.update, but will add keys & values from other that DO NOT EXIST in self.
nameTuples([topLevelOnly])	Get tuples representing the name hierarchies of all keys.
names([topLevelOnly, delimiter])	Get a delimited name of all the keys in the hierarchy.
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised.
popitem()	as a 2-tuple; but raise KeyError if D is empty.
ppprint()	helper function for debugging, prints a config out in a readable way in the debugger.
setdefault(k[,d])
update(other)	Like dict.update, but will add or modify keys in nested dicts, instead of overwriting the nested dict entirely.
updateParameters(configType, config, full[, …])	Generic helper function for updating specific config parameters.
validate()	Check that mandatory keys are present in this configuration.
values()

Attributes Documentation

component = None

Component to use from supplied config. Can be None. If specified the key is not required. Can be a full dot-separated path to a component.

defaultConfigFile = None

Name of the file containing defaults for this config class.

includeKey = 'includeConfigs'

requiredKeys = ()

Keys that are required to be specified in the configuration.

Methods Documentation

asArray(name)

Get a value as an array.

May contain one or more elements.

Parameters:

name : str

Key to use to retrieve value.

Returns:

array : collections.abc.Sequence

The value corresponding to name, but guaranteed to be returned as a list with at least one element. If the value is a Sequence (and not a str) the value itself will be returned, else the value will be the first element.

clear() → None. Remove all items from D.

copy()

classmethod defaultSearchPaths()

Read the environment to determine search paths to use for global defaults.

Global defaults, at lowest priority, are found in the config directory of the butler source tree. Additional defaults can be defined using the environment variable $DAF_BUTLER_CONFIG_PATHS which is a PATH-like variable where paths at the front of the list have priority over those later.

Returns:

paths : list

Returns a list of paths to search. The returned order is in priority with the highest priority paths first. The butler config directory will always be at the end of the list.

dump(output)

Writes the config to a yaml stream.

Parameters:

output

The YAML stream to use for output.

dumpToFile(path)

Writes the config to a file.

Parameters:

path : str

Path to the file to use for output.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

merge(other)

Like Config.update, but will add keys & values from other that DO NOT EXIST in self.

Keys and values that already exist in self will NOT be overwritten.

Parameters:

other : dict or Config

Source of configuration:

nameTuples(topLevelOnly=False)

Get tuples representing the name hierarchies of all keys.

The tuples returned from this method are guaranteed to be usable to access items in the configuration object.

Parameters:

topLevelOnly : bool, optional

If False, the default, a full hierarchy of names is returned. If True, only the top level are returned.

Returns:

names : list of tuple of str

List of all names present in the Config where each element in the list is a tuple of strings representing the hierarchy.

names(topLevelOnly=False, delimiter=None)

Get a delimited name of all the keys in the hierarchy.

The values returned from this method are guaranteed to be usable to access items in the configuration object.

Parameters:

topLevelOnly : bool, optional

If False, the default, a full hierarchy of names is returned. If True, only the top level are returned.

delimiter : str, optional

Delimiter to use when forming the keys. If the delimiter is present in any of the keys, it will be escaped in the returned names. If None given a delimiter will be automatically provided. The delimiter can not be alphanumeric.

Returns:

names : list of str

List of all names present in the Config.

Raises:

ValueError:

The supplied delimiter is alphanumeric.

Notes

This is different than the built-in method dict.keys, which will return only the first level keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

ppprint()

helper function for debugging, prints a config out in a readable way in the debugger.

use: pdb> print(myConfigObject.ppprint())

Returns:

s : str

A prettyprint formatted string representing the config

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update(other)

Like dict.update, but will add or modify keys in nested dicts, instead of overwriting the nested dict entirely.

For example, for the given code: foo = {“a”: {“b”: 1}} foo.update({“a”: {“c”: 2}})

Parameters:

other : dict or Config

Source of configuration:

• If foo is a dict, then after the update foo == {“a”: {“c”: 2}}
• But if foo is a Config, then after the update foo == {“a”: {“b”: 1, “c”: 2}}

static updateParameters(configType, config, full, toUpdate=None, toCopy=None, overwrite=True)

Generic helper function for updating specific config parameters.

Allows for named parameters to be set to new values in bulk, and for other values to be set by copying from a reference config.

Assumes that the supplied config is compatible with configType and will attach the updated values to the supplied config by looking for the related component key. It is assumed that config and full are from the same part of the configuration hierarchy.

Parameters:

configType : ConfigSubset

Config type to use to extract relevant items from config.

config : Config

A Config to update. Only the subset understood by the supplied ConfigSubset will be modified. Default values will not be inserted and the content will not be validated since mandatory keys are allowed to be missing until populated later by merging.

full : Config

A complete config with all defaults expanded that can be converted to a configType. Read-only and will not be modified by this method. Values are read from here if toCopy is defined.

Repository-specific options that should not be obtained from defaults when Butler instances are constructed should be copied from full to config.

toUpdate : dict, optional

A dict defining the keys to update and the new value to use. The keys and values can be any supported by Config assignment.

toCopy : tuple, optional

tuple of keys whose values should be copied from full into config.

overwrite : bool, optional

If False, do not modify a value in config if the key already exists. Default is always to overwrite.

Raises:

ValueError

Neither toUpdate not toCopy were defined.

validate()

Check that mandatory keys are present in this configuration.

Ignored if requiredKeys is empty.

values() → an object providing a view on D's values