pyrsql 0.0.1__py3-none-any.whl

pyrsql/orms/sqlalchemy/json_path.py

@@ -0,0 +1,351 @@
+"""JSON path expression building for the SQLAlchemy orm."""
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any, cast
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from sqlalchemy.sql.elements import ColumnElement
+
+from pyrsql.core.json.options import JSONOptions
+from pyrsql.core.json.path import JSONPath
+from pyrsql.core.json.query import JSONPathComparison
+from pyrsql.core.json.values import JSONScalarValue
+from pyrsql.orms.sqlalchemy.errors import SQLAlchemyORMError
+from pyrsql.parsing.operators import (
+    BETWEEN,
+    EQUAL,
+    GREATER_THAN,
+    GREATER_THAN_OR_EQUAL,
+    IGNORE_CASE,
+    IGNORE_CASE_LIKE,
+    IGNORE_CASE_NOT_LIKE,
+    IN,
+    IS_NULL,
+    LESS_THAN,
+    LESS_THAN_OR_EQUAL,
+    LIKE,
+    NOT_BETWEEN,
+    NOT_EQUAL,
+    NOT_IN,
+    NOT_LIKE,
+    NOT_NULL,
+)
+
+_ISO_DATE_TIME_PATTERN_TZ = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$"
+)
+_ISO_TIME_PATTERN_TZ = re.compile(
+    r"^\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$"
+)
+_ISO_DATE_TIME_PATTERN = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?$"
+)
+_ISO_DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+_ISO_TIME_PATTERN = re.compile(r"^\d{2}:\d{2}:\d{2}(\.\d+)?$")
+_DEFAULT_JSON_OPTIONS = JSONOptions()
+
+
+class SQLAlchemyJSONPathExpressionBuilder:
+    """Builds PostgreSQL JSON path expressions for SQLAlchemy."""
+
+    def build_filter_expression(
+        self,
+        column: ColumnElement[Any],
+        comparison: JSONPathComparison,
+        *,
+        options: JSONOptions | None = None,
+    ) -> ColumnElement[bool]:
+        """Builds a PostgreSQL JSONB path-exists predicate."""
+        function_call = self._build_filter_call(
+            comparison,
+            options=options or _DEFAULT_JSON_OPTIONS,
+        )
+        jsonb_column = cast(
+            ColumnElement[Any],
+            sa.cast(column, postgresql.JSONB),
+        )
+        if function_call.use_timezone_function:
+            function_expression = getattr(
+                sa.func,
+                function_call.path_exists_tz_function,
+            )(
+                jsonb_column,
+                sa.literal(function_call.json_path_expression),
+            )
+            return cast(ColumnElement[bool], function_expression)
+        if options and options.path_exists_function != "jsonb_path_exists":
+            function_expression = getattr(
+                sa.func,
+                options.path_exists_function,
+            )(
+                jsonb_column,
+                sa.literal(function_call.json_path_expression),
+            )
+            return cast(ColumnElement[bool], function_expression)
+        return cast(
+            ColumnElement[bool],
+            jsonb_column.path_exists(
+                sa.literal(function_call.json_path_expression)
+            ),
+        )
+
+    def build_sort_expression(
+        self,
+        column: ColumnElement[Any],
+        json_path: JSONPath,
+    ) -> ColumnElement[Any]:
+        """Builds a PostgreSQL JSON path extraction expression for sort."""
+        jsonb_column = cast(
+            ColumnElement[Any],
+            sa.cast(column, postgresql.JSONB),
+        )
+        if json_path.is_root:
+            return jsonb_column
+        return cast(
+            ColumnElement[Any],
+            jsonb_column[json_path.segments].as_string(),
+        )
+
+    def _build_filter_call(
+        self,
+        comparison: JSONPathComparison,
+        *,
+        options: JSONOptions,
+    ) -> "_JSONPathFilterCall":
+        """Builds the function call payload for one jsonpath predicate."""
+        target_path = (
+            "$"
+            if comparison.path.is_root
+            else "$." + comparison.path.to_dot_path()
+        )
+        use_datetime = options.use_datetime
+        use_timezone_function = use_datetime and any(
+            self._is_timezone_datetime_value(value)
+            for value in comparison.values
+        )
+        value_reference = "@"
+        if use_datetime and any(
+            self._is_datetime_value(value) for value in comparison.values
+        ):
+            value_reference = "@.datetime()"
+        if comparison.operator_name == NOT_NULL.name:
+            comparison_clause = "(@ != null)"
+        elif comparison.operator_name == EQUAL.name:
+            comparison_clause = self._equality_comparison(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+        elif comparison.operator_name == NOT_EQUAL.name:
+            equality_clause = self._equality_comparison(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = f"!{equality_clause}"
+        elif comparison.operator_name == GREATER_THAN.name:
+            value_literal = self._print_value(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = f"({value_reference} > {value_literal})"
+        elif comparison.operator_name == GREATER_THAN_OR_EQUAL.name:
+            value_literal = self._print_value(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = f"({value_reference} >= {value_literal})"
+        elif comparison.operator_name == LESS_THAN.name:
+            value_literal = self._print_value(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = f"({value_reference} < {value_literal})"
+        elif comparison.operator_name == LESS_THAN_OR_EQUAL.name:
+            value_literal = self._print_value(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = f"({value_reference} <= {value_literal})"
+        elif comparison.operator_name == IN.name:
+            comparison_clause = self._membership_comparison(
+                value_reference,
+                comparison.values,
+                operator="==",
+                join_operator="||",
+                use_datetime=use_datetime,
+            )
+        elif comparison.operator_name == NOT_IN.name:
+            comparison_clause = self._membership_comparison(
+                value_reference,
+                comparison.values,
+                operator="!=",
+                join_operator="&&",
+                use_datetime=use_datetime,
+            )
+        elif comparison.operator_name == IS_NULL.name:
+            comparison_clause = "(@ == null)"
+        elif comparison.operator_name == LIKE.name:
+            comparison_clause = self._regex_comparison(
+                comparison.values[0],
+                ignore_case=False,
+            )
+        elif comparison.operator_name == NOT_LIKE.name:
+            comparison_clause = "!" + self._regex_comparison(
+                comparison.values[0],
+                ignore_case=False,
+            )
+        elif comparison.operator_name == IGNORE_CASE.name:
+            comparison_clause = self._regex_comparison(
+                comparison.values[0],
+                ignore_case=True,
+            )
+        elif comparison.operator_name == IGNORE_CASE_LIKE.name:
+            comparison_clause = self._regex_comparison(
+                comparison.values[0],
+                ignore_case=True,
+            )
+        elif comparison.operator_name == IGNORE_CASE_NOT_LIKE.name:
+            comparison_clause = "!" + self._regex_comparison(
+                comparison.values[0],
+                ignore_case=True,
+            )
+        elif comparison.operator_name == BETWEEN.name:
+            lower_literal = self._print_value(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            upper_literal = self._print_value(
+                comparison.values[1],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = (
+                f"({value_reference} >= {lower_literal}"
+                f" && {value_reference} <= {upper_literal})"
+            )
+        elif comparison.operator_name == NOT_BETWEEN.name:
+            lower_literal = self._print_value(
+                comparison.values[0],
+                use_datetime=use_datetime,
+            )
+            upper_literal = self._print_value(
+                comparison.values[1],
+                use_datetime=use_datetime,
+            )
+            comparison_clause = (
+                f"({value_reference} < {lower_literal}"
+                f" || {value_reference} > {upper_literal})"
+            )
+        else:
+            raise SQLAlchemyORMError(
+                f"Unsupported JSON operator {comparison.operator_name!r}."
+            )
+        return _JSONPathFilterCall(
+            json_path_expression=f"{target_path} ? {comparison_clause}",
+            use_timezone_function=use_timezone_function,
+            path_exists_tz_function=options.path_exists_tz_function,
+        )
+
+    def _equality_comparison(
+        self,
+        value: JSONScalarValue,
+        *,
+        use_datetime: bool,
+    ) -> str:
+        """Builds equality or wildcard comparison for JSON values."""
+        if value.python_type is str and "*" in str(value.value):
+            return self._regex_comparison(
+                value,
+                ignore_case=False,
+            )
+        value_reference = (
+            "@.datetime()"
+            if use_datetime and self._is_datetime_value(value)
+            else "@"
+        )
+        return (
+            f"({value_reference} == "
+            f"{self._print_value(value, use_datetime=use_datetime)})"
+        )
+
+    def _regex_comparison(
+        self,
+        value: JSONScalarValue,
+        *,
+        ignore_case: bool,
+    ) -> str:
+        """Builds a jsonpath like_regex comparison."""
+        if value.python_type is not str:
+            raise SQLAlchemyORMError(
+                "LIKE-style JSON operators require string values."
+            )
+        normalized = str(value.value)
+        if "*" not in normalized:
+            normalized = f"*{normalized}*"
+        pattern = re.escape(normalized).replace(r"\*", ".*")
+        literal = json.dumps(pattern)
+        if ignore_case:
+            return f'(@ like_regex {literal} flag "i")'
+        return f"(@ like_regex {literal})"
+
+    def _membership_comparison(
+        self,
+        value_reference: str,
+        values: tuple[JSONScalarValue, ...],
+        *,
+        operator: str,
+        join_operator: str,
+        use_datetime: bool,
+    ) -> str:
+        """Builds one JSON membership comparison clause."""
+        comparisons = (
+            (
+                f"({value_reference} {operator} "
+                f"{self._print_value(value, use_datetime=use_datetime)})"
+            )
+            for value in values
+        )
+        return "(" + f" {join_operator} ".join(comparisons) + ")"
+
+    def _print_value(
+        self,
+        value: JSONScalarValue,
+        *,
+        use_datetime: bool,
+    ) -> str:
+        """Prints one JSON value for PostgreSQL jsonpath expressions."""
+        if use_datetime and self._is_datetime_value(value):
+            return f'"{value.value}".datetime()'
+        return value.json_literal
+
+    def _is_datetime_value(self, value: JSONScalarValue) -> bool:
+        """Returns whether a value is a supported ISO temporal string."""
+        if value.python_type is not str:
+            return False
+        normalized = str(value.value)
+        return (
+            _ISO_DATE_TIME_PATTERN.fullmatch(normalized) is not None
+            or _ISO_DATE_PATTERN.fullmatch(normalized) is not None
+            or _ISO_TIME_PATTERN.fullmatch(normalized) is not None
+            or self._is_timezone_datetime_value(value)
+        )
+
+    def _is_timezone_datetime_value(self, value: JSONScalarValue) -> bool:
+        """Returns whether a value is a timezone-aware ISO temporal string."""
+        if value.python_type is not str:
+            return False
+        normalized = str(value.value)
+        return (
+            _ISO_DATE_TIME_PATTERN_TZ.fullmatch(normalized) is not None
+            or _ISO_TIME_PATTERN_TZ.fullmatch(normalized) is not None
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _JSONPathFilterCall:
+    """Represents one PostgreSQL JSON path filter call."""
+
+    json_path_expression: str
+    use_timezone_function: bool
+    path_exists_tz_function: str

pyrsql/orms/sqlalchemy/orm.py

@@ -0,0 +1,65 @@
+"""SQLAlchemy ORM entry point."""
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+from pyrsql.orms import base
+from pyrsql.orms.sqlalchemy.compiled import SQLAlchemyCompiledQuery
+from pyrsql.orms.sqlalchemy.compiled_page import SQLAlchemyCompiledPageRequest
+from pyrsql.orms.sqlalchemy.compiled_sort import SQLAlchemyCompiledSort
+from pyrsql.orms.sqlalchemy.custom import SQLAlchemyCustomPredicate
+from pyrsql.orms.sqlalchemy.sorter import SQLAlchemySortTranslator
+from pyrsql.orms.sqlalchemy.translator import SQLAlchemyExpressionTranslator
+
+if TYPE_CHECKING:
+    from pyrsql.core.page import PageRequest
+    from pyrsql.core.query import Query
+    from pyrsql.core.sort import Sort
+
+
+class SQLAlchemyORM(base.ORM):
+    """ORM adapter for SQLAlchemy 2.0 integration."""
+
+    def __init__(
+        self,
+        *,
+        translator: SQLAlchemyExpressionTranslator | None = None,
+        sort_translator: SQLAlchemySortTranslator | None = None,
+        custom_predicates: (
+            Mapping[str, SQLAlchemyCustomPredicate] | None
+        ) = None,
+    ) -> None:
+        self._translator = translator or SQLAlchemyExpressionTranslator(
+            custom_predicates=custom_predicates,
+        )
+        self._sort_translator = sort_translator or SQLAlchemySortTranslator()
+
+    @property
+    def name(self) -> str:
+        """Returns the ORM name."""
+        return "sqlalchemy"
+
+    def compile_query(self, query: "Query") -> SQLAlchemyCompiledQuery:
+        """Compiles a pyrsql query for SQLAlchemy."""
+        if query.semantic_expression is None:
+            raise ValueError("Query must carry a semantic expression.")
+        return SQLAlchemyCompiledQuery(
+            expression=query.semantic_expression,
+            options=query.options,
+            translator=self._translator,
+        )
+
+    def compile_sort(self, sort: "Sort") -> SQLAlchemyCompiledSort:
+        """Compiles a pyrsql sort for SQLAlchemy."""
+        return SQLAlchemyCompiledSort(
+            fields=sort.semantic_fields,
+            options=sort.options,
+            translator=self._sort_translator,
+        )
+
+    def compile_page_request(
+        self,
+        page_request: "PageRequest",
+    ) -> SQLAlchemyCompiledPageRequest:
+        """Compiles a pyrsql page request for SQLAlchemy."""
+        return SQLAlchemyCompiledPageRequest(page_request=page_request)

pyrsql/orms/sqlalchemy/resolver.py

@@ -0,0 +1,202 @@
+"""Path resolution for SQLAlchemy ORM models."""
+
+from typing import Any, cast
+
+from sqlalchemy.sql.elements import ColumnElement
+
+from pyrsql.core.field_policy import FieldPolicySet
+from pyrsql.core.joins import JoinHint
+from pyrsql.core.json.path import JSONPath
+from pyrsql.orms.sqlalchemy.errors import SQLAlchemyPathResolutionError
+from pyrsql.orms.sqlalchemy.introspection import SQLAlchemyModelInspector
+from pyrsql.orms.sqlalchemy.types import (
+    SQLAlchemyAttributeKind,
+    SQLAlchemyJoinPlan,
+    SQLAlchemyMappedAttribute,
+    SQLAlchemyResolvedPath,
+)
+
+
+class SQLAlchemyPathResolver:
+    """Resolves semantic field paths into ORM joins and leaf attributes."""
+
+    def __init__(
+        self,
+        *,
+        inspector: SQLAlchemyModelInspector | None = None,
+    ) -> None:
+        self._inspector = inspector or SQLAlchemyModelInspector()
+        self._default_resolution_cache: dict[
+            tuple[type[Any], str], SQLAlchemyResolvedPath
+        ] = {}
+
+    def resolve(
+        self,
+        model: type[Any],
+        field_path: str,
+        *,
+        field_policy: FieldPolicySet | None = None,
+    ) -> SQLAlchemyResolvedPath:
+        """Resolves a dotted field path against a mapped SQLAlchemy model."""
+        if field_policy is None or field_policy.is_empty:
+            cache_key = (model, field_path)
+            cached_path = self._default_resolution_cache.get(cache_key)
+            if cached_path is not None:
+                return cached_path
+            resolved_path = self._resolve_with_field_policy(
+                model,
+                field_path,
+                field_policy=None,
+            )
+            self._default_resolution_cache[cache_key] = resolved_path
+            return resolved_path
+        return self._resolve_with_field_policy(
+            model,
+            field_path,
+            field_policy=field_policy,
+        )
+
+    def _resolve_with_field_policy(
+        self,
+        model: type[Any],
+        field_path: str,
+        *,
+        field_policy: FieldPolicySet | None,
+    ) -> SQLAlchemyResolvedPath:
+        """Resolves a dotted field path with the provided field policy."""
+        if not field_path:
+            raise SQLAlchemyPathResolutionError("Field path cannot be empty.")
+
+        segments = tuple(
+            segment for segment in field_path.split(".") if segment
+        )
+        if not segments:
+            raise SQLAlchemyPathResolutionError(
+                f"Field path {field_path!r} is invalid."
+            )
+
+        current_model = model
+        joins: list[SQLAlchemyJoinPlan] = []
+        leaf_attribute: SQLAlchemyMappedAttribute | None = None
+        segments_to_resolve = list(segments)
+        segment_index = 0
+        expansion_count = 0
+
+        while segment_index < len(segments_to_resolve):
+            segment = segments_to_resolve[segment_index]
+            if field_policy is not None:
+                mapped_segment = field_policy.map_model_field(
+                    current_model,
+                    segment,
+                )
+                if mapped_segment != segment:
+                    mapped_segments = tuple(
+                        part for part in mapped_segment.split(".") if part
+                    )
+                    if not mapped_segments:
+                        raise SQLAlchemyPathResolutionError(
+                            f"Mapped field {segment!r} on "
+                            f"{current_model.__name__!r} is invalid."
+                        )
+                    segments_to_resolve[segment_index : segment_index + 1] = (
+                        mapped_segments
+                    )
+                    expansion_count += 1
+                    if expansion_count > 32:
+                        raise SQLAlchemyPathResolutionError(
+                            "Field mapping expansion exceeded the supported "
+                            "limit."
+                        )
+                    continue
+            mapped_attribute = self._inspector.get_mapped_attribute(
+                current_model,
+                segment,
+            )
+            is_last_segment = segment_index == len(segments_to_resolve) - 1
+
+            if mapped_attribute.kind is SQLAlchemyAttributeKind.RELATIONSHIP:
+                if is_last_segment:
+                    raise SQLAlchemyPathResolutionError(
+                        f"Field path {field_path!r} ends on relationship "
+                        f"{segment!r}; a column-like attribute is required."
+                    )
+                joins.append(
+                    SQLAlchemyJoinPlan(
+                        key=self._make_join_key(current_model, segment),
+                        attribute=mapped_attribute.attribute,
+                        default_hint=JoinHint.INNER,
+                        is_collection=mapped_attribute.is_collection,
+                    )
+                )
+                if mapped_attribute.mapper is None:
+                    raise RuntimeError("mapper cannot be None")
+                current_model = mapped_attribute.mapper.class_
+                segment_index += 1
+                continue
+
+            if not is_last_segment:
+                if mapped_attribute.is_json:
+                    return SQLAlchemyResolvedPath(
+                        root_model=model,
+                        leaf_model=current_model,
+                        field_path=".".join(segments_to_resolve),
+                        joins=tuple(joins),
+                        leaf_attribute=cast(
+                            ColumnElement[Any],
+                            mapped_attribute.attribute,
+                        ),
+                        python_type=None,
+                        json_path=JSONPath(
+                            tuple(segments_to_resolve[segment_index + 1 :])
+                        ),
+                        is_json=True,
+                    )
+                raise SQLAlchemyPathResolutionError(
+                    f"Field path {field_path!r} traverses through "
+                    f"non-relationship segment {segment!r}."
+                )
+            leaf_attribute = mapped_attribute
+            if field_policy is not None:
+                self._validate_field_policy(
+                    field_policy,
+                    current_model,
+                    leaf_attribute.name,
+                    ".".join(segments_to_resolve),
+                )
+            segment_index += 1
+
+        if leaf_attribute is None:
+            raise RuntimeError("leaf_attribute cannot be None")
+        return SQLAlchemyResolvedPath(
+            root_model=model,
+            leaf_model=current_model,
+            field_path=field_path,
+            joins=tuple(joins),
+            leaf_attribute=cast(
+                ColumnElement[Any],
+                leaf_attribute.attribute,
+            ),
+            python_type=leaf_attribute.python_type,
+        )
+
+    @staticmethod
+    def _make_join_key(
+        model: type[Any],
+        segment: str,
+    ) -> str:
+        """Builds the stable join-hint lookup key for one relationship step."""
+        return f"{model.__name__}.{segment}"
+
+    @staticmethod
+    def _validate_field_policy(
+        field_policy: FieldPolicySet,
+        model: type[Any],
+        field_name: str,
+        field_path: str,
+    ) -> None:
+        """Validates field access using global and model-specific rules."""
+        try:
+            field_policy.validate_global_field_access(field_path)
+            field_policy.validate_model_field_access(model, field_name)
+        except ValueError as error:
+            raise SQLAlchemyPathResolutionError(str(error)) from error