CollectionQuery

class lsst.daf.butler.registry.wildcards.CollectionQuery(search: Union[lsst.daf.butler.registry.wildcards.CollectionSearch, ellipsis], patterns: Tuple[re.Pattern, ...])

Bases: object

An unordered query for collections and dataset type restrictions.

The fromExpression method should almost always be used to construct instances, as the regular constructor performs no checking of inputs (and that can lead to confusing error messages downstream).

Parameters:
search : CollectionSearch or

An object representing an ordered search for explicitly-named collections (to be interpreted here as unordered), or the special value indicating all collections. must be accompanied by patterns=None.

patterns : tuple of re.Pattern

Regular expression patterns to match against collection names.

Notes

A CollectionQuery is used to find all matching datasets in any number of collections, or to find collections themselves.

CollectionQuery is expected to be rarely used outside of Registry (which uses it to back several of its “query” methods that take general expressions for collections), but it may occassionally be useful outside Registry as a way to preprocess expressions that contain single-pass iterators into a form that can be used to call those Registry methods multiple times.

Attributes Summary

any A special CollectionQuery instance that matches any collection.

Methods Summary

fromExpression(expression) Process a general expression to construct a CollectionQuery instance.
iter(manager, *, datasetType, …) Iterate over collection records that match this instance and the given criteria, in an arbitrary order.
iterPairs(manager, *, datasetType, …) Like iter, but yield pairs of CollectionRecord, DatasetTypeRestriction instead of just the former.

Attributes Documentation

any = <lsst.daf.butler.registry.wildcards.CollectionQuery object>

A special CollectionQuery instance that matches any collection.

This instance should be preferred instead of constructing a new one with ..., when possible, but it should not be assumed to be the only such instance.

Methods Documentation

classmethod fromExpression(expression: Any) → lsst.daf.butler.registry.wildcards.CollectionQuery

Process a general expression to construct a CollectionQuery instance.

Parameters:
expression
May be:

Multiple consecutive entries for the same collection with different restrictions will be merged. Non-consecutive entries will not, because that actually represents a different search path.
Returns:
collections : CollectionQuery

A CollectionQuery instance.
iter(manager: CollectionManager, *, datasetType: Optional[DatasetType] = None, collectionTypes: AbstractSet[CollectionType] = frozenset({<CollectionType.RUN: 1>, <CollectionType.TAGGED: 2>, <CollectionType.CHAINED: 3>, <CollectionType.CALIBRATION: 4>}), flattenChains: bool = True, includeChains: Optional[bool] = None) → Iterator[CollectionRecord]

Iterate over collection records that match this instance and the given criteria, in an arbitrary order.

This method is primarily intended for internal use by Registry; other callers should generally prefer Registry.queryDatasets or other Registry query methods.

Parameters:
manager : CollectionManager

Object responsible for managing the collection tables in a Registry.

datasetType : DatasetType, optional

If given, only yield collections whose dataset type restrictions include this dataset type.

collectionTypes : AbstractSet [ CollectionType ], optional

If provided, only yield collections of these types.

flattenChains : bool, optional

If True (default) recursively yield the child collections of CHAINED collections.

includeChains : bool, optional

If False, return records for CHAINED collections themselves. The default is the opposite of flattenChains: either return records for CHAINED collections or their children, but not both.
Yields:
record : CollectionRecord

Matching collection records.
iterPairs(manager: CollectionManager, *, datasetType: Optional[DatasetType] = None, collectionTypes: AbstractSet[CollectionType] = frozenset({<CollectionType.RUN: 1>, <CollectionType.TAGGED: 2>, <CollectionType.CHAINED: 3>, <CollectionType.CALIBRATION: 4>}), flattenChains: bool = True, includeChains: Optional[bool] = None) → Iterator[Tuple[CollectionRecord, DatasetTypeRestriction]]

Like iter, but yield pairs of CollectionRecord, DatasetTypeRestriction instead of just the former.

See iter for all parameter descriptions.

Yields:
record : CollectionRecord

Matching collection records.

restriction : DatasetTypeRestriction

The given dataset type restriction.