"""
These objects describe queries, independent of how the actual querying is implemented.
They are used on the client side and the server side.
The are encoded into and decoded from URL query parameters.
"""
import enum
import json
from dataclasses import dataclass
from typing import Any, List
from .query_registration import register
from .structures.core import StructureFamily as StructureFamilyEnum
JSONSerializable = Any # Feel free to refine this.
class NoBool:
def __bool__(self):
raise TypeError(
"""Queries are not "truth-y" or "false-y". They must be passed to search().
You may be seeing this error message because you tried to use a tiled query
with the Python keywords `and` or `or`. This does not (cannot) work.
To compose queries, chain search calls like:
c.search(...).search(...).search(...)
"""
)
[docs]@register(name="fulltext")
@dataclass
class FullText(NoBool):
"""
Search the full text of all metadata values for word matches.
This matches *complete words*, so 'dog' would match 'cat dog elephant',
but 'do' would not match.
Parameters
----------
text : str
case_sensitive : bool, optional
Default False (case-insensitive).
"""
text: str
case_sensitive: bool = False
def encode(self):
return {"text": self.text, "case_sensitive": json.dumps(self.case_sensitive)}
@classmethod
def decode(cls, *, text, case_sensitive=False):
# Note: FastAPI decodes case_sensitive into a boolean for us.
return cls(
text=text,
case_sensitive=case_sensitive,
)
[docs]@register(name="lookup")
@dataclass
class KeyLookup(NoBool):
"""
Match a specific Entry by key. Mostly for internal use.
This is necessary to support item lookup within search results, as in:
>>> tree.search(...)["..."]
The server handles this directly and generically, simply calling __getitem__
on the tree after apply all other queries. Implementations of search(...)
do not need to handle it.
Parameters
----------
key : str
"""
key: str
def encode(self):
return {"key": self.key}
@classmethod
def decode(cls, *, key):
return cls(key=key)
@register(name="keys_filter")
@dataclass
class KeysFilter(NoBool):
"""
Filter entries that do not match one of these keys.
This is used by the SimpleAccessPolicy.
Parameters
----------
keys : List[str]
"""
keys: List[str]
def encode(self):
return {"keys": json.dumps(self.keys)}
@classmethod
def decode(cls, *, keys):
return cls(keys=json.loads(keys))
[docs]@register(name="regex")
@dataclass
class Regex(NoBool):
"""
Match a key's value to a regular expression.
Parameters
----------
key : str
e.g. "color", "sample.name"
pattern : str
regular expression
case_sensitive : bool, optional
Default True (case-sensitive).
Note that this is the opposite of the default for FullText;
regex users generally expect case sensitivity by default.
Examples
--------
Search for color == "red"
>>> c.search(Regex("sample.name", "Cu.*"))
"""
key: str
pattern: str
case_sensitive: bool = True
def encode(self):
return {
"key": self.key,
"pattern": self.pattern,
"case_sensitive": json.dumps(self.case_sensitive),
}
@classmethod
def decode(cls, *, key, pattern, case_sensitive=True):
# Note: FastAPI decodes case_sensitive into a boolean for us.
return cls(
key=key,
pattern=pattern,
case_sensitive=case_sensitive,
)
[docs]@register(name="eq")
@dataclass
class Eq(NoBool):
"""
Query equality of a given key's value to the specified value.
See `Key` in this module for a more intuitive interface for equality.
Parameters
----------
key : str
e.g. "color", "sample.name"
value : JSONSerializable
May be a string, number, list, or dict.
Examples
--------
Search for color == "red"
>>> c.search(Eq("color", "red"))
"""
key: str
value: JSONSerializable
def encode(self):
return {"key": self.key, "value": json.dumps(self.value)}
@classmethod
def decode(cls, *, key, value):
return cls(key=key, value=json.loads(value))
[docs]@register(name="noteq")
@dataclass
class NotEq(NoBool):
"""
Query inequality of a given key's value to the specified value.
See `Key` in this module for a more intuitive interface for inequality.
Parameters
----------
key : str
e.g. "color", "sample.name"
value : JSONSerializable
May be a string, number, list, or dict.
Examples
--------
Search for color == "red"
>>> c.search(Eq("color", "red"))
"""
key: str
value: JSONSerializable
def encode(self):
return {"key": self.key, "value": json.dumps(self.value)}
@classmethod
def decode(cls, *, key, value):
return cls(key=key, value=json.loads(value))
class Operator(str, enum.Enum):
lt = "lt"
gt = "gt"
le = "le"
ge = "ge"
[docs]@register(name="comparison")
@dataclass
class Comparison(NoBool):
"""
Query binary comparison between given key's value to the specified value.
See `Key` in this module for a more intuitive interface for comparisons.
Parameters
----------
operator : {"gt", "lt", "ge", "lt"}
key : str
e.g. "temperature"
value : JSONSerializable
May be a string, number, list, or dict.
Examples
--------
Search for temperature > 300.
>>> c.search(Comparison("gt", "temperature", 300))
"""
operator: Operator
key: str
value: JSONSerializable
[docs] def __init__(self, operator, key, value):
self.operator = Operator(operator)
self.key = key
self.value = value
def encode(self):
return {
"operator": self.operator.value,
"key": self.key,
"value": json.dumps(self.value),
}
@classmethod
def decode(cls, *, operator, key, value):
return cls(operator=Operator(operator), key=key, value=json.loads(value))
[docs]@register(name="contains")
@dataclass
class Contains(NoBool):
"""
Query where a given key's value contains the specified value.
Parameters
----------
key : str
e.g. "motors"
value : JSONSerializable
May be a string, number, list, or dict.
Examples
--------
Search for matches where "ccd" is including the list of detectors.
>>> c.search(Contains("detectors", "ccd"))
"""
key: str
value: JSONSerializable
def encode(self):
return {"key": self.key, "value": json.dumps(self.value)}
@classmethod
def decode(cls, *, key, value):
return cls(key=key, value=json.loads(value))
[docs]@register(name="in")
@dataclass
class In:
"""
Query if a given key's value is present in the specified list of values.
Parameters
----------
key : str
e.g. "color", "sample.name"
value : List[JSONSerializable]
e.g. ["red", "blue"]
Examples
--------
Search for color in ["red", "blue"]
>>> c.search(In("color", ["red", "blue"]))
"""
key: str
value: List[JSONSerializable]
def encode(self):
return {"key": self.key, "value": json.dumps(self.value)}
@classmethod
def decode(cls, *, key, value):
return cls(key=key, value=json.loads(value))
[docs]@register(name="notin")
@dataclass
class NotIn:
"""
Query if a given key's value is not present in the specified list of values.
Parameters
----------
key : str
e.g. "color", "sample.name"
value : List[JSONSerializable]
e.g. ["red", "blue"]
Examples
--------
Search for color not in ["red", "blue"]
>>> c.search(NotIn("color", ["red", "blue"]))
"""
key: str
value: List[JSONSerializable]
def encode(self):
return {"key": self.key, "value": json.dumps(self.value)}
@classmethod
def decode(cls, *, key, value):
return cls(key=key, value=json.loads(value))
[docs]@register(name="specs")
@dataclass(init=False)
class Specs:
"""
Query if specs list matches all elements in include list and does not match any element in exclude list
Parameters
----------
include : List[str]
exclude : List[str]
Examples
--------
Search for specs ["foo", "bar"] and NOT "baz"
>>> c.search(Specs(include=["foo", "bar"], exclude=["baz"]))
"""
include: List[str]
exclude: List[str]
[docs] def __init__(self, include, exclude=None):
exclude = exclude or []
if isinstance(include, str):
raise TypeError("include must be a list not a str")
if isinstance(exclude, str):
raise TypeError("exclude must be a list not a str")
self.include = list(include)
self.exclude = list(exclude)
def encode(self):
return {
"include": json.dumps(self.include),
"exclude": json.dumps(self.exclude),
}
@classmethod
def decode(cls, *, include, exclude):
return cls(include=json.loads(include), exclude=json.loads(exclude))
[docs]def Spec(spec):
"""
Convenience function for querying if specs list contains a given spec
Equivalent to Specs([spec]).
Parameters
----------
spec: str
Examples
--------
Search for spec "foo"
>>> c.search(Spec("foo"))
"""
return Specs([spec])
[docs]@register(name="structure_family")
@dataclass(init=False)
class StructureFamily:
"""
Query if structure_families match value
Parameters
----------
value : StructureFamily
Examples
--------
Search for dataframes
>>> c.search(StructureFamilies("dataframe"))
"""
[docs] def __init__(self, value):
self.value = StructureFamilyEnum(value)
value: StructureFamilyEnum
def encode(self):
return {"value": self.value.value}
@classmethod
def decode(cls, *, value):
return cls(value=value)
[docs]class Key:
"""
Compare a key in the metadata to a value using standard Python operators.
This itself is not a query, but *comparing* it with a value, as shown
in the examples below, produces a query.
Parameters
----------
key : str
Examples
--------
Search for equality, comparison, or membership in a collection.
>>> c.search(Key("color") == "red")
>>> c.search(Key("temperature") >= 300)
>>> c.search(Key("temperature") <= 300)
>>> c.search(Key("position") > 5.0)
>>> c.search(Key("position") < 5.0)
"""
[docs] def __init__(self, key):
self.key = key
def __eq__(self, value):
return Eq(self.key, value)
def __ne__(self, value):
return NotEq(self.key, value)
def __lt__(self, value):
return Comparison("lt", self.key, value)
def __gt__(self, value):
return Comparison("gt", self.key, value)
def __le__(self, value):
return Comparison("le", self.key, value)
def __ge__(self, value):
return Comparison("ge", self.key, value)
# Note: __contains__ cannot be supported because the language coerces
# the result of __contains__ to be a literal boolean. We are not
# allowed to return a custom type.
class QueryValueError(ValueError):
pass