FileTemplate

class lsst.daf.butler.FileTemplate(template)

Bases: object

Format a path template into a fully expanded path.

Parameters

templatestr

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

• collection: str, Run.collection

• run: int, Run.id

At least one or both 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.

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 = {'component', 'datasetType'}

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', 'component', 'datasetType', 'run'}

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

optionalsbool

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

specialsbool

If True, non-dimension fields are included.

subfieldsbool, optional

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

Returns

namesset

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

refDatasetRef

The dataset to be formatted.

Returns

pathstr

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

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