pyrsql 0.0.1__py3-none-any.whl

pyrsql/core/query.py

@@ -0,0 +1,160 @@
+"""High-level query object."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyrsql.core.compiler import CompilationResult
+from pyrsql.core.options import QueryOptions
+from pyrsql.orms.base import ORM
+from pyrsql.parsing.ast import Expression
+from pyrsql.parsing.parser import Parser
+from pyrsql.semantic.analyzer import SemanticAnalyzer
+from pyrsql.semantic.ast import SemanticExpression
+
+_DEFAULT_QUERY_OPTIONS = QueryOptions()
+
+
+def _resolve_query_options(
+    options: QueryOptions | None,
+) -> QueryOptions:
+    """Returns the provided options or the shared immutable default."""
+    return options or _DEFAULT_QUERY_OPTIONS
+
+
+def _parse_query_expression(
+    query_text: str,
+    *,
+    options: QueryOptions,
+) -> Expression:
+    """Parses raw query text into a syntax tree."""
+    return Parser(
+        query_text,
+        limits=options.parse_limits,
+        operator_registry=options.operator_registry,
+    ).parse()
+
+
+def _analyze_query_expression(
+    expression: Expression,
+    *,
+    options: QueryOptions,
+) -> SemanticExpression:
+    """Analyzes a syntax tree into a semantic expression."""
+    return SemanticAnalyzer(options).analyze(expression)
+
+
+@dataclass(frozen=True, slots=True)
+class Query:
+    """Represents a parsed ORM-neutral query request.
+
+    The query preserves the raw text, the parsed expression tree, and the
+    semantic representation used by later compilation steps.
+
+    Attributes:
+        text: Raw RSQL text that produced the query.
+        options: Normalized query configuration used during parsing.
+        expression: Parsed syntax tree, if parsing succeeded.
+        semantic_expression: Semantic expression tree, if analysis succeeded.
+    """
+
+    text: str
+    options: QueryOptions
+    expression: Expression | None = None
+    semantic_expression: SemanticExpression | None = None
+
+    @classmethod
+    def parse(
+        cls,
+        query_text: str,
+        *,
+        options: QueryOptions | None = None,
+    ) -> "Query":
+        """Parses raw RSQL text into a query object.
+
+        Args:
+            query_text: Raw RSQL text to parse.
+            options: Optional query configuration.
+
+        Returns:
+            A parsed query object.
+        """
+        resolved_options = _resolve_query_options(options)
+        expression = cls.parse_expression(query_text, options=resolved_options)
+        semantic_expression = cls.analyze_expression(
+            expression,
+            options=resolved_options,
+        )
+        return cls(
+            text=query_text,
+            options=resolved_options,
+            expression=expression,
+            semantic_expression=semantic_expression,
+        )
+
+    @staticmethod
+    def parse_expression(
+        query_text: str,
+        *,
+        options: QueryOptions,
+    ) -> Expression:
+        """Parses raw RSQL text into a syntax tree.
+
+        Args:
+            query_text: Raw RSQL text to parse.
+            options: Query configuration used by the parser.
+
+        Returns:
+            The parsed syntax tree.
+        """
+        return _parse_query_expression(query_text, options=options)
+
+    @staticmethod
+    def analyze_expression(
+        expression: Expression,
+        *,
+        options: QueryOptions,
+    ) -> SemanticExpression:
+        """Analyzes a syntax tree into a semantic expression.
+
+        Args:
+            expression: Parsed syntax tree to analyze.
+            options: Query configuration used by semantic analysis.
+
+        Returns:
+            The semantic expression tree.
+        """
+        return _analyze_query_expression(expression, options=options)
+
+    def compile(self, *, orm: ORM) -> CompilationResult:
+        """Compiles the query using the provided ORM.
+
+        Args:
+            orm: ORM adapter used to compile the query.
+
+        Returns:
+            The ORM-specific compilation result.
+        """
+        compiled_query = orm.compile_query(self)
+        return CompilationResult(
+            orm_name=orm.name,
+            compiled_query=compiled_query,
+        )
+
+    def apply(
+        self,
+        target: Any,
+        model: type[Any],
+        *,
+        orm: ORM,
+    ) -> Any:
+        """Compiles and applies the query using the provided ORM.
+
+        Args:
+            target: ORM-specific target to mutate.
+            model: ORM model class used to resolve the query.
+            orm: ORM adapter used to compile the query.
+
+        Returns:
+            The value returned by the ORM-specific apply operation.
+        """
+        return self.compile(orm=orm).apply(target=target, model=model)

pyrsql/core/sort.py

@@ -0,0 +1,153 @@
+"""High-level sort object."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyrsql.core.compiler import SortCompilationResult
+from pyrsql.core.options import SortOptions
+from pyrsql.orms.base import ORM
+from pyrsql.sorting.analyzer import SortAnalyzer
+from pyrsql.sorting.ast import SortField
+from pyrsql.sorting.parser import SortParser
+from pyrsql.sorting.semantic import SemanticSortField
+
+_DEFAULT_SORT_OPTIONS = SortOptions()
+
+
+def _resolve_sort_options(
+    options: SortOptions | None,
+) -> SortOptions:
+    """Returns the provided options or the shared immutable default."""
+    return options or _DEFAULT_SORT_OPTIONS
+
+
+def _parse_sort_fields(
+    sort_text: str | None,
+    *,
+    options: SortOptions,
+) -> tuple[SortField, ...]:
+    """Parses raw sort text into sort fields."""
+    return SortParser(
+        sort_text,
+        limits=options.sort_limits,
+    ).parse()
+
+
+def _analyze_sort_fields(
+    fields: tuple[SortField, ...],
+    *,
+    options: SortOptions,
+) -> tuple[SemanticSortField, ...]:
+    """Analyzes sort fields into semantic sort fields."""
+    return SortAnalyzer(options).analyze(fields)
+
+
+@dataclass(frozen=True, slots=True)
+class Sort:
+    """Represents an ORM-neutral parsed sort request.
+
+    Attributes:
+        text: Raw sort text used to build the request.
+        options: Normalized sort configuration used during parsing.
+        fields: Parsed sort fields, if parsing succeeded.
+        semantic_fields: Semantic sort fields, if analysis succeeded.
+    """
+
+    text: str | None
+    options: SortOptions
+    fields: tuple[SortField, ...] = ()
+    semantic_fields: tuple[SemanticSortField, ...] = ()
+
+    @classmethod
+    def parse(
+        cls,
+        sort_text: str | None,
+        *,
+        options: SortOptions | None = None,
+    ) -> "Sort":
+        """Parses raw sort text into a sort object.
+
+        Args:
+            sort_text: Raw sort text to parse.
+            options: Optional sort configuration.
+
+        Returns:
+            A parsed sort object.
+        """
+        resolved_options = _resolve_sort_options(options)
+        fields = cls.parse_fields(sort_text, options=resolved_options)
+        semantic_fields = cls.analyze_fields(fields, options=resolved_options)
+        return cls(
+            text=sort_text,
+            options=resolved_options,
+            fields=fields,
+            semantic_fields=semantic_fields,
+        )
+
+    @staticmethod
+    def parse_fields(
+        sort_text: str | None,
+        *,
+        options: SortOptions,
+    ) -> tuple[SortField, ...]:
+        """Parses raw sort text into sort fields.
+
+        Args:
+            sort_text: Raw sort text to parse.
+            options: Sort configuration used by the parser.
+
+        Returns:
+            The parsed sort fields.
+        """
+        return _parse_sort_fields(sort_text, options=options)
+
+    @staticmethod
+    def analyze_fields(
+        fields: tuple[SortField, ...],
+        *,
+        options: SortOptions,
+    ) -> tuple[SemanticSortField, ...]:
+        """Analyzes sort fields into semantic sort fields.
+
+        Args:
+            fields: Parsed sort fields to analyze.
+            options: Sort configuration used by semantic analysis.
+
+        Returns:
+            The semantic sort fields.
+        """
+        return _analyze_sort_fields(fields, options=options)
+
+    def compile(self, *, orm: ORM) -> SortCompilationResult:
+        """Compiles the sort using the provided ORM.
+
+        Args:
+            orm: ORM adapter used to compile the sort.
+
+        Returns:
+            The ORM-specific sort compilation result.
+        """
+        compiled_sort = orm.compile_sort(self)
+        return SortCompilationResult(
+            orm_name=orm.name,
+            compiled_sort=compiled_sort,
+        )
+
+    def apply(
+        self,
+        target: Any,
+        model: type[Any],
+        *,
+        orm: ORM,
+    ) -> Any:
+        """Compiles and applies the sort using the provided ORM.
+
+        Args:
+            target: ORM-specific target to mutate.
+            model: ORM model class used to resolve the sort.
+            orm: ORM adapter used to compile the sort.
+
+        Returns:
+            The value returned by the ORM-specific apply operation.
+        """
+        return self.compile(orm=orm).apply(target=target, model=model)

