python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/data/expressions/comparison.py

@@ -1,22 +1,30 @@
 from typing import Any, Iterable
 
 from corekit.data.expressions.expression import Expression
+from corekit.data.expressions.operator import Operator
+from corekit.data.expressions.target import Target
+
+UNSET = object()
+
+
+class UnknownFieldError(AttributeError):
+    """
+    Raised when an expression names a field the target does not have.
+    """
 
 
 class Comparison(Expression):
     """
     Base for comparing two values (Equals, GreaterThan, IsIn, ...).
 
-    `left`, `right`, and `symbol` are public so external code --
-    e.g. a future translator to SQL/Mongo/Elasticsearch -- can walk the
-    tree and read out what each node represents without evaluating it.
-    `symbol` is a human-readable operator string; the class itself
+    `left`, `right`, and `operator` are public so a translator can walk the
+    tree and read what each node represents without evaluating it. The class itself
     (Equals, GreaterThan, etc.) is the canonical, type-safe identifier of
     *which* operation a node represents, so a translator can dispatch on
     isinstance(node, GreaterThan) rather than string-matching on symbol.
     """
 
-    symbol: str
+    operator: Operator
 
     def __init__(self, left: Any, right: Any) -> None:
         self.left = left
@@ -25,154 +33,153 @@ class Comparison(Expression):
     def __repr__(self) -> str:
         return f"({self.left!r} {self.symbol} {self.right!r})"
 
+    @property
+    def symbol(self) -> str:
+        """
+        The human-readable operator, e.g. ``>=``.
+        """
+        return self.operator.symbol
+
     @staticmethod
-    def _resolve_value(value: Any, *args: Any, **kwargs: Any) -> Any:
+    def resolve(value: Any, *args: Any, **kwargs: Any) -> Any:
         """
-        Resolves a value to a concrete value. This method utilizes a neat trick
-        to be able to resolve the final value of complex expressions without
-        having to evaluate the entire tree.
+        Resolve one operand, passing everything through to the expression.
         """
         if isinstance(value, ValueExpression):
-            return value.get(*args, **kwargs)
+            return value.resolve(*args, **kwargs)
         return value
 
     def get_left(self, *args: Any, **kwargs: Any) -> Any:
-        return self._resolve_value(self.left, *args, **kwargs)
-
-    def get_right(self, *args, **kwargs) -> Any:
         """
-        Returns the right value of the comparison.
+        Whatever is on the left of this comparison, resolved.
         """
-        return self._resolve_value(self.right, *args, **kwargs)
+        return self.resolve(self.left, *args, **kwargs)
 
+    def get_right(self, *args: Any, **kwargs: Any) -> Any:
+        """
+        Whatever is on the right of this comparison, resolved.
+        """
+        return self.resolve(self.right, *args, **kwargs)
 
-class Equals(Comparison):
-    symbol = "=="
+    @property
+    def compares_fields(self) -> bool:
+        """
+        Whether the right side names a field rather than holding a value.
 
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) == self.get_right(*args, **kwargs)
+        A dialect that only compares a field to a value needs a different form
+        for this, so each renderer has to ask.
+        """
+        return isinstance(self.right, FieldExpression)
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} = {self.get_right(*args, **kwargs)}"
+    def _reject_sql(self, reason: str) -> None:
+        """
+        Refuse a form SQL cannot mean the same way Python does.
+        """
+        raise NotImplementedError(f"SQL cannot express `{self.symbol}`: {reason}")
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): self.get_right(*args, **kwargs)}
 
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"term": {self.get_left(*args, **kwargs): self.get_right(*args, **kwargs)}}
+class Equals(Comparison):
+    operator = Operator.EQUALS
 
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) == self.get_right(context, *args, **kwargs)
 
-class NotEquals(Comparison):
-    symbol = "!="
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) == self.get_right(context)
 
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) != self.get_right(*args, **kwargs)
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} != {self.get_right(*args, **kwargs)}"
+class NotEquals(Comparison):
+    operator = Operator.NOT_EQUALS
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): {"$ne": self.get_right(*args, **kwargs)}}
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) != self.get_right(context, *args, **kwargs)
 
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"term": {self.get_left(*args, **kwargs): {"$ne": self.get_right(*args, **kwargs)}}}
+    def to_sqlalchemy(self, context: Any) -> Any:
+        left = self.get_left(context)
+        # Python treats None != value as True. SQL treats NULL != value as
+        # unknown and drops the row, so a null column must be included.
+        if self.right is None:
+            return left.is_not(None)
+        if isinstance(self.right, FieldExpression):
+            return left != self.get_right(context)
+        return (left != self.get_right(context)) | left.is_(None)
 
 
 class LessThan(Comparison):
