CollectionWildcard

class lsst.daf.butler.registry.wildcards.CollectionWildcard(strings: tuple = (), patterns: tuple[re.Pattern, ...] | ellipsis[tuple, ellipsis] = Ellipsis)

Bases: object

A validated wildcard for collection names

The from_expression 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).

Notes

CollectionWildcard 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 occasionally 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

patterns	Regular expression patterns to match against collection names, or the special value ... indicating all collections.
strings	An an ordered list of explicitly-named collections.

Methods Summary

from_expression(expression, require_ordered)	Process a general expression to construct a CollectionWildcard instance.
from_names(names)	Construct from an iterable of explicit collection names.
require_ordered()	Require that this wildcard contains no patterns, and return the ordered tuple of names that it does hold.

Attributes Documentation

patterns = Ellipsis

Regular expression patterns to match against collection names, or the special value ... indicating all collections.

must be accompanied by strings=().

strings = ()

An an ordered list of explicitly-named collections. (tuple [ str ]).

Methods Documentation

classmethod from_expression(expression: Any, require_ordered: bool = False) → lsst.daf.butler.registry.wildcards.CollectionWildcard

Process a general expression to construct a CollectionWildcard instance.

Parameters:

expression

May be:

• a str collection name;
• an re.Pattern instance to match (with re.Pattern.fullmatch) against collection names;
• any iterable containing any of the above;
• another CollectionWildcard instance (passed through unchanged).

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

require_ordered : bool, optional

If True (False is default) require the expression to be ordered, and raise CollectionExpressionError if it is not.

Returns:

wildcard : CollectionWildcard

A CollectionWildcard instance.

Raises:

CollectionExpressionError

Raised if the patterns has regular expression, glob patterns, or the ... wildcard, and require_ordered=True.

classmethod from_names(names: collections.abc.Iterable[str]) → lsst.daf.butler.registry.wildcards.CollectionWildcard

Construct from an iterable of explicit collection names.

Parameters:

names : Iterable [ str ]

Iterable of collection names.

Returns:

wildcard : ~CollectionWildcard`

A CollectionWildcard instance. require_ordered is guaranteed to succeed and return the given names in order.

require_ordered() → tuple

Require that this wildcard contains no patterns, and return the ordered tuple of names that it does hold.

Returns:

names : tuple [ str ]

Ordered tuple of collection names.

Raises:

CollectionExpressionError

Raised if the patterns has regular expression, glob patterns, or the ... wildcard.