pyrsql 0.0.1__py3-none-any.whl

pyrsql/core/compiler.py

@@ -0,0 +1,81 @@
+"""ORM-neutral compilation result objects."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyrsql.orms.base import CompiledPageRequest, CompiledQuery, CompiledSort
+
+
+@dataclass(frozen=True, slots=True)
+class CompilationResult:
+    """Wraps an ORM-specific compiled query object.
+
+    Attributes:
+        orm_name: Name of the ORM used to produce the compilation.
+        compiled_query: ORM-specific compiled query payload.
+    """
+
+    orm_name: str
+    compiled_query: CompiledQuery
+
+    def apply(self, target: Any, model: type[Any]) -> Any:
+        """Applies the 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.
+        """
+        return self.compiled_query.apply(target=target, model=model)
+
+
+@dataclass(frozen=True, slots=True)
+class SortCompilationResult:
+    """Wraps an ORM-specific compiled sort object.
+
+    Attributes:
+        orm_name: Name of the ORM used to produce the compilation.
+        compiled_sort: ORM-specific compiled sort payload.
+    """
+
+    orm_name: str
+    compiled_sort: CompiledSort
+
+    def apply(self, target: Any, model: type[Any]) -> Any:
+        """Applies the 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.
+        """
+        return self.compiled_sort.apply(target=target, model=model)
+
+
+@dataclass(frozen=True, slots=True)
+class PageCompilationResult:
+    """Wraps an ORM-specific compiled page request object.
+
+    Attributes:
+        orm_name: Name of the ORM used to produce the compilation.
+        compiled_page: ORM-specific compiled page payload.
+    """
+
+    orm_name: str
+    compiled_page: CompiledPageRequest
+
+    def apply(self, target: Any, model: type[Any]) -> Any:
+        """Applies the 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.
+        """
+        return self.compiled_page.apply(target=target, model=model)

pyrsql/core/conversion.py

@@ -0,0 +1,206 @@
+"""ORM-neutral value conversion support."""
+
+import datetime as dt
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum
+from types import MappingProxyType
+from typing import Any
+from uuid import UUID
+
+import ciso8601
+
+ValueConverter = Callable[[str], Any]
+
+
+class ValueConversionError(ValueError):
+    """Raised when a raw RSQL value cannot be converted."""
+
+
+def _convert_bool(raw_value: str) -> bool:
+    """Converts a string to bool using explicit accepted values."""
+    lowered = raw_value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    raise ValueConversionError(f"Cannot convert {raw_value!r} to bool.")
+
+
+@dataclass(frozen=True, slots=True)
+class ValueConverterRegistry:
+    """Immutable registry of orm-neutral string-to-type converters."""
+
+    converters: Mapping[type[Any], ValueConverter]
+
+    def __post_init__(self) -> None:
+        """Normalizes the converter mapping into an immutable view."""
+        object.__setattr__(
+            self,
+            "converters",
+            MappingProxyType(dict(self.converters)),
+        )
+
+    def with_converter(
+        self,
+        target_type: type[Any],
+        converter: ValueConverter,
+    ) -> "ValueConverterRegistry":
+        """Returns a new registry with one additional converter."""
+        updated = dict(self.converters)
+        updated[target_type] = converter
+        return ValueConverterRegistry(updated)
+
+    def convert(
+        self,
+        raw_value: str,
+        target_type: type[Any] | None,
+    ) -> Any:
+        """Converts a raw string into the requested target type."""
+        if target_type is None:
+            return raw_value
+
+        if target_type is dt.datetime:
+            return self._convert_datetime(raw_value)
+
+        converter = self._find_registered_converter(target_type)
+        if converter is not None:
+            try:
+                return converter(raw_value)
+            except Exception as error:  # pragma: no cover - defensive wrap
+                raise ValueConversionError(
+                    f"Failed to convert {raw_value!r} to "
+                    f"{target_type.__name__}."
+                ) from error
+
+        try:
+            if issubclass(target_type, Enum):
+                return self._convert_enum(raw_value, target_type)
+            if issubclass(target_type, str):
+                return raw_value
+        except TypeError as error:  # pragma: no cover - invalid type object
+            raise ValueConversionError(
+                f"Unsupported target type {target_type!r}."
+            ) from error
+
+        return self._construct_from_string(raw_value, target_type)
+
+    def _find_registered_converter(
+        self,
+        target_type: type[Any],
+    ) -> ValueConverter | None:
+        """Finds the most specific registered converter for a type."""
+        for candidate in target_type.__mro__:
+            converter = self.converters.get(candidate)
+            if converter is not None:
+                return converter
+        return None
+
+    def _convert_enum(
+        self,
+        raw_value: str,
+        target_type: type[Any],
+    ) -> Any:
+        """Converts a string into an enum member by name first."""
+        try:
+            return target_type[raw_value]
+        except KeyError:
+            try:
+                return target_type(raw_value)
+            except ValueError as error:
+                raise ValueConversionError(
+                    f"Failed to convert {raw_value!r} to "
+                    f"{target_type.__name__}."
+                ) from error
+
+    def _convert_datetime(self, raw_value: str) -> dt.datetime:
+        """Converts a string into datetime with LocalDate-style fallback."""
+        try:
+            parsed_datetime = ciso8601.parse_datetime(raw_value)
+        except ValueError:
+            parsed_datetime = None
+        if parsed_datetime is not None:
+            return parsed_datetime
+        try:
+            parsed_date = dt.date.fromisoformat(raw_value)
+        except ValueError as date_error:
+            raise ValueConversionError(
+                f"Failed to convert {raw_value!r} to datetime."
+            ) from date_error
+        return dt.datetime.combine(parsed_date, dt.time.min)
+
+    def _construct_from_string(
+        self,
+        raw_value: str,
+        target_type: type[Any],
+    ) -> Any:
+        """Attempts a plain constructor-based conversion as a fallback."""
+        try:
+            return target_type(raw_value)
+        except Exception as error:
+            raise ValueConversionError(
+                f"Failed to convert {raw_value!r} to {target_type.__name__}."
+            ) from error
+
+
+@dataclass(frozen=True, slots=True)
+class FieldValueConverterSet:
+    """Immutable field-scoped value converter configuration."""
+
+    field_converters: Mapping[str, ValueConverter]
+    model_field_converters: Mapping[type[Any], Mapping[str, ValueConverter]]
+
+    def __post_init__(self) -> None:
+        """Normalizes nested converter mappings into immutable views."""
+        object.__setattr__(
+            self,
+            "field_converters",
+            MappingProxyType(dict(self.field_converters)),
+        )
+        object.__setattr__(
+            self,
+            "model_field_converters",
+            MappingProxyType(
+                {
+                    model: MappingProxyType(dict(converters))
+                    for model, converters in self.model_field_converters.items()
+                }
+            ),
+        )
+
+    def resolve(
+        self,
+        *,
+        model: type[Any] | None,
+        field_name: str | None,
+        field_path: str | None,
+    ) -> ValueConverter | None:
+        """Resolves the most specific converter configured for a field."""
+        if model is not None and field_name is not None:
+            model_converters = self.model_field_converters.get(model)
+            if model_converters is not None:
+                converter = model_converters.get(field_name)
+                if converter is not None:
+                    return converter
+        if field_path is not None:
+            return self.field_converters.get(field_path)
+        return None
+
+
+DEFAULT_VALUE_CONVERTER_REGISTRY = ValueConverterRegistry(
+    {
+        bool: _convert_bool,
+        int: int,
+        float: float,
+        Decimal: Decimal,
+        UUID: UUID,
+        dt.date: dt.date.fromisoformat,
+        dt.time: dt.time.fromisoformat,
+    }
+)
+
+DEFAULT_FIELD_VALUE_CONVERTER_SET = FieldValueConverterSet(
+    field_converters={},
+    model_field_converters={},
+)

pyrsql/core/custom.py

@@ -0,0 +1,14 @@
+"""ORM-neutral custom predicate definitions."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyrsql.parsing.operators import ComparisonOperator
+
+
+@dataclass(frozen=True, slots=True)
+class CustomPredicateDefinition:
+    """Defines a custom predicate independently of any orm."""
+
+    operator: ComparisonOperator
+    argument_type: type[Any]