-    symbol = "<"
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) < self.get_right(*args, **kwargs)
+    operator = Operator.LESS_THAN
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} < {self.get_right(*args, **kwargs)}"
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) < self.get_right(context, *args, **kwargs)
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): {"$lt": self.get_right(*args, **kwargs)}}
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"range": {self.get_left(*args, **kwargs): {"lt": self.get_right(*args, **kwargs)}}}
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) < self.get_right(context)
 
 
 class LessThanOrEquals(Comparison):
-    symbol = "<="
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) <= self.get_right(*args, **kwargs)
+    operator = Operator.LESS_THAN_OR_EQUALS
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} <= {self.get_right(*args, **kwargs)}"
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) <= self.get_right(context, *args, **kwargs)
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): {"$lte": self.get_right(*args, **kwargs)}}
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"range": {self.get_left(*args, **kwargs): {"lte": self.get_right(*args, **kwargs)}}}
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) <= self.get_right(context)
 
 
 class GreaterThan(Comparison):
-    symbol = ">"
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) > self.get_right(*args, **kwargs)
-
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} > {self.get_right(*args, **kwargs)}"
+    operator = Operator.GREATER_THAN
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): {"$gt": self.get_right(*args, **kwargs)}}
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) > self.get_right(context, *args, **kwargs)
 
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"range": {self.get_left(*args, **kwargs): {"gt": self.get_right(*args, **kwargs)}}}
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) > self.get_right(context)
 
 
 class GreaterThanOrEquals(Comparison):
-    symbol = ">="
+    operator = Operator.GREATER_THAN_OR_EQUALS
 
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) >= self.get_right(*args, **kwargs)
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) >= self.get_right(context, *args, **kwargs)
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} >= {self.get_right(*args, **kwargs)}"
-
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): {"$gte": self.get_right(*args, **kwargs)}}
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"range": {self.get_left(*args, **kwargs): {"gte": self.get_right(*args, **kwargs)}}}
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) >= self.get_right(context)
 
 
 class IsIn(Comparison):
-    symbol = "is in"
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) in self.get_right(*args, **kwargs)
+    operator = Operator.IS_IN
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        # TODO: this might not actually be valid SQL
-        return f"{self.get_left(*args, **kwargs)} IN {self.get_right(*args, **kwargs)}"
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) in self.get_right(context, *args, **kwargs)
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): {"$in": self.get_right(*args, **kwargs)}}
+    def to_sqlalchemy(self, context: Any) -> Any:
+        if self.compares_fields:
+            self._reject_sql("the right side is a field, and SQL IN needs a list of values")
+        return self.get_left(context).in_(self._values(context))
 
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"terms": {self.get_left(*args, **kwargs): self.get_right(*args, **kwargs)}}
+    def _values(self, context: Any = None) -> list[Any]:
+        """
+        The candidate values as a sorted list, so rendering is deterministic.
+        """
+        operand = self.get_right(context)
+        if isinstance(operand, (set, frozenset)):
+            return sorted(operand, key=repr)
+        return list(operand)
 
 
 class Contains(Comparison):
-    symbol = "contains"
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_right(*args, **kwargs) in self.get_left(*args, **kwargs)
+    """
+    Substring or membership: the left side contains the right.
+    """
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return ""
+    operator = Operator.CONTAINS
 
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_right(context, *args, **kwargs) in self.get_left(context, *args, **kwargs)
 
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return
+    def to_sqlalchemy(self, context: Any) -> Any:
+        # Python is case-sensitive `in`. SQL LIKE is case-insensitive for ASCII
+        # on SQLite, so compiling this would match a different set of rows.
+        self._reject_sql("substring match is case-sensitive in Python and LIKE is not")
 
 
 class ValueExpression(Expression):
@@ -180,8 +187,7 @@ class ValueExpression(Expression):
     Expression representing a single value to be compared.
 
     The resulting tree (Equals/And/Or/... nodes) is also an inspectable structure,
