Formatter¶

class lsst.daf.butler.Formatter(fileDescriptor: lsst.daf.butler.core.fileDescriptor.FileDescriptor)¶

Interface for reading and writing Datasets with a particular StorageClass.

Parameters:	fileDescriptor : `FileDescriptor`, optional Identifies the file to read or write, and the associated storage classes and parameter information. Its value can be `None` if the caller will never call `Formatter.read` or `Formatter.write`.

Attributes Summary

`fileDescriptor`	FileDescriptor associated with this formatter (`FileDescriptor`, read-only)
`unsupportedParameters`	Set of parameters not understood by this `Formatter`.

Methods Summary

`fromBytes`(serializedDataset, component)	Reads serialized data into a Dataset or its component.
`makeUpdatedLocation`(location)	Return a new `Location` instance updated with this formatter’s extension.
`name`()	Returns the fully qualified name of the formatter.
`predictPath`()	Return the path that would be returned by write, without actually writing.
`predictPathFromLocation`(location)	Return the path that would be returned by write, without actually writing.
`read`(component)	Read a Dataset.
`segregateParameters`(parameters, Any]] = None)	Segregate the supplied parameters into those understood by the formatter and those not understood by the formatter.
`toBytes`(inMemoryDataset)	Serialize the Dataset to bytes based on formatter.
`write`(inMemoryDataset)	Write a Dataset.

Attributes Documentation

fileDescriptor¶: FileDescriptor associated with this formatter (FileDescriptor, read-only)

unsupportedParameters = frozenset()¶: Set of parameters not understood by this Formatter. An empty set means all parameters are supported. None indicates that no parameters are supported (frozenset).

Methods Documentation

fromBytes(serializedDataset: bytes, component: Optional[str] = None) → object¶

Reads serialized data into a Dataset or its component.

Parameters:	serializedDataset : `bytes` Bytes object to unserialize. component : `str`, optional Component to read from the Dataset. Only used if the `StorageClass` for reading differed from the `StorageClass` used to write the file.
Returns:	inMemoryDataset : `object` The requested data as a Python object. The type of object is controlled by the specific formatter.

classmethod makeUpdatedLocation(location: lsst.daf.butler.core.location.Location) → lsst.daf.butler.core.location.Location¶

Return a new Location instance updated with this formatter’s extension.

Parameters:	location : `Location` The location to update.
Returns:	updated : `Location` The updated location with a new file extension applied.
Raises:	NotImplementedError Raised if there is no `extension` attribute associated with this formatter.

classmethod name() → str¶

Returns the fully qualified name of the formatter.

Returns:	name : `str` Fully-qualified name of formatter class.

predictPath() → str¶

Return the path that would be returned by write, without actually writing.

Uses the FileDescriptor associated with the instance.

Returns:	path : `str` Path within datastore that would be associated with the location stored in this `Formatter`.

classmethod predictPathFromLocation(location: lsst.daf.butler.core.location.Location) → str¶

Return the path that would be returned by write, without actually writing.

Parameters:	location : `Location` Location of file for which path prediction is required.
Returns:	path : `str` Path within datastore that would be associated with this location.

read(component: Optional[str] = None) → object¶

Read a Dataset.

Parameters:	component : `str`, optional Component to read from the file. Only used if the `StorageClass` for reading differed from the `StorageClass` used to write the file.
Returns:	inMemoryDataset : `object` The requested Dataset.

segregateParameters(parameters: Optional[Dict[str, Any]] = None) → Tuple[Dict[KT, VT], Dict[KT, VT]]¶

Segregate the supplied parameters into those understood by the formatter and those not understood by the formatter.

Any unsupported parameters are assumed to be usable by associated assemblers.

Parameters:	parameters : `dict`, optional Parameters with values that have been supplied by the caller and which might be relevant for the formatter. If `None` parameters will be read from the registered `FileDescriptor`.
Returns:	supported : `dict` Those parameters supported by this formatter. unsupported : `dict` Those parameters not supported by this formatter.

toBytes(inMemoryDataset: Any) → bytes¶

Serialize the Dataset to bytes based on formatter.

Parameters:	inMemoryDataset : `object` The Python object to serialize.
Returns:	serializedDataset : `bytes` Bytes representing the serialized dataset.

write(inMemoryDataset: Any) → str¶

Write a Dataset.

Parameters:	inMemoryDataset : `object` The Dataset to store.
Returns:	path : `str` The path to where the Dataset was stored within the datastore.