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

corekit/data/expressions/expression.py

@@ -1,98 +1,103 @@
-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_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
+
+    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_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {"$and": [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": {
+                "must": [self.left.to_elasticsearch(*args, **kwargs), self.right.to_elasticsearch(*args, **kwargs)]
+            }
+        }
+
+    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_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)]
+            }
+        }
+
+    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_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)}}
+
+    def to_sqlalchemy(self, context: Any) -> Any:
+        return ~self.expr.to_sqlalchemy(context)

corekit/data/expressions/operator.py

@@ -0,0 +1,54 @@
+"""
+The operators a comparison can express, and how each dialect spells them.
+"""
+
+from typing import NamedTuple
+
+from corekit.schemas.enum import ValidatingEnum
+
+__all__ = ["Dialect", "Operator"]
+
+
+class Dialect(NamedTuple):
+    """
+    How one operator is spelled in each backend.
+
+    Args:
+        symbol: The human-readable operator, used in ``repr``.
+        mongo: The MongoDB query operator.
+        elasticsearch: The Elasticsearch clause the operator renders into.
+    """
+
+    symbol: str
+    mongo: str
+    elasticsearch: str
+
+
+class Operator(ValidatingEnum):
+    """
+    A comparison operator and its spelling in every dialect corekit renders to.
+
+    Adding a backend means adding a field to ``Dialect``, not a method to
+    every comparison class.
+    """
+
+    EQUALS = Dialect("==", "$eq", "term")
+    NOT_EQUALS = Dialect("!=", "$ne", "term")
+    LESS_THAN = Dialect("<", "$lt", "range")
+    LESS_THAN_OR_EQUALS = Dialect("<=", "$lte", "range")
+    GREATER_THAN = Dialect(">", "$gt", "range")
+    GREATER_THAN_OR_EQUALS = Dialect(">=", "$gte", "range")
+    IS_IN = Dialect("is in", "$in", "terms")
+    CONTAINS = Dialect("contains", "$regex", "wildcard")
+
+    @property
+    def symbol(self) -> str:
+        return self.value.symbol
+
+    @property
+    def mongo(self) -> str:
+        return self.value.mongo
+
+    @property
+    def elasticsearch(self) -> str:
+        return self.value.elasticsearch

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"

corekit/data/record.py

