FileTemplate

class lsst.daf.butler.FileTemplate(template)

Bases: object

Format a path template into a fully expanded path.

Parameters:

template : str

Template string.

Raises:

FileTemplateValidationError

Raised if the template fails basic validation.

Notes

The templates use the standard Format Specification Mini-Language with the caveat that only named fields can be used. The field names are taken from the Dimensions along with several additional fields:

• datasetType: str, DatasetType.name
• component: str, name of the StorageClass component
• run: str, name of the run this dataset was added with
• collection: synonoym for run

At least one of run or collection must be provided to ensure unique filenames.

More detailed information can be requested from dimensions by using a dot notation, so visit.name would use the name of the visit and detector.name_in_raft would use the name of the detector within the raft.

The mini-language is extended to understand a “?” in the format specification. This indicates that a field is optional. If that Dimension is missing the field, along with the text before the field, unless it is a path separator, will be removed from the output path.

By default any “/” in a dataId value will be replaced by “_” to prevent unexpected directories being created in the path. If the “/” should be retained then a special “/” format specifier can be included in the template.

Attributes Summary

datasetFields	Fields related to the supplied dataset, not a dimension.
mandatoryFields	A set of fields, one of which must be present in a template.
specialFields	Set of special fields that are available independently of the defined Dimensions.

Methods Summary

fields([optionals, specials, subfields])	Return the field names used in this template.
format(ref)	Format a template string into a full path.
validateTemplate(entity)	Compare the template against a representative entity that would like to use template.

Attributes Documentation

datasetFields = {'datasetType', 'component'}

Fields related to the supplied dataset, not a dimension.

mandatoryFields = {'collection', 'run'}

A set of fields, one of which must be present in a template.

specialFields = {'collection', 'datasetType', 'run', 'component'}

Set of special fields that are available independently of the defined Dimensions.

Methods Documentation

fields(optionals=False, specials=False, subfields=False)

Return the field names used in this template.

Parameters:

optionals : bool

If True, optional fields are included in the returned set.

specials : bool

If True, non-dimension fields are included.

subfields : bool, optional

If True, fields with syntax a.b are included. If False, the default, only a would be returned.

Returns:

names : set

Names of fields used in this template

Notes

The returned set will include the special values such as datasetType and component.

format(ref)

Format a template string into a full path.

Parameters:

ref : DatasetRef

The dataset to be formatted.

Returns:

path : str

Expanded path.

Raises:

KeyError

Raised if the requested field is not defined and the field is not optional. Or, component is specified but “component” was not part of the template.

validateTemplate(entity)

Compare the template against a representative entity that would like to use template.

Parameters:

entity : DatasetType, DatasetRef, or StorageClass

Entity to compare against template.

Raises:

FileTemplateValidationError

Raised if the template is inconsistent with the supplied entity.

Notes

Validation will always include a check that mandatory fields are present and that at least one field refers to a dimension. If the supplied entity includes a DimensionGraph then it will be used to compare the available dimensions with those specified in the template.