FormatterFactory

class lsst.daf.butler.FormatterFactory

Bases: object

Factory for Formatter instances.

Methods Summary

getFormatter(entity, …)	Get a new formatter instance.
getFormatterClass(entity, …)	Get the matching formatter class.
getFormatterClassWithMatch(entity, …)	Get the matching formatter class along with the matching registry key.
getFormatterWithMatch(entity, …)	Get a new formatter instance along with the matching registry key.
getLookupKeys()	Retrieve the look up keys for all the registry entries.
registerFormatter(type_, str, …)	Register a Formatter.
registerFormatters(config, *, universe)	Bulk register formatters from a config.

Methods Documentation

getFormatter(entity: Union[lsst.daf.butler.core.datasets.type.DatasetType, lsst.daf.butler.core.datasets.ref.DatasetRef, lsst.daf.butler.core.storageClass.StorageClass, str], *args, **kwargs) → lsst.daf.butler.core.formatter.Formatter

Get a new formatter instance.

Parameters:

entity : DatasetRef, DatasetType, StorageClass, or str

Entity to use to determine the formatter to return. StorageClass will be used as a last resort if DatasetRef or DatasetType instance is provided. Supports instrument override if a DatasetRef is provided configured with an instrument value for the data ID.

args : tuple

Positional arguments to use pass to the object constructor.

kwargs : dict

Keyword arguments to pass to object constructor.

Returns:

formatter : Formatter

An instance of the registered formatter.

getFormatterClass(entity: Union[lsst.daf.butler.core.datasets.type.DatasetType, lsst.daf.butler.core.datasets.ref.DatasetRef, lsst.daf.butler.core.storageClass.StorageClass, str]) → Type[CT_co]

Get the matching formatter class.

Parameters:

entity : DatasetRef, DatasetType, StorageClass, or str

Entity to use to determine the formatter to return. StorageClass will be used as a last resort if DatasetRef or DatasetType instance is provided. Supports instrument override if a DatasetRef is provided configured with an instrument value for the data ID.

Returns:

formatter : type

The class of the registered formatter.

getFormatterClassWithMatch(entity: Union[lsst.daf.butler.core.datasets.type.DatasetType, lsst.daf.butler.core.datasets.ref.DatasetRef, lsst.daf.butler.core.storageClass.StorageClass, str]) → Tuple[lsst.daf.butler.core.configSupport.LookupKey, Type[CT_co]]

Get the matching formatter class along with the matching registry key.

Parameters:

entity : DatasetRef, DatasetType, StorageClass, or str

Entity to use to determine the formatter to return. StorageClass will be used as a last resort if DatasetRef or DatasetType instance is provided. 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.

formatter : type

The class of the registered formatter.

getFormatterWithMatch(entity: Union[lsst.daf.butler.core.datasets.type.DatasetType, lsst.daf.butler.core.datasets.ref.DatasetRef, lsst.daf.butler.core.storageClass.StorageClass, str], *args, **kwargs) → Tuple[lsst.daf.butler.core.configSupport.LookupKey, lsst.daf.butler.core.formatter.Formatter]

Get a new formatter instance along with the matching registry key.

Parameters:

entity : DatasetRef, DatasetType, StorageClass, or str

Entity to use to determine the formatter to return. StorageClass will be used as a last resort if DatasetRef or DatasetType instance is provided. Supports instrument override if a DatasetRef is provided configured with an instrument value for the data ID.

args : tuple

Positional arguments to use pass to the object constructor.

kwargs : dict

Keyword arguments to pass to object constructor.

Returns:

matchKey : LookupKey

The key that resulted in the successful match.

formatter : Formatter

An instance of the registered formatter.

getLookupKeys() → Set[lsst.daf.butler.core.configSupport.LookupKey]

Retrieve the look up keys for all the registry entries.

Returns:

keys : set of LookupKey

The keys available for matching in the registry.

registerFormatter(type_: Union[lsst.daf.butler.core.configSupport.LookupKey, str, lsst.daf.butler.core.storageClass.StorageClass, lsst.daf.butler.core.datasets.type.DatasetType], formatter: str, overwrite: bool = False) → None

Register a Formatter.

Parameters:

type_ : LookupKey, str, StorageClass or DatasetType

Type for which this formatter is to be used. If a LookupKey is not provided, one will be constructed from the supplied string or by using the name property of the supplied entity.

formatter : str or class of type Formatter

Identifies a Formatter subclass to use for reading and writing Datasets of this type. Can be a Formatter class.

overwrite : bool, optional

If True an existing entry will be replaced by the new value. Default is False.

Raises:

ValueError

Raised if the formatter does not name a valid formatter type and overwrite is False.

registerFormatters(config: lsst.daf.butler.core.config.Config, *, universe: lsst.daf.butler.core.dimensions.universe.DimensionUniverse) → None

Bulk register formatters from a config.

Parameters:

config : Config

formatters section of a configuration.

universe : DimensionUniverse, optional

Set of all known dimensions, used to expand and validate any used in lookup keys.

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.

The config is parsed using the function processLookupConfigs.