DimensionConfig¶

class lsst.daf.butler.DimensionConfig(other: Optional[Union[str, ParseResult, ResourcePath, Path, Config]] = None, validate: bool = True, searchPaths: Optional[Iterable[Union[str, ParseResult, ResourcePath, Path]]] = None)¶

Bases: ConfigSubset

Configuration that defines a DimensionUniverse.

The configuration tree for dimensions is a (nested) dictionary with five top-level entries:

version: an integer version number, used as keys in a singleton registry of all DimensionUniverse instances;
namespace: a string to be associated with the version in the singleton registry of all DimensionUnivers instances;
skypix: a dictionary whose entries each define a SkyPixSystem, along with a special “common” key whose value is the name of a skypix dimension that is used to relate all other spatial dimensions in the Registry database;
elements: a nested dictionary whose entries each define StandardDimension or StandardDimensionCombination.
topology: a nested dictionary with spatial and temporal keys, with dictionary values that each define a StandardTopologicalFamily.
packers: a nested dictionary whose entries define factories for a DimensionPacker instance.

See the documentation for the linked classes above for more information on the configuration syntax.

Parameters:

otherConfig or str or dict, optional: Argument specifying the configuration information as understood by Config. If None is passed then defaults are loaded from “dimensions.yaml”, otherwise defaults are not loaded.
validatebool, optional: If True required keys will be checked to ensure configuration consistency.
searchPathslist 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(). Paths can be str referring to the local file system or URIs, lsst.resources.ResourcePath.

Attributes Summary

`component`	Component to use from supplied config.
`defaultConfigFile`	Name of the file containing defaults for this config class.
`includeKey`	Key used to indicate that another config should be included at this part of the hierarchy.
`requiredKeys`	Keys that are required to be specified in the configuration.
`resourcesPackage`	Package to search for default configuration data.

Methods Summary

`asArray`(name)	Get a value as an array.
`clear`()
`copy`()
`defaultSearchPaths`()	Read environment to determine search paths to use.
`dump`([output, format])	Write the config to an output stream.
`dumpToUri`(uri[, updateFile, ...])	Write the config to location pointed to by given URI.
`fromString`(string[, format])	Create a new Config instance from a serialized string.
`fromYaml`(string)	Create a new Config instance from a YAML string.
`get`(k[,d])
`items`()
`keys`()
`makeBuilder`()	Construct a `DinmensionConstructionBuilder`.
`merge`(other)	Merge another Config into this one.
`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`()	Return config as formatted readable string.
`setdefault`(k[,d])
`toDict`()	Convert a `Config` to a standalone hierarchical `dict`.
`update`(other)	Update config from other `Config` or `dict`.
`updateParameters`(configType, config, full[, ...])	Update specific config parameters.
`validate`()	Check that mandatory keys are present in this configuration.
`values`()

Attributes Documentation

component: ClassVar[Optional[str]] = 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: ClassVar[Optional[str]] = 'dimensions.yaml'¶: Name of the file containing defaults for this config class.

includeKey: ClassVar[str] = 'includeConfigs'¶: Key used to indicate that another config should be included at this part of the hierarchy.

requiredKeys: ClassVar[Sequence[str]] = ('version', 'elements', 'skypix')¶: Keys that are required to be specified in the configuration.

resourcesPackage: str = 'lsst.daf.butler'¶: Package to search for default configuration data. The resources themselves will be within a configs resource hierarchy.

Methods Documentation

asArray(name)¶

Get a value as an array.

May contain one or more elements.

Parameters:

namestr: Key to use to retrieve value.

Returns:

arraycollections.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 environment to determine search paths to use.

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:

pathslist: Returns a list of paths to search. The returned order is in priority with the highest priority paths first. The butler config configuration resources will not be included here but will always be searched last.

Notes

The environment variable is split on the standard : path separator. This currently makes it incompatible with usage of URIs.

dump(output: Optional[IO] = None, format: str = 'yaml') → Optional[str]¶

Write the config to an output stream.

Parameters:

outputIO, optional: The stream to use for output. If None the serialized content will be returned.
formatstr, optional: The format to use for the output. Can be “yaml” or “json”.

Returns:

serializedstr or None: If a stream was given the stream will be used and the return value will be None. If the stream was None the serialization will be returned as a string.

dumpToUri(uri: Union[str, ParseResult, ResourcePath, Path], updateFile: bool = True, defaultFileName: str = 'butler.yaml', overwrite: bool = True) → None¶

Write the config to location pointed to by given URI.

Currently supports ‘s3’ and ‘file’ URI schemes.

Parameters:

uri: `lsst.resources.ResourcePathExpression`: URI of location where the Config will be written.
updateFilebool, optional: If True and uri does not end on a filename with extension, will append defaultFileName to the target uri. True by default.
defaultFileNamebool, optional: The file name that will be appended to target uri if updateFile is True and uri does not end on a file with an extension.
overwritebool, optional: If True the configuration will be written even if it already exists at that location.

classmethod fromString(string: str, format: str = 'yaml') → Config¶

Create a new Config instance from a serialized string.

Parameters:

stringstr: String containing content in specified format
formatstr, optional: Format of the supplied string. Can be json or yaml.

Returns:

cConfig: Newly-constructed Config.

classmethod fromYaml(string: str) → Config¶

Create a new Config instance from a YAML string.

Parameters:

stringstr: String containing content in YAML format

Returns:

cConfig: Newly-constructed Config.

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¶

makeBuilder() → DimensionConstructionBuilder¶

Construct a DinmensionConstructionBuilder.

The builder will reflect this configuration.

Returns:

builderDimensionConstructionBuilder: A builder object populated with all visitors from this configuration. The finish method will not have been called.

merge(other)¶

Merge another Config into this one.

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:

otherdict 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:

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

Returns:

nameslist 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:

topLevelOnlybool, optional: If False, the default, a full hierarchy of names is returned. If True, only the top level are returned.
delimiterstr, 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:

nameslist 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()¶

Return config as formatted readable string.

Returns:

sstr: A prettyprint formatted string representing the config

Examples

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

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

toDict()¶

Convert a Config to a standalone hierarchical dict.

Returns:

ddict: The standalone hierarchical dict with any Config classes in the hierarchy converted to dict.

Notes

This can be useful when passing a Config to some code that expects native Python types.

update(other)¶

Update config from other Config or dict.

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

Parameters:

otherdict or Config: Source of configuration:

Examples

>>> c = Config({"a": {"b": 1}})
>>> c.update({"a": {"c": 2}})
>>> print(c)
{'a': {'b': 1, 'c': 2}}

>>> foo = {"a": {"b": 1}}
>>> foo.update({"a": {"c": 2}})
>>> print(foo)
{'a': {'c': 2}}

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

Update 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:

configTypeConfigSubset

Config type to use to extract relevant items from config.

configConfig

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.

fullConfig

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.

toUpdatedict, 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.

toCopytuple, optional

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

overwritebool, optional

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

toMergetuple, optional

Keys to merge content from full to config without overwriting pre-existing values. Only works if the key refers to a hierarchy. The overwrite flag is ignored.

Raises:

ValueError: Neither toUpdate, toCopy nor toMerge 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¶

Navigation

DimensionConfig¶