pyrsql 0.0.1__py3-none-any.whl

pyrsql/__init__.py

@@ -0,0 +1,63 @@
+"""Public package interface for pyrsql."""
+
+# pylint: disable=redefined-builtin
+
+import pyrsql.api as api
+from pyrsql.core.compiler import (
+    CompilationResult,
+    PageCompilationResult,
+    SortCompilationResult,
+)
+from pyrsql.core.conversion import (
+    FieldValueConverterSet,
+    ValueConverter,
+    ValueConverterRegistry,
+)
+from pyrsql.core.custom import CustomPredicateDefinition
+from pyrsql.core.field_policy import FieldPolicySet
+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 JSONScalarNormalizer, JSONScalarValue
+from pyrsql.core.options import QueryOptions, SortOptions
+from pyrsql.core.page import PageRequest
+from pyrsql.core.procedure_policy import ProcedureAccessPolicy
+from pyrsql.core.query import Query
+from pyrsql.core.sort import Sort
+from pyrsql.integrations import (
+    FastAPISQLAlchemyIntegration,
+    SQLAlchemyPaginatedSelect,
+)
+from pyrsql.orms.base import ORM
+
+parse = api.parse
+compile = api.compile
+apply = api.apply
+
+__all__ = [
+    "ORM",
+    "CompilationResult",
+    "CustomPredicateDefinition",
+    "FieldPolicySet",
+    "FieldValueConverterSet",
+    "FastAPISQLAlchemyIntegration",
+    "JSONOptions",
+    "JSONPath",
+    "JSONPathComparison",
+    "JSONScalarNormalizer",
+    "JSONScalarValue",
+    "PageCompilationResult",
+    "PageRequest",
+    "ProcedureAccessPolicy",
+    "Query",
+    "QueryOptions",
+    "Sort",
+    "SortCompilationResult",
+    "SortOptions",
+    "SQLAlchemyPaginatedSelect",
+    "ValueConverter",
+    "ValueConverterRegistry",
+    "apply",
+    "compile",
+    "parse",
+]

