CategorizedWildcard

class lsst.daf.butler.registry.wildcards.CategorizedWildcard(strings: List[str], patterns: List[re.Pattern], items: List[Tuple[str, Any]])

Bases: object

The results of preprocessing a wildcard expression to separate match patterns from strings.

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

Methods Summary

fromExpression(expression, *, allowAny, …)	Categorize a wildcard expression.
makeWhereExpression(column)	Transform the wildcard into a SQLAlchemy boolean expression suitable for use in a WHERE clause.

Methods Documentation

classmethod fromExpression(expression: Any, *, allowAny: bool = True, allowPatterns: bool = True, coerceUnrecognized: Optional[Callable[[Any], Union[Tuple[str, Any], str]]] = None, coerceItemValue: Optional[Callable[[Any], Any]] = None, defaultItemValue: Optional[Any] = None) → Union[lsst.daf.butler.registry.wildcards.CategorizedWildcard, ellipsis]

Categorize a wildcard expression.

Parameters:

expression

The expression to categorize. May be any of:

• str;
• re.Pattern (only if allowPatterns is True);
• objects recognized by coerceUnrecognized (if provided);
• two-element tuples of (str, value) where value is recognized by coerceItemValue (if provided);
• a non-str, non-mapping iterable containing any of the above;
• the special value (only if allowAny is True), which matches anything;
• a mapping from str to a value are recognized by coerceItemValue (if provided);
• a CategorizedWildcard instance (passed through unchanged if it meets the requirements specified by keyword arguments).

allowAny: `bool`, optional

If False (True is default) raise TypeError if is encountered.

allowPatterns: `bool`, optional

If False (True is default) raise TypeError if a re.Pattern is encountered, or if expression is a CategorizedWildcard with patterns not empty.

coerceUnrecognized: `Callable`, optional

A callback that takes a single argument of arbitrary type and returns either a str - appended to strings - or a tuple of (str, Any) to be appended to items. This will be called on objects of unrecognized type, with the return value added to strings. Exceptions will be reraised as TypeError (and chained).

coerceItemValue: `Callable`, optional

If provided, expression may be a mapping from str to any type that can be passed to this function; the result of that call will be stored instead as the value in self.items.

defaultItemValue: `Any`, optional

If provided, combine this value with any string values encountered (including any returned by coerceUnrecognized) to form a tuple and add it to items, guaranteeing that strings will be empty. Patterns are never added to items.

Returns:

categorized : CategorizedWildcard or ....

The struct describing the wildcard. ... is passed through unchanged.

Raises:

TypeError

Raised if an unsupported type is found in the expression.

makeWhereExpression(column: sqlalchemy.sql.elements.ColumnElement) → Optional[sqlalchemy.sql.elements.ColumnElement]

Transform the wildcard into a SQLAlchemy boolean expression suitable for use in a WHERE clause.

Parameters:

column : sqlalchemy.sql.ColumnElement

A string column in a table or query that should be compared to the wildcard expression.

Returns:

where : sqlalchemy.sql.ColumnElement or None

A boolean SQL expression that evaluates to true if and only if the value of column matches the wildcard. None is returned if both strings and patterns are empty, and hence no match is possible.