CollectionQuery

class lsst.daf.butler.registry.wildcards.CollectionQuery(search: lsst.daf.butler.registry.wildcards.CollectionSearch | ellipsis[lsst.daf.butler.registry.wildcards.CollectionSearch, ellipsis] = Ellipsis, patterns: tuple = ())

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.

universe : DimensionUniverse

Object managing all dimensions.

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.

Methods Summary

explicitNames() Iterate over collection names that were specified explicitly.
fromExpression(expression) Process a general expression to construct a CollectionQuery instance.
iter(manager, *, collectionTypes, …) Iterate over collection records that match this instance and the given criteria, in an arbitrary order.

Methods Documentation

explicitNames() → collections.abc.Iterator[str]

Iterate over collection names that were specified explicitly.

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

Process a general expression to construct a CollectionQuery instance.

Parameters:
expression
May be:

Duplicate collection names will be removed (preserving the first appearance of each collection name).

Returns:
collections : CollectionQuery

A CollectionQuery instance.

iter(manager: CollectionManager, *, collectionTypes: Set[CollectionType] = frozenset({<CollectionType.RUN: 1>, <CollectionType.TAGGED: 2>, <CollectionType.CHAINED: 3>, <CollectionType.CALIBRATION: 4>}), flattenChains: bool = True, includeChains: bool | None = 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.

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.