pyrsql/core/field_policy.py

@@ -0,0 +1,97 @@
+"""Shared field mapping and access-policy helpers."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class FieldPolicySet:
+    """ORM-neutral field mapping and access-policy configuration.
+
+    Attributes:
+        field_mapping: Global selector-to-field mapping.
+        field_whitelist: Globally allowed field paths.
+        field_blacklist: Globally blocked field paths.
+        model_field_mapping: Model-specific selector-to-field mappings.
+        model_field_whitelist: Model-specific allowed field names.
+        model_field_blacklist: Model-specific blocked field names.
+    """
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the policy carries no active restrictions."""
+        return not any(
+            (
+                self.field_mapping,
+                self.field_whitelist,
+                self.field_blacklist,
+                self.model_field_mapping,
+                self.model_field_whitelist,
+                self.model_field_blacklist,
+            )
+        )
+
+    field_mapping: Mapping[str, str]
+    field_whitelist: frozenset[str]
+    field_blacklist: frozenset[str]
+    model_field_mapping: Mapping[type[Any], Mapping[str, str]]
+    model_field_whitelist: Mapping[type[Any], frozenset[str]]
+    model_field_blacklist: Mapping[type[Any], frozenset[str]]
+
+    def map_model_field(
+        self,
+        model: type[Any],
+        selector: str,
+    ) -> str:
+        """Maps one selector segment for a specific model when configured.
+
+        Args:
+            model: ORM model used to look up a model-specific mapping.
+            selector: Raw selector segment to map.
+
+        Returns:
+            The mapped selector segment, or the original value when no mapping
+            is configured.
+        """
+        mapping = self.model_field_mapping.get(model)
+        if mapping is None:
+            return selector
+        return mapping.get(selector, selector)
+
+    def validate_global_field_access(self, field_path: str) -> None:
+        """Validates global whitelist and blacklist rules.
+
+        Args:
+            field_path: Dotted field path to validate.
+
+        Raises:
+            ValueError: If the field path is not allowed or is blocked.
+        """
+        if self.field_whitelist and field_path not in self.field_whitelist:
+            raise ValueError(f"Field {field_path!r} is not allowed.")
+        if field_path in self.field_blacklist:
+            raise ValueError(f"Field {field_path!r} is blocked.")
+
+    def validate_model_field_access(
+        self,
+        model: type[Any],
+        field_name: str,
+    ) -> None:
+        """Validates model-specific whitelist and blacklist rules.
+
+        Args:
+            model: ORM model used to look up model-specific rules.
+            field_name: Field name to validate.
+
+        Raises:
+            ValueError: If the field name is not allowed or is blocked.
+        """
+        whitelist = self.model_field_whitelist.get(model)
+        if whitelist is not None and field_name not in whitelist:
+            raise ValueError(
+                f"Field {model.__name__}.{field_name} is not allowed."
+            )
+        blacklist = self.model_field_blacklist.get(model)
+        if blacklist is not None and field_name in blacklist:
+            raise ValueError(f"Field {model.__name__}.{field_name} is blocked.")

