pyrsql 0.0.1__py3-none-any.whl

pyrsql/orms/sqlalchemy/__init__.py

@@ -0,0 +1,39 @@
+"""SQLAlchemy ORM exports."""
+
+from pyrsql.orms.sqlalchemy.coercion import SQLAlchemyValueCoercer
+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.errors import (
+    SQLAlchemyJSONSupportError,
+    SQLAlchemyModelInspectionError,
+    SQLAlchemyORMError,
+    SQLAlchemyPathResolutionError,
+)
+from pyrsql.orms.sqlalchemy.introspection import SQLAlchemyModelInspector
+from pyrsql.orms.sqlalchemy.json_path import (
+    SQLAlchemyJSONPathExpressionBuilder,
+)
+from pyrsql.orms.sqlalchemy.orm import SQLAlchemyORM
+from pyrsql.orms.sqlalchemy.resolver import SQLAlchemyPathResolver
+from pyrsql.orms.sqlalchemy.sorter import SQLAlchemySortTranslator
+from pyrsql.orms.sqlalchemy.translator import SQLAlchemyExpressionTranslator
+
+__all__ = [
+    "SQLAlchemyORM",
+    "SQLAlchemyORMError",
+    "SQLAlchemyCompiledPageRequest",
+    "SQLAlchemyCompiledQuery",
+    "SQLAlchemyCompiledSort",
+    "SQLAlchemyJSONPathExpressionBuilder",
+    "SQLAlchemyJSONSupportError",
+    "SQLAlchemyModelInspector",
+    "SQLAlchemyModelInspectionError",
+    "SQLAlchemyPathResolutionError",
+    "SQLAlchemyPathResolver",
+    "SQLAlchemySortTranslator",
+    "SQLAlchemyExpressionTranslator",
+    "SQLAlchemyValueCoercer",
+]

pyrsql/orms/sqlalchemy/coercion.py

@@ -0,0 +1,57 @@
+"""SQLAlchemy ORM value coercion."""
+
+from typing import Any
+
+from pyrsql.core.conversion import (
+    FieldValueConverterSet,
+    ValueConversionError,
+    ValueConverterRegistry,
+)
+from pyrsql.orms.sqlalchemy.errors import SQLAlchemyORMError
+
+
+class SQLAlchemyValueCoercer:
+    """Coerces semantic argument values using resolved Python types."""
+
+    def __init__(
+        self,
+        *,
+        registry: ValueConverterRegistry | None = None,
+    ) -> None:
+        self._registry = registry
+
+    def coerce(
+        self,
+        raw_value: str,
+        python_type: type[Any] | None,
+        *,
+        field_converter_set: FieldValueConverterSet | None = None,
+        model: type[Any] | None = None,
+        field_name: str | None = None,
+        field_path: str | None = None,
+        registry: ValueConverterRegistry | None = None,
+    ) -> Any:
+        """Coerces a raw argument into a typed Python value."""
+        if field_converter_set is not None:
+            field_converter = field_converter_set.resolve(
+                model=model,
+                field_name=field_name,
+                field_path=field_path,
+            )
+            if field_converter is not None:
+                try:
+                    return field_converter(raw_value)
+                except Exception as error:
+                    raise SQLAlchemyORMError(
+                        f"Failed to convert {raw_value!r} for field "
+                        f"{field_path or field_name!r}."
+                    ) from error
+        active_registry = registry or self._registry
+        if active_registry is None:
+            raise SQLAlchemyORMError(
+                "SQLAlchemyValueCoercer requires a conversion registry."
+            )
+        try:
+            return active_registry.convert(raw_value, python_type)
+        except ValueConversionError as error:
+            raise SQLAlchemyORMError(str(error)) from error

pyrsql/orms/sqlalchemy/compiled.py

@@ -0,0 +1,56 @@
+"""Compiled query support for SQLAlchemy."""
+
+from dataclasses import dataclass
+
+from pyrsql.core.options import QueryOptions
+from pyrsql.orms.sqlalchemy.statement import (
+    apply_relationship_joins,
+    require_sqlalchemy_select,
+)
+from pyrsql.orms.sqlalchemy.translator import SQLAlchemyExpressionTranslator
+from pyrsql.orms.sqlalchemy.types import SQLAlchemyModel, SQLAlchemySelect
+from pyrsql.semantic.ast import SemanticExpression
+
+
+@dataclass(frozen=True, slots=True)
+class SQLAlchemyCompiledQuery:
+    """Compiled SQLAlchemy query plan.
+
+    Attributes:
+        expression: Semantic expression to translate into SQLAlchemy clauses.
+        options: Query configuration used during translation.
+        translator: Translator responsible for producing SQLAlchemy objects.
+    """
+
+    expression: SemanticExpression
+    options: QueryOptions
+    translator: SQLAlchemyExpressionTranslator
+
+    def apply(
+        self,
+        target: SQLAlchemySelect | object,
+        model: SQLAlchemyModel,
+    ) -> SQLAlchemySelect:
+        """Applies the compiled query to a SQLAlchemy Select.
+
+        Args:
+            target: SQLAlchemy select statement to mutate.
+            model: SQLAlchemy mapped class used to resolve fields.
+
+        Returns:
+            A SQLAlchemy select with filters and joins applied.
+        """
+        statement = require_sqlalchemy_select(target)
+        joins, predicate = self.translator.translate(
+            model,
+            self.expression,
+            options=self.options,
+        )
+        statement = apply_relationship_joins(
+            statement,
+            joins,
+            join_hints=self.options.join_hints,
+        )
+        if self.options.distinct:
+            statement = statement.distinct()
+        return statement.where(predicate)

