FileTemplates

class lsst.daf.butler.FileTemplates(config, default=None, universe=None)

Bases: object

Collection of FileTemplate templates.

Parameters:

config : FileTemplatesConfig or str

Load configuration.

default : str, optional

If not None, a default template to use if no template has been specified explicitly in the configuration.

universe : DimensionUniverse, optional

The set of all known dimensions. If not None, any look up keys involving dimensions will be normalized. Normalization only happens once.

Notes

The configuration can include one level of hierarchy where an instrument-specific section can be defined to override more general template specifications. This is represented in YAML using a key of form instrument<name> which can then define templates that will be returned if a DatasetRef contains a matching instrument name in the data ID.

A default fallback template can be specified using the key default. Defaulting can be disabled in a child configuration by defining the value to be an empty string or a boolean False.

The config is parsed using the function processLookupConfigs.

Attributes Summary

defaultKey	Configuration key associated with the default template.
templates	Collection of templates indexed by lookup key (dict).

Methods Summary

getLookupKeys()	Retrieve the look up keys for all the template entries.
getTemplate(entity)	Retrieve the FileTemplate associated with the dataset type.
getTemplateWithMatch(entity)	Retrieve the FileTemplate associated with the dataset type along with the lookup key that was a match for this template.
normalizeDimensions(universe)	Normalize template lookups that use dimensions.
validateTemplates(entities[, logFailures])	Retrieve the template associated with each dataset type and validate the dimensions against the template.

Attributes Documentation

defaultKey = LookupKey(name='default',)

Configuration key associated with the default template.

templates

Collection of templates indexed by lookup key (dict).

Methods Documentation

getLookupKeys()

Retrieve the look up keys for all the template entries.

Returns:

keys : set of LookupKey

The keys available for matching a template.

getTemplate(entity)

Retrieve the FileTemplate associated with the dataset type.

If the lookup name corresponds to a component the base name for the component will be examined if the full component name does not match.

Parameters:

entity : DatasetType, DatasetRef, or StorageClass

Instance to use to look for a corresponding template. A DatasetType name or a StorageClass name will be used depending on the supplied entity. Priority is given to a DatasetType name. Supports instrument override if a DatasetRef is provided configured with an instrument value for the data ID.

Returns:

template : FileTemplate

Template instance to use with that dataset type.

Raises:

KeyError

Raised if no template could be located for this Dataset type.

getTemplateWithMatch(entity)

Retrieve the FileTemplate associated with the dataset type along with the lookup key that was a match for this template.

If the lookup name corresponds to a component the base name for the component will be examined if the full component name does not match.

Parameters:

entity : DatasetType, DatasetRef, or StorageClass

Instance to use to look for a corresponding template. A DatasetType name or a StorageClass name will be used depending on the supplied entity. Priority is given to a DatasetType name. Supports instrument override if a DatasetRef is provided configured with an instrument value for the data ID.

Returns:

matchKey : LookupKey

The key that resulted in the successful match.

template : FileTemplate

Template instance to use with that dataset type.

Raises:

KeyError

Raised if no template could be located for this Dataset type.

normalizeDimensions(universe)

Normalize template lookups that use dimensions.

Parameters:

universe : DimensionUniverse

The set of all known dimensions. If None, returns without action.

Raises:

ValueError

Raised if a key exists where a dimension is not part of the universe.

Notes

Goes through all registered templates, and for keys that include dimensions, rewrites those keys to use a verified set of dimensions.

Returns without action if the template keys have already been normalized.

validateTemplates(entities, logFailures=False)

Retrieve the template associated with each dataset type and validate the dimensions against the template.

Parameters:

entities : DatasetType, DatasetRef, or StorageClass

Entities to validate against the matching templates. Can be differing types.

logFailures : bool, optional

If True, output a log message for every validation error detected.

Raises:

FileTemplateValidationError

Raised if an entity failed validation.

Notes

See FileTemplate.validateTemplate() for details on the validation.