-    not just a callable. These could be used in the future to emit structured queries
-    (SQL, MongoDB, Elasticsearch, etc.)
+    not just a callable. SQL is emitted through ``to_sqlalchemy``.
     """
 
     def __init__(self, value: Any) -> None:
@@ -214,39 +220,52 @@ class ValueExpression(Expression):
     def contains(self, substring: Any) -> "Comparison":
         return Contains(self, substring)
 
-    def get(self, *args: Any, **kwargs: Any) -> Any:
-        return self.value
-
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return str(self.value)
-
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return self.value
+    def resolve(self, context: Any = None, target: Target = Target.VALUE, *args: Any, **kwargs: Any) -> Any:
+        """
+        Resolve this literal, which is its own value for every target.
 
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        The signature matches ``FieldExpression.resolve`` so a caller can resolve
+        either side of a comparison without knowing which it holds.
+        """
         return self.value
 
 
 class FieldExpression(ValueExpression):
     """
     A value expression representing a named field reference for building filter predicates.
-    FieldExpression instances will evaluate against anything that supports __getitem__ by field name.
+
+    FieldExpression resolves against anything that holds fields by name: a mapping,
+    a dataclass, a pydantic model, a plain object, or a SQLAlchemy model class.
     """
 
-    def __call__(self, record: Any, *args, **kwargs) -> bool:
-        return bool(record[self.value])
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return bool(self.resolve(context))
 
     def __repr__(self) -> str:
         return f"Field({self.value!r})"
 
-    def get(self, record: Any, *args: Any, **kwargs: Any) -> Any:
-        return record[self.value]
-
-    def to_sql(self, record: Any, *args: Any, **kwargs: Any) -> str:
-        return record[self.value]
+    def resolve(self, context: Any = None, target: Target = Target.VALUE, *args: Any, **kwargs: Any) -> Any:
+        """
+        Resolve this field against ``context``.
 