pyrsql/core/joins.py

@@ -0,0 +1,11 @@
+"""ORM-neutral join hint definitions."""
+
+from enum import Enum
+
+
+class JoinHint(Enum):
+    """Supported orm-neutral join hint kinds."""
+
+    INNER = "inner"
+    LEFT = "left"
+    RIGHT = "right"

pyrsql/core/json/__init__.py

@@ -0,0 +1,19 @@
+"""ORM-neutral JSON query primitives."""
+
+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 (
+    DEFAULT_JSON_SCALAR_NORMALIZER,
+    JSONScalarNormalizer,
+    JSONScalarValue,
+)
+
+__all__ = [
+    "DEFAULT_JSON_SCALAR_NORMALIZER",
+    "JSONOptions",
+    "JSONPath",
+    "JSONPathComparison",
+    "JSONScalarNormalizer",
+    "JSONScalarValue",
+]

pyrsql/core/json/options.py

@@ -0,0 +1,31 @@
+"""ORM-neutral JSON options."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class JSONOptions:
+    """ORM-neutral JSON behavior flags.
+
+    Attributes:
+        path_exists_function: SQL function used for JSON path existence.
+        path_exists_tz_function: SQL function used for timezone-aware JSON path
+            existence checks.
+        use_datetime: Whether JSON values should be interpreted as datetimes
+            when possible.
+    """
+
+    path_exists_function: str = "jsonb_path_exists"
+    path_exists_tz_function: str = "jsonb_path_exists_tz"
+    use_datetime: bool = False
+
+    def __post_init__(self) -> None:
+        """Validates configured SQL function names.
+
+        Raises:
+            ValueError: If either configured SQL function name is empty.
+        """
+        if not self.path_exists_function:
+            raise ValueError("path_exists_function cannot be empty.")
+        if not self.path_exists_tz_function:
+            raise ValueError("path_exists_tz_function cannot be empty.")

pyrsql/core/json/path.py

@@ -0,0 +1,35 @@
+"""Immutable JSON path primitives."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class JSONPath:
+    """Represents an ORM-neutral JSON path.
+
+    Attributes:
+        segments: Ordered path segments from the JSON root to the target.
+    """
+
+    segments: tuple[str, ...] = ()
+    _dot_path: str = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        """Validates path segments.
+
+        Raises:
+            ValueError: If any segment is empty.
+        """
+        for segment in self.segments:
+            if not segment:
+                raise ValueError("JSON path segments cannot be empty.")
+        object.__setattr__(self, "_dot_path", ".".join(self.segments))
+
+    @property
+    def is_root(self) -> bool:
+        """Whether the path targets the root JSON value."""
+        return not self.segments
+
+    def to_dot_path(self) -> str:
+        """The path rendered as a dotted string."""
+        return self._dot_path

