Formatter

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

Bases: object

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.