DimensionRecord

class lsst.daf.butler.DimensionRecord(**kwargs: Any)

Bases: object

Base class for the Python representation of database records.

Parameters:

**kwargs

Field values for this record. Unrecognized keys are ignored. If this is the record for a Dimension, its primary key value may be provided with the actual name of the field (e.g. “id” or “name”), the name of the Dimension, or both. If this record class has a “timespan” attribute, “datetime_begin” and “datetime_end” keyword arguments may be provided instead of a single “timespan” keyword argument (but are ignored if a “timespan” argument is provided).

Notes

DimensionRecord subclasses are created dynamically for each DimensionElement in a DimensionUniverse, and are accessible via the DimensionElement.RecordClass attribute. The DimensionRecord base class itself is pure abstract, but does not use the abc module to indicate this because it does not have overridable methods.

Record classes have attributes that correspond exactly to the standard fields in the related database table, plus “region” and “timespan” attributes for spatial and/or temporal elements (respectively).

Instances are usually obtained from a Registry, but can be constructed directly from Python as well.

DimensionRecord instances are immutable.

Attributes Summary

dataId

A dict-like identifier for this record's primary keys (DataCoordinate).

Methods Summary

deserialize_key(raw)	Deserialize just the key slice of the raw list serializeation of a dimension record.
deserialize_value(key, raw_value)	Deserialize the value slice of the raw list form of serialized dimension record.
from_json(json_str[, universe, registry])	Convert from JSON to a pydantic model.
from_simple(simple[, universe, registry, ...])	Construct a new object from the simplified form.
get(name)	Return a single metadata value associated with this record.
serialize_key_value()	Serialize this record to a list that can be sliced into a key (data ID values) / value (everything else) pair.
toDict([splitTimespan])	Return a vanilla dict representation of this record.
to_json([minimal])	Convert this class to JSON assuming that the to_simple() returns a pydantic model.
to_simple([minimal])	Convert this class to a simple python type.

Attributes Documentation

dataId: DataCoordinate

A dict-like identifier for this record’s primary keys (DataCoordinate).

Methods Documentation

classmethod deserialize_key(raw: list[Any]) → tuple[tuple[int | str, ...], list[Any]]

Deserialize just the key slice of the raw list serializeation of a dimension record.

Parameters:

rawlist

Serialized list with JSON-compatible types, as returned by serialize_key_value.

Returns:

keytuple

Validated tuple of required data ID values that uniquely identify this record, extracted from the head of raw.

raw_valuelist

Remaining unvalidated fields.

classmethod deserialize_value(key: tuple[int | str, ...], raw_value: list[Any]) → DimensionRecord

Deserialize the value slice of the raw list form of serialized dimension record.

Parameters:

keytuple

Validated tuple of required data ID values that uniquely identify this record, as returned by deserialize_key.

raw_valuelist

Serialized list with JSON-compatible types, with just the non-key items, as returned by deserialize_key.

Returns:

recordDimensionRecord

A fully-validated DimensionRecord with this subclass.

classmethod from_json(json_str: str | bytes | bytearray, universe: DimensionUniverse | None = None, registry: Registry | None = None) → SupportsSimple

Convert from JSON to a pydantic model.

Parameters:

cls_type of SupportsSimple

The Python type being created.

json_strstr or bytes or bytearray

The JSON string representing this object.

universeDimensionUniverse or None, optional

The universe required to instantiate some models. Required if registry is None.

registryRegistry or None, optional

Registry from which to obtain the dimension universe if an explicit universe has not been given.

Returns:

modelSupportsSimple

Pydantic model constructed from JSON and validated.

classmethod from_simple(simple: SerializedDimensionRecord, universe: DimensionUniverse | None = None, registry: Registry | None = None, cacheKey: Hashable | None = None) → DimensionRecord

Construct a new object from the simplified form.

This is generally data returned from the to_simple method.

Parameters:

simpleSerializedDimensionRecord

Value return from to_simple.

universeDimensionUniverse

The special graph of all known dimensions of which this graph will be a subset. Can be None if Registry is provided.

registrylsst.daf.butler.Registry, optional

Registry from which a universe can be extracted. Can be None if universe is provided explicitly.

cacheKeyHashable or None

If this is not None, it will be used as a key for any cached reconstruction instead of calculating a value from the serialized format.

Returns:

recordDimensionRecord

Newly-constructed object.

get(name: str) → Any

Return a single metadata value associated with this record.

Parameters:

namestr

Key of the metadata value to be retrieved.

Returns:

value

The metadata value.

Raises:

KeyError

If the given name is not a valid key in this dimension record.

serialize_key_value() → list[Any]

Serialize this record to a list that can be sliced into a key (data ID values) / value (everything else) pair.

Returns:

rawlist

List of values with JSON-compatible types.

Notes

Unlike to_simple / from_simple, this serialization approach does not encode the definition element in the serialized form. This is expected to be serialized separately (e.g. as part of a homogeneous set of dimension records).

toDict(splitTimespan: bool = False) → dict[str, Any]

Return a vanilla dict representation of this record.

Parameters:

splitTimespanbool, optional

If True (False is default) transform any “timespan” key value from a Timespan instance into a pair of regular (“datetime_begin”, “datetime_end”) fields.

to_json(minimal: bool = False) → str

Convert this class to JSON assuming that the to_simple() returns a pydantic model.

Parameters:

minimalbool

Return minimal possible representation.

to_simple(minimal: bool = False) → SerializedDimensionRecord

Convert this class to a simple python type.

This makes it suitable for serialization.

Parameters:

minimalbool, optional

Use minimal serialization. Has no effect on for this class.

Returns:

nameslist

The names of the dimensions.