pyrsql/integrations/__init__.py

@@ -0,0 +1,8 @@
+"""Framework and ORM integration helpers."""
+
+from pyrsql.integrations.fastapi import (
+    FastAPISQLAlchemyIntegration,
+    SQLAlchemyPaginatedSelect,
+)
+
+__all__ = ["FastAPISQLAlchemyIntegration", "SQLAlchemyPaginatedSelect"]

pyrsql/integrations/fastapi/__init__.py

@@ -0,0 +1,8 @@
+"""FastAPI integration helpers."""
+
+from pyrsql.integrations.fastapi.sqlalchemy import (
+    FastAPISQLAlchemyIntegration,
+    SQLAlchemyPaginatedSelect,
+)
+
+__all__ = ["FastAPISQLAlchemyIntegration", "SQLAlchemyPaginatedSelect"]

pyrsql/integrations/fastapi/sqlalchemy.py

@@ -0,0 +1,251 @@
+"""FastAPI + SQLAlchemy integration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, cast
+
+try:
+    from fastapi import Depends
+except ImportError as error:  # pragma: no cover - import guard
+    raise ImportError(
+        "FastAPI integration requires installing the 'fastapi' extra: "
+        "pip install pyrsql[fastapi]"
+    ) from error
+
+from sqlalchemy import func, select
+
+from pyrsql.adapters.fastapi import (
+    CriteriaDependency,
+    FastAPICriteriaConfig,
+    RequestCriteria,
+)
+from pyrsql.orms.sqlalchemy import SQLAlchemyORM
+from pyrsql.orms.sqlalchemy.types import SQLAlchemyModel, SQLAlchemySelect
+
+_DEFAULT_SQLALCHEMY_ORM = SQLAlchemyORM()
+_DEFAULT_FASTAPI_CRITERIA_CONFIG = FastAPICriteriaConfig()
+
+
+@dataclass(frozen=True, slots=True)
+class SQLAlchemyPaginatedSelect:
+    """Carries the list and count statements for a paginated query flow."""
+
+    statement: SQLAlchemySelect
+    count_statement: SQLAlchemySelect
+
+
+class FastAPISQLAlchemyIntegration:
+    """Composes the FastAPI adapter with the SQLAlchemy ORM integration."""
+
+    __slots__ = (
+        "orm",
+        "criteria_config",
+        "_criteria_dependency",
+        "_select_dependencies",
+        "_count_select_dependencies",
+        "_paginated_select_dependencies",
+        "_base_selects",
+    )
+
+    def __init__(
+        self,
+        *,
+        orm: SQLAlchemyORM | None = None,
+        criteria_config: FastAPICriteriaConfig | None = None,
+    ) -> None:
+        """Creates an integration helper for FastAPI and SQLAlchemy."""
+        self.orm = orm or _DEFAULT_SQLALCHEMY_ORM
+        self.criteria_config = (
+            criteria_config or _DEFAULT_FASTAPI_CRITERIA_CONFIG
+        )
+        self._criteria_dependency = CriteriaDependency(self.criteria_config)
+        self._select_dependencies: dict[
+            SQLAlchemyModel, Callable[..., SQLAlchemySelect]
+        ] = {}
+        self._count_select_dependencies: dict[
+            SQLAlchemyModel, Callable[..., SQLAlchemySelect]
+        ] = {}
+        self._paginated_select_dependencies: dict[
+            SQLAlchemyModel, Callable[..., SQLAlchemyPaginatedSelect]
+        ] = {}
+        self._base_selects: dict[SQLAlchemyModel, SQLAlchemySelect] = {}
+
+    def criteria_dependency(self) -> CriteriaDependency:
+        """Returns a configured FastAPI dependency for request criteria."""
+        return self._criteria_dependency
+
+    def _apply_query(
+        self,
+        statement: SQLAlchemySelect,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemySelect:
+        """Applies only the filtering part of request criteria."""
+        if criteria.query is None:
+            return statement
+        return cast(
+            SQLAlchemySelect,
+            criteria.query.apply(statement, model, orm=self.orm),
+        )
+
+    def _apply_sort_and_page(
+        self,
+        statement: SQLAlchemySelect,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemySelect:
+        """Applies sort and page semantics on top of a filtered statement."""
+        updated_statement = statement
+        if criteria.sort is not None:
+            updated_statement = cast(
+                SQLAlchemySelect,
+                criteria.sort.apply(updated_statement, model, orm=self.orm),
+            )
+        if criteria.page_request is not None:
+            updated_statement = cast(
+                SQLAlchemySelect,
+                criteria.page_request.apply(
+                    updated_statement,
+                    model,
+                    orm=self.orm,
+                ),
+            )
+        return updated_statement
+
+    def _filtered_select(
+        self,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemySelect:
+        """Builds the common filtered select used by list and count flows."""
+        return self._apply_query(self._base_select(model), model, criteria)
+
+    def _base_select(self, model: SQLAlchemyModel) -> SQLAlchemySelect:
+        """Returns a cached base select(model) statement."""
+        statement = self._base_selects.get(model)
+        if statement is not None:
+            return statement
+        statement = select(model)
+        self._base_selects[model] = statement
+        return statement
+
+    def _count_from_filtered_select(
+        self,
+        filtered_statement: SQLAlchemySelect,
+    ) -> SQLAlchemySelect:
+        """Builds a count statement from an already-filtered select."""
+        return select(func.count()).select_from(  # pylint: disable=not-callable
+            filtered_statement.order_by(None).subquery()
+        )
+
+    def apply(
+        self,
+        statement: SQLAlchemySelect,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemySelect:
+        """Applies request criteria to an existing SQLAlchemy select."""
+        return cast(
+            SQLAlchemySelect,
+            criteria.apply(statement, model, orm=self.orm),
+        )
+
+    def select(
+        self,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemySelect:
+        """Builds a select statement for a model and applies criteria."""
+        filtered_statement = self._filtered_select(model, criteria)
+        return self._apply_sort_and_page(
+            filtered_statement,
+            model,
+            criteria,
+        )
+
+    def count_select(
+        self,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemySelect:
+        """Builds a count statement from the filtered query semantics only."""
+        return self._count_from_filtered_select(
+            self._filtered_select(model, criteria)
+        )
+
+    def paginated_select(
+        self,
+        model: SQLAlchemyModel,
+        criteria: RequestCriteria,
+    ) -> SQLAlchemyPaginatedSelect:
+        """Builds both list and count statements for a paginated flow."""
+        filtered_statement = self._filtered_select(model, criteria)
+        return SQLAlchemyPaginatedSelect(
+            statement=self._apply_sort_and_page(
+                filtered_statement,
+                model,
+                criteria,
+            ),
+            count_statement=self._count_from_filtered_select(
+                filtered_statement
+            ),
+        )
+
+    def select_dependency(
+        self,
+        model: SQLAlchemyModel,
+    ) -> Callable[..., SQLAlchemySelect]:
+        """Returns a FastAPI dependency that yields a filtered select."""
+        cached_dependency = self._select_dependencies.get(model)
+        if cached_dependency is not None:
+            return cached_dependency
+        criteria_dependency = self.criteria_dependency()
+
+        def dependency(
+            criteria: Any = Depends(criteria_dependency),
+        ) -> SQLAlchemySelect:
+            return self.select(model, cast(RequestCriteria, criteria))
+
+        self._select_dependencies[model] = dependency
+        return dependency
+
+    def count_select_dependency(
+        self,
+        model: SQLAlchemyModel,
+    ) -> Callable[..., SQLAlchemySelect]:
+        """Returns a FastAPI dependency that yields a count select."""
+        cached_dependency = self._count_select_dependencies.get(model)
+        if cached_dependency is not None:
+            return cached_dependency
+        criteria_dependency = self.criteria_dependency()
+
+        def dependency(
+            criteria: Any = Depends(criteria_dependency),
+        ) -> SQLAlchemySelect:
+            return self.count_select(model, cast(RequestCriteria, criteria))
+
+        self._count_select_dependencies[model] = dependency
+        return dependency
+
+    def paginated_select_dependency(
+        self,
+        model: SQLAlchemyModel,
+    ) -> Callable[..., SQLAlchemyPaginatedSelect]:
+        """Returns a FastAPI dependency yielding list and count statements."""
+        cached_dependency = self._paginated_select_dependencies.get(model)
+        if cached_dependency is not None:
+            return cached_dependency
+        criteria_dependency = self.criteria_dependency()
+
+        def dependency(
+            criteria: Any = Depends(criteria_dependency),
+        ) -> SQLAlchemyPaginatedSelect:
+            return self.paginated_select(
+                model,
+                cast(RequestCriteria, criteria),
+            )
+
+        self._paginated_select_dependencies[model] = dependency
+        return dependency

pyrsql/orms/__init__.py

@@ -0,0 +1,15 @@
+"""ORM integrations for pyrsql."""
+
+from pyrsql.orms.base import (
+    ORM,
+    CompiledPageRequest,
+    CompiledQuery,
+    CompiledSort,
+)
+
+__all__ = [
+    "ORM",
+    "CompiledPageRequest",
+    "CompiledQuery",
+    "CompiledSort",
+]

pyrsql/orms/base.py

@@ -0,0 +1,99 @@
+"""Shared ORM contracts."""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from pyrsql.core.page import PageRequest
+    from pyrsql.core.query import Query
+    from pyrsql.core.sort import Sort
+
+
+class CompiledQuery(Protocol):
+    """Protocol implemented by ORM-specific compiled query objects."""
+
+    def apply(self, target: Any, model: type[Any]) -> Any:
+        """Applies a compiled query to an ORM-specific target.
+
+        Args:
+            target: ORM-specific target to mutate.
+            model: ORM model class used to resolve the query.
+
+        Returns:
+            The value returned by the compiled query application.
+        """
+
+
+class CompiledSort(Protocol):
+    """Protocol implemented by ORM-specific compiled sort objects."""
+
+    def apply(self, target: Any, model: type[Any]) -> Any:
+        """Applies a compiled sort to an ORM-specific target.
+
+        Args:
+            target: ORM-specific target to mutate.
+            model: ORM model class used to resolve the sort.
+
+        Returns:
+            The value returned by the compiled sort application.
+        """
+
+
+class CompiledPageRequest(Protocol):
+    """Protocol implemented by ORM-specific compiled page objects."""
+
+    def apply(self, target: Any, model: type[Any]) -> Any:
+        """Applies a compiled page request to an ORM-specific target.
+
+        Args:
+            target: ORM-specific target to mutate.
+            model: ORM model class used to resolve the page request.
+
+        Returns:
+            The value returned by the compiled page application.
+        """
+
+
+class ORM(ABC):
+    """Abstract ORM contract used by the pyrsql public API."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The stable ORM name."""
+
+    @abstractmethod
+    def compile_query(self, query: "Query") -> CompiledQuery:
+        """Compiles a high-level query into an ORM-specific form.
+
+        Args:
+            query: High-level query to compile.
+
+        Returns:
+            A compiled query object for this ORM.
+        """
+
+    @abstractmethod
+    def compile_sort(self, sort: "Sort") -> CompiledSort:
+        """Compiles a high-level sort into an ORM-specific form.
+
+        Args:
+            sort: High-level sort request to compile.
+
+        Returns:
+            A compiled sort object for this ORM.
+        """
+
+    @abstractmethod
+    def compile_page_request(
+        self,
+        page_request: "PageRequest",
+    ) -> CompiledPageRequest:
+        """Compiles a pagination request into an ORM-specific form.
+
+        Args:
+            page_request: Pagination request to compile.
+
+        Returns:
+            A compiled page request object for this ORM.
+        """