@@ -1,147 +1,147 @@
-import functools
-import keyword
-import logging
-from typing import Any, Callable, Iterator
-
-logger = logging.getLogger(__name__)
-
-
-def is_valid_key(key: Any) -> bool:
-    return isinstance(key, str) and key.isidentifier() and not keyword.iskeyword(key)
-
-
-def return_constant(value: Any) -> Any:
-    return value
-
-
-def resolve_default(default: Any, default_factory: Callable[[], Any] | None) -> Callable[[], Any]:
-    """
-    Normalize (default, default_factory) into a single zero-arg factory.
-
-    Raises on a raw mutable default (list/dict/set/bytearray), since that
-    object would otherwise be shared by reference across every record;
-    use default_factory instead. The non-factory path returns
-    functools.partial(_return_constant, default) rather than a lambda,
-    since a local lambda can't be pickled.
-    """
-    if default_factory is not None:
-        if default is not None:
-            logger.warning("Both default and default_factory were provided. Prioritizing default_factory.")
-        return default_factory
-
-    if isinstance(default, (list, dict, set, bytearray)):
-        raise TypeError(
-            f"mutable default {default!r} would be shared by reference across every "
-            f"record; use default_factory instead (e.g. default_factory=list)"
-        )
-    return functools.partial(return_constant, default)
-
-
-def reconstruct_record(fields: tuple, values: tuple) -> "BaseRecord":
-    """
-    Rebuild a record on unpickling. Module-level so pickle can reference
-    it by import path -- the record's actual class is generated
-    dynamically and has no module path of its own.
-    """
-    cls = BaseRecord.create_new(fields)
-    instance = cls()
-    for key, value in zip(fields, values):
-        instance[key] = value
-    return instance
-
-
-class BaseRecord:
-    """
-    Base class for dynamically generated, schema-specific record types.
-
-    Subclasses are built per-dataset by create_new() with __slots__ for
-    each field, so instances carry no per-record __dict__ overhead.
-    __slots__ = () here means this base itself adds nothing on top of
-    that.
-    """
-
-    __slots__ = ()
-    __fieldmap__ = {}
-
-    @staticmethod
-    def create_new(fields: tuple) -> type:
-        """
-        Build a record class for the given field names.
-
-        Fields that aren't valid Python identifiers get a synthetic slot
-        name (_slot_0, _slot_1, ...) instead, tracked via __fieldmap__
-        so dict-style access (record["weird field"]) still works.
-        Synthetic names are checked against real field names so a field
-        literally named "_slot_0" can't collide with one.
-        """
-        fieldmap: dict[Any, str] = {}
-        slot_names: list[str] = []
-        reserved = {key for key in fields if is_valid_key(key)}
-        used: set[str] = set()
-        counter = 0
-        for key in fields:
-            if is_valid_key(key):
-                slot = key
-            else:
-                candidate = f"_slot_{counter}"
-                counter += 1
-                while candidate in reserved or candidate in used:
-                    candidate = f"_slot_{counter}"
-                    counter += 1
-                slot = candidate
-            used.add(slot)
-            fieldmap[key] = slot
-            slot_names.append(slot)
-        return type("Record", (BaseRecord,), {"__slots__": tuple(slot_names), "__fieldmap__": fieldmap})
-
-    def __getitem__(self, key: Any) -> Any:
-        slot = self.__fieldmap__.get(key, key)
-        try:
-            return getattr(self, slot)
-        except AttributeError:
-            raise KeyError(key) from None
-
-    def __setitem__(self, key: Any, value: Any) -> Any:
-        slot = self.__fieldmap__.get(key)
-        if slot is None:
-            raise KeyError(f"{key!r} does not exist for record: {self}")
-        setattr(self, slot, value)
-
-    def __contains__(self, key: Any) -> bool:
-        return key in self.__fieldmap__
-
-    def __iter__(self) -> Iterator[Any]:
-        return iter(self.__fieldmap__)
-
-    def __len__(self) -> int:
-        return len(self.__fieldmap__)
-
-    def __eq__(self, other: Any) -> bool:
-        """
-        Value equality: same fields and values, not same object.
-
-        Records are mutable, so __hash__ is implicitly disabled once
-        __eq__ is defined (Python does this automatically) -- that's
-        intentional, not an oversight, since a hashable object whose
-        hash can change under mutation is unsafe to use as a dict/set key.
-        """
-        if isinstance(other, BaseRecord):
-            return self.to_dict() == other.to_dict()
-        if isinstance(other, dict):
-            return self.to_dict() == other
-        return NotImplemented
-
-    def __repr__(self) -> str:
-        fields = ", ".join(f"{key}={self[key]!r}" for key in self.__fieldmap__)
-        return f"{type(self).__name__}({fields})"
-
-    def __reduce__(self) -> tuple:
-        """
-        Pickle as (reconstruct_fn, (fields, values)); see _reconstruct_record
-        """
-        fields = tuple(self.__fieldmap__.keys())
-        values = tuple(self[k] for k in fields)
-        return reconstruct_record, (fields, values)
-
-    def to_dict(self) -> dict[Any, Any]:
-        return {k: self[k] for k in self.__fieldmap__}
+import functools
+import keyword
+import logging
+from typing import Any, Callable, Iterator
+
+logger = logging.getLogger(__name__)
+
+
+def is_valid_key(key: Any) -> bool:
+    return isinstance(key, str) and key.isidentifier() and not keyword.iskeyword(key)
+
+
+def return_constant(value: Any) -> Any:
+    return value
+
+
+def resolve_default(default: Any, default_factory: Callable[[], Any] | None) -> Callable[[], Any]:
+    """
+    Normalize (default, default_factory) into a single zero-arg factory.
+
+    Raises on a raw mutable default (list/dict/set/bytearray), since that
+    object would otherwise be shared by reference across every record;
+    use default_factory instead. The non-factory path returns
+    functools.partial(_return_constant, default) rather than a lambda,
+    since a local lambda can't be pickled.
+    """
+    if default_factory is not None:
+        if default is not None:
+            logger.warning("Both default and default_factory were provided. Prioritizing default_factory.")
+        return default_factory
+
+    if isinstance(default, (list, dict, set, bytearray)):
+        raise TypeError(
+            f"mutable default {default!r} would be shared by reference across every "
+            f"record; use default_factory instead (e.g. default_factory=list)"
+        )
+    return functools.partial(return_constant, default)
+
+
+def reconstruct_record(fields: tuple, values: tuple) -> "BaseRecord":
+    """
+    Rebuild a record on unpickling. Module-level so pickle can reference
+    it by import path -- the record's actual class is generated
+    dynamically and has no module path of its own.
+    """
+    cls = BaseRecord.create_new(fields)
+    instance = cls()
+    for key, value in zip(fields, values):
+        instance[key] = value
+    return instance
+
+
+class BaseRecord:
+    """
+    Base class for dynamically generated, schema-specific record types.
+
+    Subclasses are built per-dataset by create_new() with __slots__ for
+    each field, so instances carry no per-record __dict__ overhead.
+    __slots__ = () here means this base itself adds nothing on top of
+    that.
+    """
+
+    __slots__ = ()
+    __fieldmap__ = {}
+
+    @staticmethod
+    def create_new(fields: tuple) -> type:
+        """
+        Build a record class for the given field names.
+
+        Fields that aren't valid Python identifiers get a synthetic slot
+        name (_slot_0, _slot_1, ...) instead, tracked via __fieldmap__
+        so dict-style access (record["weird field"]) still works.
+        Synthetic names are checked against real field names so a field
+        literally named "_slot_0" can't collide with one.
+        """
+        fieldmap: dict[Any, str] = {}
+        slot_names: list[str] = []
+        reserved = {key for key in fields if is_valid_key(key)}
+        used: set[str] = set()
+        counter = 0
+        for key in fields:
+            if is_valid_key(key):
+                slot = key
+            else:
+                candidate = f"_slot_{counter}"
+                counter += 1
+                while candidate in reserved or candidate in used:
+                    candidate = f"_slot_{counter}"
+                    counter += 1
+                slot = candidate
+            used.add(slot)
+            fieldmap[key] = slot
+            slot_names.append(slot)
+        return type("Record", (BaseRecord,), {"__slots__": tuple(slot_names), "__fieldmap__": fieldmap})
+
+    def __getitem__(self, key: Any) -> Any:
+        slot = self.__fieldmap__.get(key, key)
+        try:
+            return getattr(self, slot)
+        except AttributeError:
+            raise KeyError(key) from None
+
+    def __setitem__(self, key: Any, value: Any) -> Any:
+        slot = self.__fieldmap__.get(key)
+        if slot is None:
+            raise KeyError(f"{key!r} does not exist for record: {self}")
+        setattr(self, slot, value)
+
+    def __contains__(self, key: Any) -> bool:
+        return key in self.__fieldmap__
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.__fieldmap__)
+
+    def __len__(self) -> int:
+        return len(self.__fieldmap__)
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Value equality: same fields and values, not same object.
+
+        Records are mutable, so __hash__ is implicitly disabled once
+        __eq__ is defined (Python does this automatically) -- that's
+        intentional, not an oversight, since a hashable object whose
+        hash can change under mutation is unsafe to use as a dict/set key.
+        """
+        if isinstance(other, BaseRecord):
+            return self.to_dict() == other.to_dict()
+        if isinstance(other, dict):
+            return self.to_dict() == other
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        fields = ", ".join(f"{key}={self[key]!r}" for key in self.__fieldmap__)
+        return f"{type(self).__name__}({fields})"
+
+    def __reduce__(self) -> tuple:
+        """
+        Pickle as (reconstruct_fn, (fields, values)); see _reconstruct_record
+        """
+        fields = tuple(self.__fieldmap__.keys())
+        values = tuple(self[k] for k in fields)
+        return reconstruct_record, (fields, values)
+
+    def to_dict(self) -> dict[Any, Any]:
+        return {k: self[k] for k in self.__fieldmap__}