pyrsql/orms/sqlalchemy/compiled_page.py

@@ -0,0 +1,40 @@
+"""Compiled pagination support for SQLAlchemy."""
+
+from dataclasses import dataclass
+
+from pyrsql.core.page import PageRequest
+from pyrsql.orms.sqlalchemy.statement import require_sqlalchemy_select
+from pyrsql.orms.sqlalchemy.types import SQLAlchemyModel, SQLAlchemySelect
+
+
+@dataclass(frozen=True, slots=True)
+class SQLAlchemyCompiledPageRequest:
+    """Compiled SQLAlchemy pagination plan.
+
+    Attributes:
+        page_request: Pagination request to apply to a select statement.
+    """
+
+    page_request: PageRequest
+
+    def apply(
+        self,
+        target: SQLAlchemySelect | object,
+        model: SQLAlchemyModel,
+    ) -> SQLAlchemySelect:
+        """Applies the compiled page request to a SQLAlchemy Select.
+
+        Args:
+            target: SQLAlchemy select statement to mutate.
+            model: SQLAlchemy mapped class. The page application does not use
+                it directly, but the signature matches the other compiled
+                plans.
+
+        Returns:
+            A SQLAlchemy select with limit and offset applied.
+        """
+        del model
+        statement = require_sqlalchemy_select(target)
+        return statement.limit(self.page_request.limit).offset(
+            self.page_request.offset
+        )

pyrsql/orms/sqlalchemy/compiled_sort.py

@@ -0,0 +1,56 @@
+"""Compiled sort support for SQLAlchemy."""
+
+from dataclasses import dataclass
+
+from pyrsql.core.options import SortOptions
+from pyrsql.orms.sqlalchemy.sorter import SQLAlchemySortTranslator
+from pyrsql.orms.sqlalchemy.statement import (
+    apply_relationship_joins,
+    require_sqlalchemy_select,
+)
+from pyrsql.orms.sqlalchemy.types import SQLAlchemyModel, SQLAlchemySelect
+from pyrsql.sorting.semantic import SemanticSortField
+
+
+@dataclass(frozen=True, slots=True)
+class SQLAlchemyCompiledSort:
+    """Compiled SQLAlchemy sort plan.
+
+    Attributes:
+        fields: Semantic sort fields to translate into order clauses.
+        options: Sort configuration used during translation.
+        translator: Translator responsible for producing SQLAlchemy objects.
+    """
+
+    fields: tuple[SemanticSortField, ...]
+    options: SortOptions
+    translator: SQLAlchemySortTranslator
+
+    def apply(
+        self,
+        target: SQLAlchemySelect | object,
+        model: SQLAlchemyModel,
+    ) -> SQLAlchemySelect:
+        """Applies the compiled sort to a SQLAlchemy Select.
+
+        Args:
+            target: SQLAlchemy select statement to mutate.
+            model: SQLAlchemy mapped class used to resolve fields.
+
+        Returns:
+            A SQLAlchemy select with joins and ordering applied.
+        """
+        statement = require_sqlalchemy_select(target)
+        joins, order_clauses = self.translator.translate(
+            model,
+            self.fields,
+            options=self.options,
+        )
+        statement = apply_relationship_joins(
+            statement,
+            joins,
+            join_hints=self.options.join_hints,
+        )
+        if not order_clauses:
+            return statement
+        return statement.order_by(*order_clauses)

pyrsql/orms/sqlalchemy/custom.py

