CollectionQuery

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

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

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.

Attributes Documentation

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

Methods Documentation

classmethod fromExpression(expression: Any) → Union[lsst.daf.butler.registry.wildcards.CollectionQuery, ellipsis]

Process a general expression to construct a CollectionQuery instance.

Parameters:

expression

May be:

• a str collection name;
• a two-element tuple containing a str and any expression accepted by DatasetTypeRestriction.fromExpression;
• an re.Pattern instance to match (with re.Pattern.fullmatch) against collection names;
• any non-mapping iterable containing any of the above;
• a mapping from str to any expression accepted by DatasetTypeRestriction.
• a CollectionSearch instance;
• another CollectionQuery instance (passed through unchanged).

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, collectionType: Optional[CollectionType] = None, withRestrictions: bool = False, 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.

collectionType : CollectionType, optional

If given, only yield collections of this type.

withRestrictions : bool, optional

If True (False is default) yield the associated DatasetTypeRestriction along with each CollectionRecord.

flattenChains : bool, optional

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

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.