YamlFormatter

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

Bases: TypelessFormatter

Read and write YAML files.

Attributes Summary

can_read_from_uri	Declare whether read_from_uri is available to this formatter.
default_extension	Default extension to use when writing a file.
supported_write_parameters	Parameters understood by this formatter that can be used to control how a dataset is serialized.
unsupported_parameters	Set of read parameters not understood by this Formatter.

Methods Summary

read_from_uri(uri[, component, expected_size])	Read a dataset from a URI that can be local or remote.
to_bytes(in_memory_dataset)	Write the in memory dataset to a bytestring.

Attributes Documentation

can_read_from_uri: ClassVar[bool] = True

Declare whether read_from_uri is available to this formatter.

default_extension: ClassVar[str | None] = '.yaml'

Default extension to use when writing a file.

Can be None if the extension is determined dynamically. Use the get_write_extension method to get the actual extension to use.

supported_write_parameters: ClassVar[Set[str] | None] = frozenset({'unsafe_dump'})

Parameters understood by this formatter that can be used to control how a dataset is serialized. None indicates that no parameters are supported.

unsupported_parameters: ClassVar[Set[str] | None] = None

Set of read parameters not understood by this Formatter. An empty set means all parameters are supported. None indicates that no parameters are supported. These parameters should match those defined in the storage class definition. (frozenset).

Methods Documentation

read_from_uri(uri: ResourcePath, component: str | None = None, expected_size: int = -1) → Any

Read a dataset from a URI that can be local or remote.

Parameters:

urilsst.resources.ResourcePath

URI to use to read the dataset. This URI can be local or remote and can refer to the actual resource or to a locally cached file.

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 support for direct reads from a, possibly, remote URI.

Notes

This method is only called if the class property can_read_from_uri is set to True.

It is possible that a cached local file will be given to this method even if it was originally a remote URI. This can happen if the original write resulted in the file being added to the local cache.

If the full file is being read this file will not be added to the local cache. Consider returning NotImplemented in this situation, for example if there are no parameters or component specified, and allowing the system to fall back to calling read_from_local_file (which will populate the cache if configured to do so).

to_bytes(in_memory_dataset: Any) → bytes

Write the in memory dataset to a bytestring.

Will look for _asdict() method to aid YAML serialization, following the approach of the simplejson module. Additionally, can attempt to detect pydantic.BaseModel.

The dict will be passed to the relevant constructor on read if not explicitly handled by Pyyaml.

Parameters:

in_memory_datasetobject

Object to serialize.

Returns:

serialized_datasetbytes

YAML string encoded to bytes.

Raises:

Exception

The object could not be serialized.

Notes

SafeDumper is used when generating the YAML serialization. This will fail for data structures that have complex python classes without a registered YAML representer.