pyrsql/core/json/query.py

@@ -0,0 +1,39 @@
+"""ORM-neutral JSON query models."""
+
+from dataclasses import dataclass
+
+from pyrsql.core.json.path import JSONPath
+from pyrsql.core.json.values import (
+    DEFAULT_JSON_SCALAR_NORMALIZER,
+    JSONScalarNormalizer,
+    JSONScalarValue,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class JSONPathComparison:
+    """Represents one JSON path comparison after semantic normalization."""
+
+    path: JSONPath
+    operator_name: str
+    values: tuple[JSONScalarValue, ...]
+
+    @classmethod
+    def from_raw_arguments(
+        cls,
+        *,
+        path: JSONPath,
+        operator_name: str,
+        raw_arguments: tuple[tuple[str, bool], ...],
+        normalizer: JSONScalarNormalizer | None = None,
+    ) -> "JSONPathComparison":
+        """Builds a normalized JSON comparison from raw RSQL arguments."""
+        value_normalizer = normalizer or DEFAULT_JSON_SCALAR_NORMALIZER
+        return cls(
+            path=path,
+            operator_name=operator_name,
+            values=tuple(
+                value_normalizer.normalize(raw_value, quoted=quoted)
+                for raw_value, quoted in raw_arguments
+            ),
+        )

pyrsql/core/json/values.py

@@ -0,0 +1,72 @@
+"""ORM-neutral JSON value normalization."""
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import msgspec
+
+_INTEGER_PATTERN = re.compile(r"^-?\d+$")
+_FLOAT_PATTERN = re.compile(r"^-?\d+\.\d+$")
+
+
+@dataclass(frozen=True, slots=True)
+class JSONScalarValue:
+    """Represents one normalized JSON scalar or structured value."""
+
+    value: Any
+    json_literal: str
+    python_type: type[Any] | None
+
+
+class JSONScalarNormalizer:
+    """Normalizes raw RSQL arguments to JSON-aware values."""
+
+    def normalize(
+        self,
+        raw_value: str,
+        *,
+        quoted: bool,
+    ) -> JSONScalarValue:
+        """Builds one JSON value from a raw RSQL argument."""
+        if quoted:
+            parsed_json = self._try_parse_json(raw_value)
+            if parsed_json is not None:
+                return self._from_python_value(parsed_json)
+            return self._from_python_value(raw_value)
+
+        match raw_value.lower():
+            case "true":
+                return self._from_python_value(True)
+            case "false":
+                return self._from_python_value(False)
+            case "null":
+                return self._from_python_value(None)
+            case _:
+                pass
+        if _INTEGER_PATTERN.fullmatch(raw_value):
+            return self._from_python_value(int(raw_value))
+        if _FLOAT_PATTERN.fullmatch(raw_value):
+            return self._from_python_value(float(raw_value))
+        return self._from_python_value(raw_value)
+
+    def _from_python_value(self, value: Any) -> JSONScalarValue:
+        """Creates a normalized JSON value from a Python object."""
+        return JSONScalarValue(
+            value=value,
+            json_literal=msgspec.json.encode(value).decode("utf-8"),
+            python_type=type(value) if value is not None else None,
+        )
+
+    def _try_parse_json(self, raw_value: str) -> Any | None:
+        """Parses quoted JSON arguments when they contain JSON values."""
+        try:
+            parsed = msgspec.json.decode(raw_value)
+        except msgspec.DecodeError:
+            return None
+        if isinstance(parsed, str):
+            return None
+        return parsed
+
+
+DEFAULT_JSON_SCALAR_NORMALIZER = JSONScalarNormalizer()