pyrsql/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""Framework adapter implementations for pyrsql."""
+
+__all__: list[str] = []

pyrsql/adapters/fastapi/__init__.py

@@ -0,0 +1,15 @@
+"""FastAPI adapter for pyrsql request extraction and error translation."""
+
+from pyrsql.adapters.fastapi.config import FastAPICriteriaConfig
+from pyrsql.adapters.fastapi.criteria import RequestCriteria
+from pyrsql.adapters.fastapi.dependency import (
+    CriteriaDependency,
+    criteria_dependency,
+)
+
+__all__ = [
+    "CriteriaDependency",
+    "FastAPICriteriaConfig",
+    "RequestCriteria",
+    "criteria_dependency",
+]

pyrsql/adapters/fastapi/config.py

@@ -0,0 +1,76 @@
+"""Configuration objects for the FastAPI adapter."""
+
+from dataclasses import dataclass, field
+
+from pyrsql.core.options import QueryOptions, SortOptions
+
+_DEFAULT_FILTER_PARAMETER = "filter"
+_DEFAULT_SORT_PARAMETER = "sort"
+_DEFAULT_PAGE_PARAMETER = "page"
+_DEFAULT_SIZE_PARAMETER = "size"
+
+
+@dataclass(frozen=True, slots=True)
+class FastAPICriteriaConfig:
+    """Configures FastAPI query parameter extraction for pyrsql.
+
+    Attributes:
+        filter_parameter: Query parameter used for filtering expressions.
+        sort_parameter: Query parameter used for sort expressions.
+        page_parameter: Query parameter used for page numbers.
+        size_parameter: Query parameter used for page size.
+        default_page_size: Default size used when only a page number is given.
+        max_page_size: Maximum accepted page size.
+        one_based_paging: Whether page numbers start at 1 instead of 0.
+        query_options: Query parsing and semantic configuration.
+        sort_options: Sort parsing and semantic configuration.
+    """
+
+    filter_parameter: str = _DEFAULT_FILTER_PARAMETER
+    sort_parameter: str = _DEFAULT_SORT_PARAMETER
+    page_parameter: str = _DEFAULT_PAGE_PARAMETER
+    size_parameter: str = _DEFAULT_SIZE_PARAMETER
+    default_page_size: int | None = None
+    max_page_size: int | None = None
+    one_based_paging: bool = False
+    query_options: QueryOptions = field(default_factory=QueryOptions)
+    sort_options: SortOptions = field(default_factory=SortOptions)
+
+    def __post_init__(self) -> None:
+        """Validates adapter configuration invariants.
+
+        Raises:
+            ValueError: If parameter names are empty, duplicated, or paging
+            limits are inconsistent.
+        """
+        parameter_names = (
+            self.filter_parameter,
+            self.sort_parameter,
+            self.page_parameter,
+            self.size_parameter,
+        )
+        normalized_names = tuple(name.strip() for name in parameter_names)
+        if any(not name for name in normalized_names):
+            raise ValueError("FastAPI parameter names must not be empty.")
+        if len(set(normalized_names)) != len(normalized_names):
+            raise ValueError("FastAPI parameter names must be unique.")
+        if self.default_page_size is not None and self.default_page_size <= 0:
+            raise ValueError("default_page_size must be greater than 0.")
+        if self.max_page_size is not None and self.max_page_size <= 0:
+            raise ValueError("max_page_size must be greater than 0.")
+        if (
+            self.default_page_size is not None
+            and self.max_page_size is not None
+            and self.default_page_size > self.max_page_size
+        ):
+            raise ValueError("default_page_size must not exceed max_page_size.")
+
+    @property
+    def minimum_page_number(self) -> int:
+        """The minimum accepted page number for the adapter."""
+        return 1 if self.one_based_paging else 0
+
+    @property
+    def default_page_number(self) -> int:
+        """The page number used when only size is provided."""
+        return 1 if self.one_based_paging else 0

pyrsql/adapters/fastapi/criteria.py

@@ -0,0 +1,56 @@
+"""FastAPI request criteria objects."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyrsql.core.page import PageRequest
+from pyrsql.core.query import Query
+from pyrsql.core.sort import Sort
+from pyrsql.orms.base import ORM
+
+
+@dataclass(frozen=True, slots=True)
+class RequestCriteria:
+    """Represents request-derived pyrsql criteria for a FastAPI endpoint."""
+
+    query: Query | None = None
+    sort: Sort | None = None
+    page_request: PageRequest | None = None
+
+    @property
+    def is_empty(self) -> bool:
+        """Indicates whether no query components are present."""
+        return (
+            self.query is None
+            and self.sort is None
+            and self.page_request is None
+        )
+
+    def apply(
+        self,
+        target: Any,
+        model: type[Any],
+        *,
+        orm: ORM,
+    ) -> Any:
+        """Applies the criteria to an ORM-specific target."""
+        current_target = target
+        if self.query is not None:
+            current_target = self.query.apply(
+                current_target,
+                model,
+                orm=orm,
+            )
+        if self.sort is not None:
+            current_target = self.sort.apply(
+                current_target,
+                model,
+                orm=orm,
+            )
+        if self.page_request is not None:
+            current_target = self.page_request.apply(
+                current_target,
+                model,
+                orm=orm,
+            )
+        return current_target

pyrsql/adapters/fastapi/dependency.py