-    def to_mongo(self, record: Any, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return record[self.value]
+        Args:
+            context: Whatever holds the field -- a mapping, an object, or a model class.
+            target: ``NAME`` for the field's name, ``VALUE`` for what ``context`` holds for it.
 
-    def to_elasticsearch(self, record: Any, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return record[self.value]
+        Raises:
+            UnknownFieldError: If ``context`` has no such field.
+        """
+        if target is Target.NAME:
+            return self.value
+
+        getter = getattr(context, "__getitem__", None)
+        if getter is not None:
+            try:
+                return getter(self.value)
+            except (KeyError, IndexError, TypeError):
+                pass
+
+        value = getattr(context, self.value, UNSET)
+        if value is UNSET:
+            raise UnknownFieldError(f"{context!r} has no field {self.value!r}")
+        return value

corekit/data/expressions/expression.py

@@ -1,98 +1,71 @@
-from typing import Any
-
-
-class Expression:
-    """
-    Base class for composable predicates. Subclasses implement __call__
-    """
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        raise NotImplementedError
-
-    def __and__(self, other: "Expression") -> "Expression":
-        return And(self, other)
-
-    def __or__(self, other: "Expression") -> "Expression":
-        return Or(self, other)
-
-    def __invert__(self) -> "Expression":
-        return Not(self)
-
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        raise NotImplementedError
-
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        raise NotImplementedError
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        raise NotImplementedError
-
-
-class And(Expression):
-    def __init__(self, left: Expression, right: Expression) -> None:
-        self.left = left
-        self.right = right
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return bool(self.left(*args, **kwargs)) and bool(self.right(*args, **kwargs))
-
-    def __repr__(self) -> str:
-        return f"({self.left!r} & {self.right!r})"
-
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"({self.left.to_sql(*args, **kwargs)} AND {self.right.to_sql(*args, **kwargs)})"
-
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"$and": [self.left.to_mongo(), self.right.to_mongo()]}
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {
-            "bool": {
-                "must": [self.left.to_elasticsearch(*args, **kwargs), self.right.to_elasticsearch(*args, **kwargs)]
-            }
-        }
-
-
-class Or(Expression):
-    def __init__(self, left: Expression, right: Expression) -> None:
-        self.left = left
-        self.right = right
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return bool(self.left(*args, **kwargs)) or bool(self.right(*args, **kwargs))
-
-    def __repr__(self) -> str:
-        return f"({self.left!r} | {self.right!r})"
-
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"({self.left.to_sql(*args, **kwargs)} OR {self.right.to_sql(*args, **kwargs)})"
-
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"$or": [self.left.to_mongo(*args, **kwargs), self.right.to_mongo(*args, **kwargs)]}
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {
-            "bool": {
-                "should": [self.left.to_elasticsearch(*args, **kwargs), self.right.to_elasticsearch(*args, **kwargs)]
-            }
-        }
-
-
-class Not(Expression):
-    def __init__(self, expr: Expression) -> None:
-        self.expr = expr
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return not self.expr(*args, **kwargs)
-
-    def __repr__(self) -> str:
-        return f"~{self.expr!r}"
-
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"NOT ({self.expr.to_sql(*args, **kwargs)})"
-
-    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"$not": self.expr.to_mongo(*args, **kwargs)}
-
-    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"bool": {"must_not": self.expr.to_elasticsearch(*args, **kwargs)}}
+from typing import Any
+
+
+class Expression:
+    """
+    Base class for composable predicates. Subclasses implement __call__
+    """
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        raise NotImplementedError
+
+    def __and__(self, other: "Expression") -> "Expression":
+        return And(self, other)
+
+    def __or__(self, other: "Expression") -> "Expression":
+        return Or(self, other)
+
+    def __invert__(self) -> "Expression":
+        return Not(self)
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        """
+        Compile to a SQLAlchemy clause against ``context``, a model class.
+
+        Values are bound as parameters rather than rendered into SQL text.
+        """
+        raise NotImplementedError
+
+
+class And(Expression):
+    def __init__(self, left: Expression, right: Expression) -> None:
+        self.left = left
+        self.right = right
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return bool(self.left(*args, **kwargs)) and bool(self.right(*args, **kwargs))
+
+    def __repr__(self) -> str:
+        return f"({self.left!r} & {self.right!r})"
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.left.to_sqlalchemy(context) & self.right.to_sqlalchemy(context)
+
+
+class Or(Expression):
+    def __init__(self, left: Expression, right: Expression) -> None:
+        self.left = left
+        self.right = right
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return bool(self.left(*args, **kwargs)) or bool(self.right(*args, **kwargs))
+
+    def __repr__(self) -> str:
+        return f"({self.left!r} | {self.right!r})"
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.left.to_sqlalchemy(context) | self.right.to_sqlalchemy(context)
+
+
+class Not(Expression):
+    def __init__(self, expr: Expression) -> None:
+        self.expr = expr
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return not self.expr(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"~{self.expr!r}"
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return ~self.expr.to_sqlalchemy(context)

corekit/data/expressions/operator.py

@@ -0,0 +1,39 @@
+"""
+The operators a comparison can express.
+"""
+
+from typing import NamedTuple
+
+from corekit.schemas.enum import ValidatingEnum
+
+__all__ = ["Dialect", "Operator"]
+
+
+class Dialect(NamedTuple):
+    """
+    How one operator is spelled for humans.
+
+    SQL is compiled through SQLAlchemy, not spelled here. A backend that does
+    not exist yet should not get a dialect string until it has a renderer.
+    """
+
+    symbol: str
+
+
+class Operator(ValidatingEnum):
+    """
+    A comparison operator, identified by the comparison class that uses it.
+    """
+
+    EQUALS = Dialect("==")
+    NOT_EQUALS = Dialect("!=")
+    LESS_THAN = Dialect("<")
+    LESS_THAN_OR_EQUALS = Dialect("<=")
+    GREATER_THAN = Dialect(">")
+    GREATER_THAN_OR_EQUALS = Dialect(">=")
+    IS_IN = Dialect("is in")
+    CONTAINS = Dialect("contains")
+
+    @property
+    def symbol(self) -> str:
+        return self.value.symbol

corekit/data/expressions/target.py

@@ -0,0 +1,21 @@
+"""
+How an operand should be resolved.
+"""
+
+from corekit.schemas.enum import StringEnum
+
+__all__ = ["Target"]
+
+
+class Target(StringEnum):
+    """
+    What a translator needs an operand resolved into.
+
+    Only ``FieldExpression`` reads this: a literal is its own value everywhere.
+    """
+
+    #: The field's value, read out of the context being resolved against.
+    VALUE = "value"
+
+    #: The field's name, for a query that names fields as strings.
+    NAME = "name"