FormatterV1inV2

class lsst.daf.butler.FormatterV1inV2(file_descriptor: FileDescriptor, *, ref: DatasetRef, formatter: Formatter, write_parameters: Mapping[str, Any] | None = None, write_recipes: Mapping[str, Any] | None = None, **kwargs: Any)

Bases: FormatterV2

An implementation of a V2 formatter that provides a compatibility interface for V1 formatters.

Parameters

file_descriptorFileDescriptor, 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.

refDatasetRef

The dataset associated with this formatter. Should not be a component dataset ref.

formatterFormatter

A version 1 Formatter instance. The V2 formatter layer forwards calls to this formatter.

write_parametersdict, optional

Any parameters to be hard-coded into this instance to control how the dataset is serialized.

write_recipesdict, optional

Detailed write Recipes indexed by recipe name.

**kwargs

Additional arguments that will be ignored but allow for Formatter V1 parameters to be given.

Attributes Summary

can_read_from_local_file

This formatter can read from a local file.

Methods Summary

get_write_extension()	Extension to use when writing a file.
read_from_local_file(path[, component, ...])	Read a dataset from a URI guaranteed to refer to the local file system.
segregate_parameters([parameters])	Segregate the supplied parameters.
to_bytes(in_memory_dataset)	Serialize the in-memory dataset to bytes.
validate_write_recipes(recipes)	Validate supplied recipes for this formatter.
write_local_file(in_memory_dataset, uri)	Serialize the in-memory dataset to a local file.

Attributes Documentation

can_read_from_local_file: ClassVar[bool] = True

This formatter can read from a local file.

Methods Documentation

get_write_extension() → str

Extension to use when writing a file.

read_from_local_file(path: str, component: str | None = None, expected_size: int = -1) → Any

Read a dataset from a URI guaranteed to refer to the local file system.

Parameters

pathstr

Path to a local file that should be read.

componentstr or None, optional

The component to be read from the dataset.

expected_sizeint, optional

If known, the expected size of the resource to read. This can be -1 indicates the file size is not known.

Returns

in_memory_datasetobject or NotImplemented

The Python object read from the resource or NotImplemented.

Raises

FormatterNotImplementedError

Raised if there is no implementation written to read data from a local file.

Notes

This method will only be called if the class property can_read_from_local_file is True and other options were not used.

segregate_parameters(parameters: dict[str, Any] | None = None) → tuple[dict, dict]

Segregate the supplied parameters.

This splits the 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

parametersdict, 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

supporteddict

Those parameters supported by this formatter.

unsupporteddict

Those parameters not supported by this formatter.

to_bytes(in_memory_dataset: Any) → bytes

Serialize the in-memory dataset to bytes.

Parameters

in_memory_datasetobject

The Python object to serialize.

Returns

serialized_datasetbytes

Bytes representing the serialized dataset.

Raises

FormatterNotImplementedError

Raised if the formatter has not implemented the method. This will not cause a problem if write_local_file has been implemented.

validate_write_recipes(recipes: Mapping[str, Any] | None) → Mapping[str, Any] | None

Validate supplied recipes for this formatter.

The recipes are supplemented with default values where appropriate.

Parameters

recipesdict

Recipes to validate.

Returns

validateddict

Validated recipes.

Raises

RuntimeError

Raised if validation fails. The default implementation raises if any recipes are given.

write_local_file(in_memory_dataset: Any, uri: ResourcePath) → None

Serialize the in-memory dataset to a local file.

Parameters

in_memory_datasetobject

The Python object to serialize.

uriResourcePath

The URI to use when writing the file.

Notes

By default this method will attempt to call to_bytes and then write these bytes to the file.

Raises

FormatterNotImplementedError

Raised if the formatter subclass has not implemented this method or has failed to implement the to_bytes method.