@@ -0,0 +1,217 @@
+"""Dependency factories for FastAPI request integration."""
+
+from collections.abc import Callable
+from inspect import Signature, signature
+from typing import Annotated, Any
+
+try:
+    from fastapi import HTTPException, Query
+except ImportError as error:  # pragma: no cover - import guard
+    raise ImportError(
+        "FastAPI support requires installing the 'fastapi' extra: "
+        "pip install pyrsql[fastapi]"
+    ) from error
+
+from pyrsql.adapters.fastapi.config import FastAPICriteriaConfig
+from pyrsql.adapters.fastapi.criteria import RequestCriteria
+from pyrsql.adapters.fastapi.errors import (
+    FastAPIAdapterErrorPayload,
+    build_page_error_payload,
+    build_query_error_payload,
+    build_sort_error_payload,
+)
+from pyrsql.core.page import PageRequest
+from pyrsql.core.query import Query as PyrsqlQuery
+from pyrsql.core.sort import Sort as PyrsqlSort
+from pyrsql.parsing.errors import ParseError
+from pyrsql.semantic.errors import SemanticError
+from pyrsql.sorting.errors import (
+    SortFieldBlacklistedError,
+    SortFieldNotWhitelistedError,
+    SortFunctionBlacklistedError,
+    SortFunctionNotWhitelistedError,
+    SortParseError,
+)
+
+_QUERY_ERROR_TYPES = (ParseError, SemanticError)
+_SORT_ERROR_TYPES = (
+    SortParseError,
+    SortFieldNotWhitelistedError,
+    SortFieldBlacklistedError,
+    SortFunctionNotWhitelistedError,
+    SortFunctionBlacklistedError,
+)
+_DEFAULT_FASTAPI_CRITERIA_CONFIG = FastAPICriteriaConfig()
+
+
+def _raise_http_error(payload: FastAPIAdapterErrorPayload) -> None:
+    """Raises a standardized FastAPI HTTP exception for adapter failures."""
+    raise HTTPException(
+        status_code=422,
+        detail={
+            "parameter": payload.parameter,
+            "type": payload.error_type,
+            "message": payload.message,
+        },
+    )
+
+
+def _build_page_request(
+    *,
+    config: FastAPICriteriaConfig,
+    page_value: int | None,
+    size_value: int | None,
+) -> PageRequest | None:
+    """Builds a page request from validated FastAPI query params."""
+    resolved_page_size = size_value or config.default_page_size
+
+    if page_value is None:
+        if resolved_page_size is None:
+            return None
+        resolved_page_number = config.default_page_number
+    else:
+        resolved_page_number = page_value
+
+    if resolved_page_size is None:
+        _raise_http_error(
+            build_page_error_payload(
+                config.size_parameter,
+                error_type="page_configuration_error",
+                message=(
+                    f"'{config.size_parameter}' is required when "
+                    f"'{config.page_parameter}' is provided."
+                ),
+            )
+        )
+
+    if resolved_page_size is None:
+        raise ValueError("resolved_page_size cannot be None")
+
+    if config.one_based_paging:
+        if resolved_page_number <= 0:
+            _raise_http_error(
+                build_page_error_payload(
+                    config.page_parameter,
+                    error_type="page_validation_error",
+                    message=(
+                        f"'{config.page_parameter}' must be greater than 0 "
+                        "when one_based_paging is enabled."
+                    ),
+                )
+            )
+        resolved_page_number -= 1
+
+    return PageRequest.of(resolved_page_number, resolved_page_size)
+
+
+def _build_criteria_callable(
+    config: FastAPICriteriaConfig,
+) -> Callable[..., RequestCriteria]:
+    """Builds the concrete dependency callable for a fixed configuration."""
+
+    def dependency(
+        filter_value: Annotated[
+            str | None,
+            Query(alias=config.filter_parameter),
+        ] = None,
+        sort_value: Annotated[
+            str | None,
+            Query(alias=config.sort_parameter),
+        ] = None,
+        page_value: Annotated[
+            int | None,
+            Query(
+                alias=config.page_parameter,
+                ge=config.minimum_page_number,
+            ),
+        ] = None,
+        size_value: Annotated[
+            int | None,
+            Query(
+                alias=config.size_parameter,
+                gt=0,
+                le=config.max_page_size,
+            ),
+        ] = None,
+    ) -> RequestCriteria:
+        query = None
+        sort = None
+
+        if filter_value:
+            try:
+                query = PyrsqlQuery.parse(
+                    filter_value,
+                    options=config.query_options,
+                )
+            except _QUERY_ERROR_TYPES as error:
+                _raise_http_error(
+                    build_query_error_payload(config.filter_parameter, error)
+                )
+
+        if sort_value:
+            try:
+                sort = PyrsqlSort.parse(
+                    sort_value,
+                    options=config.sort_options,
+                )
+            except _SORT_ERROR_TYPES as error:
+                _raise_http_error(
+                    build_sort_error_payload(config.sort_parameter, error)
+                )
+
+        page_request = _build_page_request(
+            config=config,
+            page_value=page_value,
+            size_value=size_value,
+        )
+
+        return RequestCriteria(
+            query=query,
+            sort=sort,
+            page_request=page_request,
+        )
+
+    return dependency
+
+
+class CriteriaDependency:
+    """Callable FastAPI dependency object that resolves request criteria.
+
+    The generated signature exposes FastAPI query parameters and returns a
+    parsed RequestCriteria object.
+    """
+
+    def __init__(
+        self,
+        config: FastAPICriteriaConfig | None = None,
+    ) -> None:
+        """Creates a dependency object for the provided FastAPI config.
+
+        Args:
+            config: Optional FastAPI criteria configuration.
+        """
+        self.config = config or _DEFAULT_FASTAPI_CRITERIA_CONFIG
+        self._dependency = _build_criteria_callable(self.config)
+        self.__signature__: Signature = signature(self._dependency)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> RequestCriteria:
+        """Delegates FastAPI dependency resolution to the generated callable.
+
+        Returns:
+            Parsed request criteria for the incoming FastAPI query params.
+        """
+        return self._dependency(*args, **kwargs)
+
+
+def criteria_dependency(
+    config: FastAPICriteriaConfig | None = None,
+) -> CriteriaDependency:
+    """Builds a FastAPI dependency object that returns parsed criteria.
+
+    Args:
+        config: Optional FastAPI criteria configuration.
+
+    Returns:
+        A callable FastAPI dependency object.
+    """
+    return CriteriaDependency(config)