@@ -0,0 +1,25 @@
+"""Custom predicate extension points for the SQLAlchemy orm."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy.sql.elements import ColumnElement
+
+from pyrsql.core.options import QueryOptions
+
+
+@dataclass(frozen=True, slots=True)
+class SQLAlchemyCustomPredicateInput:
+    """Structured input for ORM-specific custom predicate builders."""
+
+    expression: ColumnElement[Any]
+    python_type: type[Any] | None
+    values: tuple[Any, ...]
+    options: QueryOptions
+
+
+SQLAlchemyCustomPredicate = Callable[
+    [SQLAlchemyCustomPredicateInput],
+    ColumnElement[bool],
+]

pyrsql/orms/sqlalchemy/errors.py

@@ -0,0 +1,17 @@
+"""SQLAlchemy ORM-specific exceptions."""
+
+
+class SQLAlchemyORMError(ValueError):
+    """Base exception for SQLAlchemy ORM failures."""
+
+
+class SQLAlchemyModelInspectionError(SQLAlchemyORMError):
+    """Raised when a model cannot be inspected as a mapped class."""
+
+
+class SQLAlchemyPathResolutionError(SQLAlchemyORMError):
+    """Raised when a semantic field path cannot be resolved."""
+
+
+class SQLAlchemyJSONSupportError(SQLAlchemyORMError):
+    """Raised when JSON/JSONB translation cannot be completed."""

pyrsql/orms/sqlalchemy/introspection.py

@@ -0,0 +1,107 @@
+"""SQLAlchemy ORM inspection helpers."""
+
+from typing import Any
+
+from sqlalchemy import inspect
+from sqlalchemy.exc import NoInspectionAvailable
+from sqlalchemy.orm import Mapper
+from sqlalchemy.orm.properties import ColumnProperty
+from sqlalchemy.sql.sqltypes import JSON
+
+from pyrsql.orms.sqlalchemy.errors import SQLAlchemyModelInspectionError
+from pyrsql.orms.sqlalchemy.types import (
+    SQLAlchemyAttributeKind,
+    SQLAlchemyMappedAttribute,
+)
+
+
+class SQLAlchemyModelInspector:
+    """Provides stable access to public SQLAlchemy ORM inspection APIs."""
+
+    def __init__(self) -> None:
+        self._mapper_cache: dict[type[Any], Mapper[Any]] = {}
+        self._attribute_cache: dict[
+            tuple[type[Any], str], SQLAlchemyMappedAttribute
+        ] = {}
+
+    def inspect_model(self, model: type[Any]) -> Mapper[Any]:
+        """Returns the ORM mapper for a mapped class."""
+        cached_mapper = self._mapper_cache.get(model)
+        if cached_mapper is not None:
+            return cached_mapper
+        try:
+            mapper = inspect(model)
+        except NoInspectionAvailable as error:
+            raise SQLAlchemyModelInspectionError(
+                f"Type {model!r} is not a SQLAlchemy mapped class."
+            ) from error
+        if not isinstance(mapper, Mapper):
+            raise SQLAlchemyModelInspectionError(
+                f"Type {model!r} did not resolve to a SQLAlchemy ORM mapper."
+            )
+        self._mapper_cache[model] = mapper
+        return mapper
+
+    def get_mapped_attribute(
+        self,
+        model: type[Any],
+        attribute_name: str,
+    ) -> SQLAlchemyMappedAttribute:
+        """Returns metadata for a mapped attribute by name."""
+        cache_key = (model, attribute_name)
+        cached_attribute = self._attribute_cache.get(cache_key)
+        if cached_attribute is not None:
+            return cached_attribute
+
+        mapper = self.inspect_model(model)
+        if attribute_name in mapper.relationships:
+            relationship = mapper.relationships[attribute_name]
+            mapped_attribute = SQLAlchemyMappedAttribute(
+                name=attribute_name,
+                kind=SQLAlchemyAttributeKind.RELATIONSHIP,
+                owner_model=model,
+                attribute=getattr(model, attribute_name),
+                mapper=relationship.mapper,
+                python_type=relationship.mapper.class_,
+                is_collection=bool(relationship.uselist),
+            )
+            self._attribute_cache[cache_key] = mapped_attribute
+            return mapped_attribute
+        if attribute_name in mapper.column_attrs:
+            column_property = mapper.column_attrs[attribute_name]
+            mapped_attribute = SQLAlchemyMappedAttribute(
+                name=attribute_name,
+                kind=SQLAlchemyAttributeKind.COLUMN,
+                owner_model=model,
+                attribute=getattr(model, attribute_name),
+                mapper=None,
+                python_type=self._resolve_column_python_type(column_property),
+                is_json=self._is_json_column(column_property),
+            )
+            self._attribute_cache[cache_key] = mapped_attribute
+            return mapped_attribute
+        raise SQLAlchemyModelInspectionError(
+            f"Attribute {attribute_name!r} is not mapped on model "
+            f"{model.__name__!r}."
+        )
+
+    @staticmethod
+    def _resolve_column_python_type(
+        column_property: ColumnProperty[Any],
+    ) -> type[Any] | None:
+        """Returns the Python type for a column property when available."""
+        if not column_property.columns:
+            return None
+        try:
+            return column_property.columns[0].type.python_type
+        except (AttributeError, NotImplementedError):
+            return None
+
+    @staticmethod
+    def _is_json_column(
+        column_property: ColumnProperty[Any],
+    ) -> bool:
+        """Returns whether the column property stores JSON-like data."""
+        if not column_property.columns:
+            return False
+        return isinstance(column_property.columns[0].type, JSON)