python-corekit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

corekit/connections/sql/table.py

@@ -4,13 +4,24 @@ Base table type.
 
 import json
 import logging
-from typing import Any
+from typing import Any, ClassVar
 
+from pydantic import BaseModel
 from sqlmodel import SQLModel
 
 from corekit.registry import SmartRegistry
 
-__all__ = ["NamedTable"]
+__all__ = ["NamedTable", "TableExportItem"]
+
+
+class TableExportItem(BaseModel):
+    """
+    One exported row, tagged with the table it came from.
+    """
+
+    table_name: str
+    data: dict[str, Any]
+
 
 logger = logging.getLogger(__name__)
 
@@ -26,6 +37,10 @@ class NamedTable(SQLModel):
 
     __registry__: SmartRegistry = SmartRegistry()
 
+    #: A human-readable name for the table. Declared as a ClassVar so pydantic
+    #: leaves a subclass's value as a plain string rather than wrapping it.
+    _table_display_name: ClassVar[str | None] = None
+
     def __init_subclass__(cls, **kwargs: Any) -> None:
         """
         Register every subclass under its class name.
@@ -57,9 +72,14 @@ class NamedTable(SQLModel):
     @classmethod
     def get_display_name(cls) -> str:
         """
-        A human-readable name for the table.
+        A human-readable name for the table, falling back to the class name.
         """
-        return getattr(cls, "__display_name__", None) or cls.__name__
+        name = cls._table_display_name
+        if name is not None and not isinstance(name, str):
+            # A subclass declared outside this module's ClassVar annotation
+            # gets its value wrapped, and the wrapper's repr is not a label.
+            name = getattr(name, "default", None) or str(name)
+        return name or cls.__name__
 
     @classmethod
     def create_default(cls, identifier: str, **kwargs: Any) -> "NamedTable":
@@ -70,6 +90,12 @@ class NamedTable(SQLModel):
         logger.info(f"Creating default {cls.__name__} with id {kwargs['id']!r}")
         return cls(**kwargs)
 
+    def export(self) -> TableExportItem:
+        """
+        This row as a portable record, tagged with its table.
+        """
+        return TableExportItem(table_name=self.table_name, data=self.model_dump())
+
     @staticmethod
     def _serialize(value: Any) -> str:
         return json.dumps(value)

corekit/constants.py

@@ -1,45 +1,45 @@
-# Minutes
-ONE_MINUTE = 60
-TWO_MINUTES = ONE_MINUTE * 2
-THREE_MINUTES = ONE_MINUTE * 3
-FIVE_MINUTES = ONE_MINUTE * 5
-TEN_MINUTES = ONE_MINUTE * 10
-FIFTEEN_MINUTES = ONE_MINUTE * 15
-THIRTY_MINUTES = ONE_MINUTE * 30
-FORTY_FIVE_MINUTES = ONE_MINUTE * 45
-
-# Hours
-ONE_HOUR = ONE_MINUTE * 60
-TWO_HOURS = ONE_HOUR * 2
-THREE_HOURS = ONE_HOUR * 3
-FIVE_HOURS = ONE_HOUR * 5
-SIX_HOURS = ONE_HOUR * 6
-NINE_HOURS = ONE_HOUR * 9
-TWELVE_HOURS = ONE_HOUR * 12
-FIFTEEN_HOURS = ONE_HOUR * 15
-EIGHTEEN_HOURS = ONE_HOUR * 18
-
-# Days
-ONE_DAY = ONE_HOUR * 24
-TWO_DAYS = ONE_DAY * 2
-THREE_DAYS = ONE_DAY * 3
-FOUR_DAYS = ONE_DAY * 4
-FIVE_DAYS = ONE_DAY * 5
-SIX_DAYS = ONE_DAY * 6
-TEN_DAYS = ONE_DAY * 10
-FIFTEEN_DAYS = ONE_DAY * 15
-THIRTY_DAYS = ONE_DAY * 30
-FORTY_FIVE_DAYS = ONE_DAY * 45
-SIXTY_FIVE_DAYS = ONE_DAY * 60
-NINETY_FIVE_DAYS = ONE_DAY * 90
-ONE_HUNDRED_TWENTY_DAYS = ONE_DAY * 120
-ONE_HUNDRED_EIGHTY_DAYS = ONE_DAY * 180
-
-# Weeks
-ONE_WEEK = ONE_DAY * 7
-TWO_WEEKS = ONE_WEEK * 2
-THREE_WEEKS = ONE_WEEK * 3
-FOUR_WEEKS = ONE_WEEK * 4
-
-# Years
-ONE_YEAR = ONE_DAY * 365
+# Minutes
+ONE_MINUTE = 60
+TWO_MINUTES = ONE_MINUTE * 2
+THREE_MINUTES = ONE_MINUTE * 3
+FIVE_MINUTES = ONE_MINUTE * 5
+TEN_MINUTES = ONE_MINUTE * 10
+FIFTEEN_MINUTES = ONE_MINUTE * 15
+THIRTY_MINUTES = ONE_MINUTE * 30
+FORTY_FIVE_MINUTES = ONE_MINUTE * 45
+
+# Hours
+ONE_HOUR = ONE_MINUTE * 60
+TWO_HOURS = ONE_HOUR * 2
+THREE_HOURS = ONE_HOUR * 3
+FIVE_HOURS = ONE_HOUR * 5
+SIX_HOURS = ONE_HOUR * 6
+NINE_HOURS = ONE_HOUR * 9
+TWELVE_HOURS = ONE_HOUR * 12
+FIFTEEN_HOURS = ONE_HOUR * 15
+EIGHTEEN_HOURS = ONE_HOUR * 18
+
+# Days
+ONE_DAY = ONE_HOUR * 24
+TWO_DAYS = ONE_DAY * 2
+THREE_DAYS = ONE_DAY * 3
+FOUR_DAYS = ONE_DAY * 4
+FIVE_DAYS = ONE_DAY * 5
+SIX_DAYS = ONE_DAY * 6
+TEN_DAYS = ONE_DAY * 10
+FIFTEEN_DAYS = ONE_DAY * 15
+THIRTY_DAYS = ONE_DAY * 30
+FORTY_FIVE_DAYS = ONE_DAY * 45
+SIXTY_FIVE_DAYS = ONE_DAY * 60
+NINETY_FIVE_DAYS = ONE_DAY * 90
+ONE_HUNDRED_TWENTY_DAYS = ONE_DAY * 120
+ONE_HUNDRED_EIGHTY_DAYS = ONE_DAY * 180
+
+# Weeks
+ONE_WEEK = ONE_DAY * 7
+TWO_WEEKS = ONE_WEEK * 2
+THREE_WEEKS = ONE_WEEK * 3
+FOUR_WEEKS = ONE_WEEK * 4
+
+# Years
+ONE_YEAR = ONE_DAY * 365

corekit/crypto/constants.py

@@ -1,7 +1,7 @@
 HASH_JOINER = ":"
 EMPTY_HASH = ""
 
-# NOTE: a hardcoded CRYPTO_SALT previously lived here and is still present in this
-# repository's git history. It must be considered compromised and must never be
-# reintroduced. The salt is now supplied through configuration -- see
-# `corekit.config.CorekitSettings.crypto_salt` and `corekit.crypto.hasher.Hasher`.
+# There is deliberately no default salt. A salt shipped with a library is shared
+# by every install, which defeats the purpose of salting. Supply one through
+# configuration -- see `corekit.config.CorekitSettings.crypto_salt` and
+# `corekit.crypto.hasher.Hasher`.

corekit/data/__init__.py

@@ -24,6 +24,7 @@ from corekit.data.expressions import (
     And,
     Comparison,
     Contains,
+    Dialect,
     Equals,
     Expression,
     FieldExpression,
@@ -34,7 +35,10 @@ from corekit.data.expressions import (
     LessThanOrEquals,
     Not,
     NotEquals,
+    Operator,
     Or,
+    Target,
+    UnknownFieldError,
     ValueExpression,
 )
 from corekit.data.record import BaseRecord, is_valid_key, resolve_default
@@ -74,6 +78,10 @@ __all__ = [
     "NotEquals",
     "NumericFieldStats",
     "Or",
+    "Dialect",
+    "Operator",
+    "Target",
+    "UnknownFieldError",
     "ValueCounts",
     "ValueExpression",
     "is_valid_key",

corekit/data/expressions/__init__.py

@@ -8,8 +8,9 @@ values or against each other::
     Field("first_name") == Field("nickname")
     (Field("age") > 20) & ~Field("name").contains("test")
 
-Every node can also emit a backend query via ``to_sql``, ``to_mongo`` or
-``to_elasticsearch``.
+Every node can also emit a backend query: ``to_mongo``, ``to_elasticsearch`` or
+``to_sqlalchemy``. ``Target`` names the context an operand is resolved for, so a
+new backend needs one more translation method and no changes to the tree.
 """
 
 from corekit.data.expressions.comparison import (
@@ -23,9 +24,12 @@ from corekit.data.expressions.comparison import (
     LessThan,
     LessThanOrEquals,
     NotEquals,
+    UnknownFieldError,
     ValueExpression,
 )
 from corekit.data.expressions.expression import And, Expression, Not, Or
+from corekit.data.expressions.operator import Dialect, Operator
+from corekit.data.expressions.target import Target
 
 __all__ = [
     "And",
@@ -41,6 +45,10 @@ __all__ = [
     "LessThanOrEquals",
     "Not",
     "NotEquals",
+    "UnknownFieldError",
     "Or",
+    "Dialect",
+    "Operator",
+    "Target",
     "ValueExpression",
 ]

corekit/data/expressions/comparison.py

@@ -1,22 +1,32 @@
+import re
 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 external code -- e.g. a
+    translator to SQL/Mongo/Elasticsearch -- can walk the tree and read out
+    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 +35,205 @@ 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)
+        """
+        Whatever is on the left of this comparison, resolved.
+        """
+        return self.resolve(self.left, *args, **kwargs)
 
-    def get_right(self, *args, **kwargs) -> Any:
+    def get_right(self, *args: Any, **kwargs: Any) -> Any:
         """
-        Returns the right value of the comparison.
+        Whatever is on the right of this comparison, resolved.
         """
-        return self._resolve_value(self.right, *args, **kwargs)
+        return self.resolve(self.right, *args, **kwargs)
 
+    @property
+    def compares_fields(self) -> bool:
+        """
+        Whether the right side names a field rather than holding a value.
 
-class Equals(Comparison):
-    symbol = "=="
+        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 _reject_field_comparison(self) -> None:
+        """
+        Guard a dialect whose clauses only compare a field to a literal.
 
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) == self.get_right(*args, **kwargs)
+        Rendering the right side would emit a field's *name* where a value was
+        meant, which is a silently wrong query rather than a failed one.
+        """
+        if self.compares_fields:
+            raise NotImplementedError(f"Elasticsearch cannot express `{self.symbol}` between two fields")
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} = {self.get_right(*args, **kwargs)}"
+    def _reference(self, side: Any) -> str:
+        """
+        One side as a Mongo field reference, e.g. ``$age``.
+        """
+        return f"${self.resolve(side, target=Target.NAME)}"
 
     def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {self.get_left(*args, **kwargs): self.get_right(*args, **kwargs)}
+        if self.compares_fields:
+            return {"$expr": {self.operator.mongo: [self._reference(self.left), self._reference(self.right)]}}
+        return {self.get_left(target=Target.NAME): {self.operator.mongo: self.get_right()}}
 
     def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"term": {self.get_left(*args, **kwargs): self.get_right(*args, **kwargs)}}
+        self._reject_field_comparison()
+        # Elasticsearch range operators are the Mongo spelling without the `$`.
+        return {
+            self.operator.elasticsearch: {
+                self.get_left(target=Target.NAME): {self.operator.mongo.lstrip("$"): self.get_right()}
+            }
+        }
 
 
-class NotEquals(Comparison):
-    symbol = "!="
-
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) != self.get_right(*args, **kwargs)
+class Equals(Comparison):
+    operator = Operator.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): {"$ne": self.get_right(*args, **kwargs)}}
+        if self.compares_fields:
+            return super().to_mongo(*args, **kwargs)
+        # Equality is the one operator Mongo spells as a bare value.
+        return {self.get_left(target=Target.NAME): self.get_right()}
 
     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)}}}
+        self._reject_field_comparison()
+        return {self.operator.elasticsearch: {self.get_left(target=Target.NAME): self.get_right()}}
 
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) == self.get_right(context)
 
-class LessThan(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)}"
+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): {"$lt": 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): {"lt": self.get_right(*args, **kwargs)}}}
+        self._reject_field_comparison()
+        return {
+            self.operator.elasticsearch: {self.get_left(target=Target.NAME): {self.operator.mongo: self.get_right()}}
+        }
 
+    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)
 
-    def to_sql(self, *args: Any, **kwargs: Any) -> str:
-        return f"{self.get_left(*args, **kwargs)} <= {self.get_right(*args, **kwargs)}"
+class LessThan(Comparison):
+    operator = Operator.LESS_THAN
 
-    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 __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): {"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 = ">"
+class LessThanOrEquals(Comparison):
+    operator = Operator.LESS_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_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context) <= self.get_right(context)
 
-    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 to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"range": {self.get_left(*args, **kwargs): {"gt": self.get_right(*args, **kwargs)}}}
+class GreaterThan(Comparison):
+    operator = Operator.GREATER_THAN
 
+    def __call__(self, context: Any, *args: Any, **kwargs: Any) -> bool:
+        return self.get_left(context, *args, **kwargs) > self.get_right(context, *args, **kwargs)
 
-class GreaterThanOrEquals(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 GreaterThanOrEquals(Comparison):
+    operator = Operator.GREATER_THAN_OR_EQUALS
 
-    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 __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): {"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"
+    operator = Operator.IS_IN
 
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_left(*args, **kwargs) in self.get_right(*args, **kwargs)
-
-    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)}}
+        if self.compares_fields:
+            return {"$expr": {self.operator.mongo: [self._reference(self.left), self._reference(self.right)]}}
+        # A list, not the stored frozenset: no driver can serialize a set.
+        return {self.get_left(target=Target.NAME): {self.operator.mongo: self._values()}}
 
     def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return {"terms": {self.get_left(*args, **kwargs): self.get_right(*args, **kwargs)}}
+        self._reject_field_comparison()
+        return {self.operator.elasticsearch: {self.get_left(target=Target.NAME): self._values()}}
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context).in_(self._values(context))
+
+    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"
+    """
+    Substring or membership: the left side contains the right.
+    """
 
-    def __call__(self, *args: Any, **kwargs: Any) -> bool:
-        return self.get_right(*args, **kwargs) in self.get_left(*args, **kwargs)
+    operator = Operator.CONTAINS
 
-    def to_sql(self, *args: Any, **kwargs: 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_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return
+        if self.compares_fields:
+            # $regex is a query operator, not an aggregation one, so it cannot
+            # appear inside the $expr form that comparing two fields needs.
+            raise NotImplementedError("Mongo cannot express `contains` between two fields")
+        # $regex with the operand escaped, so a value containing regex
+        # metacharacters is matched literally rather than as a pattern.
+        return {self.get_left(target=Target.NAME): {self.operator.mongo: re.escape(str(self.get_right()))}}
 
     def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
-        return
+        self._reject_field_comparison()
+        return {self.operator.elasticsearch: {self.get_left(target=Target.NAME): f"*{self.get_right()}*"}}
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return self.get_left(context).contains(self.get_right(context))
 
 
 class ValueExpression(Expression):
@@ -214,11 +275,14 @@ 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 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_sql(self, *args: Any, **kwargs: Any) -> str:
-        return str(self.value)
+        The signature matches ``FieldExpression.resolve`` so a caller can resolve
+        either side of a comparison without knowing which it holds.
+        """
+        return self.value
 
     def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
         return self.value
@@ -230,23 +294,39 @@ class ValueExpression(Expression):
 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