DataIdPacker

class lsst.daf.butler.DataIdPacker

Bases: object

An abstract base class for a bidirectional mappings between a DataId and a packed integer or bytes blob.

Derived class constructors must accept at least the positional argments required by the base class contructor, but may accept additional keyword subclass-specific arguments as well (see configure).

Parameters:

dimensions : DataIdPackerDimensions

Struct containing dimensions related to this DataIdPacker.

kwds

Additional subclass-specific keyword arguments. Values for these arguments are obtained from the Registry database according to the how the packer is configured in the `Registry.

Notes

DataIdPacker subclass instances should generally be obtained from a Registry. This involves the following steps:

• One or more packers are configured in the dataIdPackers section of the Registry configuration. In YAML form, that looks something like this:

  See DataIdPackerDimensions for a description of the given and required options. The parameters section maps keyword argument names for the DataIdPacker subclass constructor to dimension metadata fields in the Registry database that provide the values for these arguments.

• A DataId that identifies at least the “given” dimensions of the DataIdPacker subclass must be expanded to include those metadata fields, by calling Registry.expandDataId.

• Registry.makeDataIdPacker is called with the name of the packer and the expanded DataId. If the DataId also identifies all “required” dimensions for the packer, Registry.packDataId can be called instead for convenience (though this does not provide a way to call unpack).

Attributes Summary

dimensions	The dimensions associated with the DataIdPacker (DataIdPackerDimensions).
maxBits	The maximum number of nonzero bits in the packed ID returned by pack (int).

Methods Summary

pack(dataId, *[, returnMaxBits])	Pack the given data ID into a single integer.
unpack(packedId)	Unpack an ID produced by pack into a full DataId.

Attributes Documentation

dimensions

The dimensions associated with the DataIdPacker (DataIdPackerDimensions).

maxBits

The maximum number of nonzero bits in the packed ID returned by pack (int).

Must be implemented by all concrete derived classes. May return None to indicate that there is no maximum.

Methods Documentation

pack(dataId, *, returnMaxBits=False, **kwds)

Pack the given data ID into a single integer.

Parameters:

dataId : dict or DataId

Dictionary-like object identifying (at least) all required dimensions associated with this packer. Subclasses should in general accept an arbitrary mapping and call the DataId constructor internally to standardize. Values for any keys also present in the data ID passed at construction must be the same as the values in the data ID passed at construction.

returnMaxBits : bool

If True, return a tuple of (packed, self.maxBits).

kwds

Additional keyword arguments forwarded to the DataId constructor.

Returns:

packed : int

Packed integer ID.

maxBits : int, optional

Maximum number of nonzero bits in packed. Not returned unless returnMaxBits is True.

Notes

Should not be overridden by derived class (_pack should be overridden instead).

unpack(packedId)

Unpack an ID produced by pack into a full DataId.

Must be implemented by all concrete derived classes.

Parameters:

packedId : int or bytes

The result of a call to pack on either self or an identically-constructed one.

Returns:

dataId : DataId

Dictionary-like ID that uniquely identifies all covered dimensions.