CollectionSummary

class lsst.daf.butler.registry.CollectionSummary(dataset_types: ~lsst.daf.butler._named.NamedValueSet[~lsst.daf.butler._dataset_type.DatasetType] = <factory>, governors: dict[str, set[str]] = <factory>)

Bases: object

A summary of the datasets that can be found in a collection.

Methods Summary

add_data_ids(dataset_type, data_ids)

Include the given dataset type and data IDs in the summary.

add_data_ids_generator(dataset_type, data_ids)

Include the given dataset type and data IDs in the summary, yielding them back as a generator.

add_datasets(refs)

Include the given datasets in the summary.

add_datasets_generator(refs)

Include the given datasets in the summary, yielding them back as a generator.

copy()

Return a deep copy of this object.

is_compatible_with(dataset_type, dimensions)

Test whether the collection summarized by this object should be queried for a given dataset type and governor dimension values.

union()

Construct a summary that contains all dataset types and governor dimension values in any of the inputs.

update(*args)

Update this summary with dataset types and governor dimension values from other summaries.

Methods Documentation

add_data_ids(dataset_type: DatasetType, data_ids: Iterable[DataCoordinate]) → None

Include the given dataset type and data IDs in the summary.

Parameters:
dataset_typeDatasetType

Dataset type to include.

data_idsIterable [ DataCoordinate ]

Data IDs to include.

add_data_ids_generator(dataset_type: DatasetType, data_ids: Iterable[DataCoordinate]) → Generator[DataCoordinate, None, None]

Include the given dataset type and data IDs in the summary, yielding them back as a generator.

Parameters:
dataset_typeDatasetType

Dataset type to include.

data_idsIterable [ DataCoordinate ]

Data IDs to include.

Yields:
data_idDataCoordinate

The same data IDs originally passed in.

Notes

As a generator, this method does nothing if its return iterator is not used. Call add_data_ids instead to avoid this; this method is intended for the case where the given iterable may be single-pass and a copy is not desired, but other processing needs to be done on its elements.

add_datasets(refs: Iterable[DatasetRef]) → None

Include the given datasets in the summary.

Parameters:
refsIterable [ DatasetRef ]

Datasets to include.

add_datasets_generator(refs: Iterable[DatasetRef]) → Generator[DatasetRef, None, None]

Include the given datasets in the summary, yielding them back as a generator.

Parameters:
refsIterable [ DatasetRef ]

Datasets to include.

Yields:
refDatasetRef

The same dataset references originally passed in.

Notes

As a generator, this method does nothing if its return iterator is not used. Call add_datasets instead to avoid this; this method is intended for the case where the given iterable may be single-pass and a copy is not desired, but other processing needs to be done on its elements.

copy() → CollectionSummary

Return a deep copy of this object.

Returns:
copyCollectionSummary

A copy of self that can be modified without modifying self at all.

is_compatible_with(dataset_type: DatasetType, dimensions: Mapping[str, Set[str]], rejections: list[str] | None = None, name: str | None = None) → bool

Test whether the collection summarized by this object should be queried for a given dataset type and governor dimension values.

Parameters:
dataset_typeDatasetType

Dataset type being queried. If this collection has no instances of this dataset type (or its parent dataset type, if it is a component), False will always be returned.

dimensionsMapping

Bounds on the values governor dimensions can take in the query, usually from a WHERE expression, as a mapping from dimension name to a set of str governor dimension values.

rejectionslist [ str ], optional

If provided, a list that will be populated with a log- or exception-friendly message explaining why this dataset is incompatible with this collection when False is returned.

namestr, optional

Name of the collection this object summarizes, for use in messages appended to rejections. Ignored if rejections is None.

Returns:
compatiblebool

True if the dataset query described by this summary and the given arguments might yield non-empty results; False if the result from such a query is definitely empty.

union() → CollectionSummary

Construct a summary that contains all dataset types and governor dimension values in any of the inputs.

Parameters:
*argsCollectionSummary

Summaries to combine.

Returns:
unionedCollectionSummary

New summary object that represents the union of the given ones.

update(*args: CollectionSummary) → None

Update this summary with dataset types and governor dimension values from other summaries.

Parameters:
*argsCollectionSummary

Summaries to include in self.