pyrsql/adapters/fastapi/errors.py

@@ -0,0 +1,107 @@
+"""FastAPI adapter error helpers."""
+
+from dataclasses import dataclass
+
+from pyrsql.parsing.errors import ParseError
+from pyrsql.semantic.errors import SemanticError
+from pyrsql.sorting.errors import (
+    SortFieldBlacklistedError,
+    SortFieldNotWhitelistedError,
+    SortFunctionBlacklistedError,
+    SortFunctionNotWhitelistedError,
+    SortParseError,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class FastAPIAdapterErrorPayload:
+    """Structured adapter error payload for HTTP translation.
+
+    Attributes:
+        parameter: Name of the query parameter associated with the failure.
+        error_type: Stable machine-readable error category.
+        message: Human-readable error message.
+    """
+
+    parameter: str
+    error_type: str
+    message: str
+
+
+def build_query_error_payload(
+    parameter_name: str,
+    error: ParseError | SemanticError,
+) -> FastAPIAdapterErrorPayload:
+    """Builds a payload for a filter/query parsing or semantic failure.
+
+    Args:
+        parameter_name: Query parameter name associated with the failure.
+        error: Parsing or semantic error raised by pyrsql.
+
+    Returns:
+        A normalized FastAPI error payload.
+    """
+    error_type = "query_parse_error"
+    if isinstance(error, SemanticError):
+        error_type = "query_semantic_error"
+    return FastAPIAdapterErrorPayload(
+        parameter=parameter_name,
+        error_type=error_type,
+        message=str(error),
+    )
+
+
+def build_sort_error_payload(
+    parameter_name: str,
+    error: Exception,
+) -> FastAPIAdapterErrorPayload:
+    """Builds a payload for a sort parsing or semantic failure.
+
+    Args:
+        parameter_name: Query parameter name associated with the failure.
+        error: Sorting error raised by pyrsql.
+
+    Returns:
+        A normalized FastAPI error payload.
+    """
+    error_type = "sort_error"
+    if isinstance(error, SortParseError):
+        error_type = "sort_parse_error"
+    elif isinstance(
+        error,
+        (
+            SortFieldNotWhitelistedError,
+            SortFieldBlacklistedError,
+            SortFunctionNotWhitelistedError,
+            SortFunctionBlacklistedError,
+        ),
+    ):
+        error_type = "sort_semantic_error"
+    return FastAPIAdapterErrorPayload(
+        parameter=parameter_name,
+        error_type=error_type,
+        message=str(error),
+    )
+
+
+def build_page_error_payload(
+    parameter_name: str,
+    *,
+    error_type: str,
+    message: str,
+) -> FastAPIAdapterErrorPayload:
+    """Builds a payload for page-related adapter validation failures.
+
+    Args:
+        parameter_name: Query parameter name associated with the failure.
+        error_type: Machine-readable error category.
+        message: Human-readable error message.
+
+    Returns:
+        A normalized FastAPI error payload.
+    """
+    return FastAPIAdapterErrorPayload(
+        parameter=parameter_name,
+        error_type=error_type,
+        message=message,
+    )

pyrsql/api.py

@@ -0,0 +1,76 @@
+"""ORM-neutral high-level API for pyrsql."""
+
+# pylint: disable=redefined-builtin
+
+from typing import Any
+
+from pyrsql.core.compiler import CompilationResult
+from pyrsql.core.options import QueryOptions
+from pyrsql.core.query import Query
+from pyrsql.orms.base import ORM
+
+
+def parse(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.
+    """
+    return Query.parse(query_text, options=options)
+
+
+def compile(
+    query_text: str,
+    *,
+    orm: ORM,
+    options: QueryOptions | None = None,
+) -> CompilationResult:
+    """Compiles raw RSQL text using the provided ORM.
+
+    Args:
+        query_text: Raw RSQL text to compile.
+        orm: ORM adapter used to compile the query.
+        options: Optional query configuration.
+
+    Returns:
+        The ORM-specific compilation result.
+    """
+    return parse(query_text, options=options).compile(orm=orm)
+
+
+def apply(
+    target: Any,
+    model: type[Any],
+    query_text: str,
+    *,
+    orm: ORM,
+    options: QueryOptions | None = None,
+) -> Any:
+    """Applies raw RSQL text to an ORM-specific target.
+
+    Args:
+        target: ORM-specific target to mutate.
+        model: ORM model class used to resolve the query.
+        query_text: Raw RSQL text to apply.
+        orm: ORM adapter used to compile the query.
+        options: Optional query configuration.
+
+    Returns:
+        The value returned by the ORM-specific apply operation.
+    """
+    return compile(
+        query_text,
+        orm=orm,
+        options=options,
+    ).apply(target=target, model=model)
+
+
+__all__ = [
+    "apply",
+    "compile",
+    "parse",
+]

pyrsql/core/__init__.py

@@ -0,0 +1,45 @@
+"""Core ORM-agnostic pyrsql types."""
+
+from pyrsql.core.compiler import (
+    CompilationResult,
+    PageCompilationResult,
+    SortCompilationResult,
+)
+from pyrsql.core.conversion import (
+    FieldValueConverterSet,
+    ValueConverter,
+    ValueConverterRegistry,
+)
+from pyrsql.core.custom import CustomPredicateDefinition
+from pyrsql.core.field_policy import FieldPolicySet
+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 JSONScalarNormalizer, JSONScalarValue
+from pyrsql.core.options import QueryOptions, SortOptions
+from pyrsql.core.page import PageRequest
+from pyrsql.core.procedure_policy import ProcedureAccessPolicy
+from pyrsql.core.query import Query
+from pyrsql.core.sort import Sort
+
+__all__ = [
+    "CompilationResult",
+    "CustomPredicateDefinition",
+    "FieldPolicySet",
+    "FieldValueConverterSet",
+    "JSONOptions",
+    "JSONPath",
+    "JSONPathComparison",
+    "JSONScalarNormalizer",
+    "JSONScalarValue",
+    "PageCompilationResult",
+    "PageRequest",
+    "ProcedureAccessPolicy",
+    "Query",
+    "QueryOptions",
+    "Sort",
+    "SortCompilationResult",
+    "SortOptions",
+    "ValueConverter",
+    "ValueConverterRegistry",
+]