FormatterFactory¶

class lsst.daf.butler.FormatterFactory¶

Bases: object

Factory for Formatter instances.

Attributes Summary

`defaultKey`	Configuration key associated with default write parameter settings.
`writeRecipesKey`	Configuration key associated with write recipes.

Methods Summary

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

Attributes Documentation

defaultKey = LookupKey(name='default',)¶: Configuration key associated with default write parameter settings.

writeRecipesKey = LookupKey(name='write_recipes',)¶: Configuration key associated with write recipes.

Methods Documentation

getFormatter(entity: DatasetType | DatasetRef | StorageClass | str, *args: Any, **kwargs: Any) → Formatter¶

Get a new formatter instance.

Parameters:

entityDatasetRef, 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.
argstuple: Positional arguments to use pass to the object constructor.
**kwargs: Keyword arguments to pass to object constructor.

Returns:

formatterFormatter: An instance of the registered formatter.

getFormatterClass(entity: DatasetType | DatasetRef | StorageClass | str) → Type¶

Get the matching formatter class.

Parameters:

entityDatasetRef, 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:

formattertype: The class of the registered formatter.

getFormatterClassWithMatch(entity: DatasetType | DatasetRef | StorageClass | str) → Tuple[LookupKey, Type[Formatter], Dict[str, Any]]¶

Get the matching formatter class along with the registry key.

Parameters:

entityDatasetRef, 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:

matchKeyLookupKey: The key that resulted in the successful match.
formattertype: The class of the registered formatter.
formatter_kwargsdict: Keyword arguments that are associated with this formatter entry.

getFormatterWithMatch(entity: DatasetType | DatasetRef | StorageClass | str, *args: Any, **kwargs: Any) → Tuple[LookupKey, Formatter]¶

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

Parameters:

entityDatasetRef, 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.
argstuple: Positional arguments to use pass to the object constructor.
**kwargs: Keyword arguments to pass to object constructor.

Returns:

matchKeyLookupKey: The key that resulted in the successful match.
formatterFormatter: An instance of the registered formatter.

getLookupKeys() → Set[LookupKey]¶

Retrieve the look up keys for all the registry entries.

Returns:

keysset of LookupKey: The keys available for matching in the registry.

registerFormatter(type_: LookupKey | str | StorageClass | DatasetType, formatter: str, *, overwrite: bool = False, **kwargs: Any) → 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.
formatterstr or class of type Formatter: Identifies a Formatter subclass to use for reading and writing Datasets of this type. Can be a Formatter class.
overwritebool, optional: If True an existing entry will be replaced by the new value. Default is False.
**kwargs: Keyword arguments to always pass to object constructor when retrieved.

Raises:

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

registerFormatters(config: Config, *, universe: DimensionUniverse) → None¶

Bulk register formatters from a config.

Parameters:

configConfig: formatters section of a configuration.
universeDimensionUniverse, 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.

The values for formatter entries can be either a simple string referring to a python type or a dict representing the formatter and parameters to be hard-coded into the formatter constructor. For the dict case the following keys are supported:

formatter: The python type to be used as the formatter class.
parameters: A further dict to be passed directly to the
writeParameters Formatter constructor to seed it. These parameters are validated at instance creation and not at configuration.

Additionally, a special default section can be defined that uses the formatter type (class) name as the keys and specifies default write parameters that should be used whenever an instance of that class is constructed.

formatters:
  default:
    lsst.daf.butler.formatters.example.ExampleFormatter:
      max: 10
      min: 2
      comment: Default comment
  calexp: lsst.daf.butler.formatters.example.ExampleFormatter
  coadd:
    formatter: lsst.daf.butler.formatters.example.ExampleFormatter
    parameters:
      max: 5

Any time an ExampleFormatter is constructed it will use those parameters. If an explicit entry later in the configuration specifies a different set of parameters, the two will be merged with the later entry taking priority. In the example above calexp will use the default parameters but coadd will override the value for max.

Formatter configuration can also include a special section describing collections of write parameters that can be accessed through a simple label. This allows common collections of options to be specified in one place in the configuration and reused later. The write_recipes section is indexed by Formatter class name and each key is the label to associate with the parameters.

formatters:
  write_recipes:
    lsst.obs.base.formatters.fitsExposure.FixExposureFormatter:
      lossless:
        ...
      noCompression:
        ...

By convention a formatter that uses write recipes will support a recipe write parameter that will refer to a recipe name in the write_recipes component. The Formatter will be constructed in the FormatterFactory with all the relevant recipes and will not attempt to filter by looking at writeParameters in advance. See the specific formatter documentation for details on acceptable recipe options.

Navigation

FormatterFactory¶