FileTemplate

class lsst.daf.butler.FileTemplate(template: str)

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

• run: str, name of the run this dataset was added with

run must always be provided to ensure unique paths.

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 supplied entity that wants to use it.

Attributes Documentation

datasetFields = {'component', 'datasetType'}

Fields related to the supplied dataset, not a dimension.

mandatoryFields = {'id', 'run'}

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

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

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

Methods Documentation

fields(optionals: bool = False, specials: bool = False, subfields: bool = False) → Set[str]

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: DatasetRef) → str

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.

RuntimeError

Raised if a template uses dimension record metadata but no records are attached to the DatasetRef.

validateTemplate(entity: DatasetRef | DatasetType | StorageClass | None) → None

Compare the template against supplied entity that wants to use it.

Parameters:

entityDatasetType, DatasetRef, or StorageClass

Entity to compare against template. If None is given only very basic validation of templates will be performed.

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.