pyrsql 0.0.1__py3-none-any.whl

pyrsql/semantic/analyzer.py

@@ -0,0 +1,116 @@
+"""ORM-neutral semantic analysis."""
+
+from pyrsql.core.options import QueryOptions
+from pyrsql.parsing.ast import ComparisonNode, Expression, LogicalNode
+from pyrsql.selector.analyzer import SelectorSemanticAnalyzer
+from pyrsql.selector.ast import Selector
+from pyrsql.selector.semantic import SemanticSelector
+from pyrsql.semantic.ast import (
+    SemanticComparison,
+    SemanticExpression,
+    SemanticLogical,
+)
+from pyrsql.semantic.errors import (
+    FieldBlacklistedError,
+    FieldNotWhitelistedError,
+    FunctionBlacklistedError,
+    FunctionNotWhitelistedError,
+)
+
+
+class SemanticAnalyzer:
+    """Applies orm-neutral semantic rules to parsed expressions."""
+
+    def __init__(self, options: QueryOptions) -> None:
+        self._options = options
+        self._field_whitelist = options.field_whitelist
+        self._field_blacklist = options.field_blacklist
+        self._procedure_policy = options.procedure_policy
+        self._selector_analyzer = SelectorSemanticAnalyzer(
+            options.field_mapping
+        )
+
+    def analyze(self, expression: Expression) -> SemanticExpression:
+        """Analyzes a parsed AST into a semantic expression tree."""
+        if isinstance(expression, ComparisonNode):
+            return self._analyze_comparison(expression)
+        if not isinstance(expression, LogicalNode):
+            raise TypeError("Expected LogicalNode")
+        return SemanticLogical(
+            span=expression.span,
+            operator=expression.operator,
+            children=tuple(
+                self.analyze(child) for child in expression.children
+            ),
+        )
+
+    def _analyze_comparison(
+        self,
+        expression: ComparisonNode,
+    ) -> SemanticComparison:
+        """Analyzes a comparison node."""
+        return SemanticComparison(
+            span=expression.span,
+            selector=self._analyze_selector(
+                expression.selector,
+                expression=expression,
+            ),
+            operator=expression.operator,
+            arguments=expression.arguments,
+        )
+
+    def _analyze_selector(
+        self,
+        selector: Selector,
+        *,
+        expression: ComparisonNode,
+    ) -> SemanticSelector:
+        """Analyzes a parsed selector recursively."""
+        return self._selector_analyzer.analyze(
+            selector,
+            validate_field=lambda field_path: self._enforce_field_access_policy(
+                field_path,
+                expression,
+            ),
+            validate_function=(
+                lambda function_name: self._enforce_function_access_policy(
+                    function_name,
+                    expression=expression,
+                )
+            ),
+        )
+
+    def _enforce_field_access_policy(
+        self,
+        field_path: str,
+        expression: ComparisonNode,
+    ) -> None:
+        """Validates whitelist and blacklist rules."""
+        if self._field_whitelist and field_path not in self._field_whitelist:
+            raise FieldNotWhitelistedError(
+                message=f"Field {field_path!r} is not allowed",
+                span=expression.span,
+            )
+        if field_path in self._field_blacklist:
+            raise FieldBlacklistedError(
+                message=f"Field {field_path!r} is blocked",
+                span=expression.span,
+            )
+
+    def _enforce_function_access_policy(
+        self,
+        function_name: str,
+        *,
+        expression: ComparisonNode,
+    ) -> None:
+        """Validates whitelist and blacklist rules for functions."""
+        if not self._procedure_policy.is_whitelisted(function_name):
+            raise FunctionNotWhitelistedError(
+                message=f"Function {function_name!r} is not whitelisted",
+                span=expression.span,
+            )
+        if self._procedure_policy.is_blacklisted(function_name):
+            raise FunctionBlacklistedError(
+                message=f"Function {function_name!r} is blacklisted",
+                span=expression.span,
+            )

pyrsql/semantic/ast.py

@@ -0,0 +1,35 @@
+"""Semantic expression nodes."""
+
+from dataclasses import dataclass
+
+from pyrsql.parsing.ast import Argument, LogicalOperator
+from pyrsql.parsing.operators import ComparisonOperator
+from pyrsql.parsing.source import SourceSpan
+from pyrsql.selector.semantic import SemanticSelector
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticNode:
+    """Base semantic node."""
+
+    span: SourceSpan
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticComparison(SemanticNode):
+    """Comparison expression after selector normalization."""
+
+    selector: SemanticSelector
+    operator: ComparisonOperator
+    arguments: tuple[Argument, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticLogical(SemanticNode):
+    """Logical semantic node."""
+
+    operator: LogicalOperator
+    children: tuple["SemanticExpression", ...]
+
+
+SemanticExpression = SemanticComparison | SemanticLogical

pyrsql/semantic/errors.py

@@ -0,0 +1,40 @@
+"""Semantic analysis exceptions."""
+
+from dataclasses import dataclass
+
+from pyrsql.parsing.source import SourceSpan
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticError(ValueError):
+    """Base exception for semantic analysis failures."""
+
+    message: str
+    span: SourceSpan
+
+    def __str__(self) -> str:
+        """Formats semantic errors with source position data."""
+        return (
+            f"{self.message} at index {self.span.start.index} "
+            f"(line {self.span.start.line}, column {self.span.start.column})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class FieldNotWhitelistedError(SemanticError):
+    """Raised when a selector is not allowed by the whitelist."""
+
+
+@dataclass(frozen=True, slots=True)
+class FieldBlacklistedError(SemanticError):
+    """Raised when a selector is blocked by the blacklist."""
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionNotWhitelistedError(SemanticError):
+    """Raised when a function selector is not allowed by the whitelist."""
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionBlacklistedError(SemanticError):
+    """Raised when a function selector is blocked by the blacklist."""

pyrsql/sorting/__init__.py

@@ -0,0 +1,26 @@
+"""Sorting primitives for pyrsql."""
+
+from pyrsql.sorting.ast import SortDirection, SortField
+from pyrsql.sorting.errors import (
+    SortFieldBlacklistedError,
+    SortFieldNotWhitelistedError,
+    SortFunctionBlacklistedError,
+    SortFunctionNotWhitelistedError,
+    SortParseError,
+)
+from pyrsql.sorting.limits import SortLimits
+from pyrsql.sorting.parser import SortParser
+from pyrsql.sorting.semantic import SemanticSortField
+
+__all__ = [
+    "SemanticSortField",
+    "SortDirection",
+    "SortField",
+    "SortFieldBlacklistedError",
+    "SortFieldNotWhitelistedError",
+    "SortFunctionBlacklistedError",
+    "SortFunctionNotWhitelistedError",
+    "SortLimits",
+    "SortParseError",
+    "SortParser",
+]

pyrsql/sorting/analyzer.py

@@ -0,0 +1,74 @@
+"""Semantic analysis for sort expressions."""
+
+from pyrsql.core.options import SortOptions
+from pyrsql.selector.analyzer import SelectorSemanticAnalyzer
+from pyrsql.selector.ast import Selector
+from pyrsql.selector.semantic import SemanticSelector
+from pyrsql.sorting.ast import SortField
+from pyrsql.sorting.errors import (
+    SortFieldBlacklistedError,
+    SortFieldNotWhitelistedError,
+    SortFunctionBlacklistedError,
+    SortFunctionNotWhitelistedError,
+)
+from pyrsql.sorting.semantic import SemanticSortField
+
+
+class SortAnalyzer:
+    """Applies selector mapping and access rules to parsed sort fields."""
+
+    def __init__(self, options: SortOptions) -> None:
+        self._field_whitelist = options.field_whitelist
+        self._field_blacklist = options.field_blacklist
+        self._procedure_policy = options.procedure_policy
+        self._selector_analyzer = SelectorSemanticAnalyzer(
+            options.field_mapping
+        )
+
+    def analyze(
+        self,
+        fields: tuple[SortField, ...],
+    ) -> tuple[SemanticSortField, ...]:
+        """Analyzes parsed sort fields into semantic sort fields."""
+        return tuple(self._analyze_field(field) for field in fields)
+
+    def _analyze_field(self, field: SortField) -> SemanticSortField:
+        """Analyzes a single parsed sort field."""
+        return SemanticSortField(
+            selector=self._analyze_selector(field.selector),
+            direction=field.direction,
+            ignore_case=field.ignore_case,
+        )
+
+    def _analyze_selector(
+        self,
+        selector: Selector,
+    ) -> SemanticSelector:
+        """Analyzes a parsed selector recursively."""
+        return self._selector_analyzer.analyze(
+            selector,
+            validate_field=self._validate_field_access,
+            validate_function=self._validate_function_access,
+        )
+
+    def _validate_field_access(self, field_path: str) -> None:
+        """Validates whitelist and blacklist rules for a sort field."""
+        if self._field_whitelist and field_path not in self._field_whitelist:
+            raise SortFieldNotWhitelistedError(
+                f"Field {field_path!r} is not allowed by the whitelist."
+            )
+        if field_path in self._field_blacklist:
+            raise SortFieldBlacklistedError(
+                f"Field {field_path!r} is blocked by the blacklist."
+            )
+
+    def _validate_function_access(self, function_name: str) -> None:
+        """Validates whitelist and blacklist rules for a sort function."""
+        if not self._procedure_policy.is_whitelisted(function_name):
+            raise SortFunctionNotWhitelistedError(
+                f"Function {function_name!r} is not whitelisted."
+            )
+        if self._procedure_policy.is_blacklisted(function_name):
+            raise SortFunctionBlacklistedError(
+                f"Function {function_name!r} is blacklisted."
+            )

pyrsql/sorting/ast.py

@@ -0,0 +1,46 @@
+"""AST nodes for pyrsql sort expressions."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+from pyrsql.selector.ast import Selector
+
+
+class SortDirection(Enum):
+    """Supported sort directions."""
+
+    ASCENDING = "asc"
+    DESCENDING = "desc"
+
+    @classmethod
+    def from_raw(cls, raw_direction: str) -> "SortDirection | None":
+        """Matches a raw token to a supported sort direction.
+
+        Args:
+            raw_direction: Raw direction token from the sort expression.
+
+        Returns:
+            The matching direction, or None when the token is unsupported.
+        """
+        match raw_direction.lower():
+            case "asc":
+                return cls.ASCENDING
+            case "desc":
+                return cls.DESCENDING
+            case _:
+                return None
+
+
+@dataclass(frozen=True, slots=True)
+class SortField:
+    """Single parsed sort field.
+
+    Attributes:
+        selector: Selector to sort by.
+        direction: Sort direction to apply.
+        ignore_case: Whether case should be ignored when sorting.
+    """
+
+    selector: Selector
+    direction: SortDirection
+    ignore_case: bool

pyrsql/sorting/errors.py

@@ -0,0 +1,21 @@
+"""Errors raised while parsing or analyzing sort expressions."""
+
+
+class SortParseError(ValueError):
+    """Raised when a sort expression is malformed."""
+
+
+class SortFieldNotWhitelistedError(ValueError):
+    """Raised when a sort selector is not allowed by the whitelist."""
+
+
+class SortFieldBlacklistedError(ValueError):
+    """Raised when a sort selector is blocked by the blacklist."""
+
+
+class SortFunctionNotWhitelistedError(ValueError):
+    """Raised when a sort function is not allowed by the whitelist."""
+
+
+class SortFunctionBlacklistedError(ValueError):
+    """Raised when a sort function is blocked by the blacklist."""

pyrsql/sorting/limits.py

@@ -0,0 +1,15 @@
+"""Security and complexity limits for sort parsing."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class SortLimits:
+    """Configurable limits for sort parsing."""
+
+    max_sort_length: int = 4096
+    max_fields: int = 32
+    max_field_path_length: int = 256
+
+
+DEFAULT_SORT_LIMITS = SortLimits()

pyrsql/sorting/parser.py

@@ -0,0 +1,150 @@
+"""Parser for pyrsql sort expressions."""
+
+from typing import Final
+
+from pyrsql.selector.ast import Selector
+from pyrsql.selector.parser import DEFAULT_SELECTOR_PARSER, SelectorParseError
+from pyrsql.sorting.ast import SortDirection, SortField
+from pyrsql.sorting.errors import SortParseError
+from pyrsql.sorting.limits import DEFAULT_SORT_LIMITS, SortLimits
+
+_EMPTY_FIELDS: Final[tuple[SortField, ...]] = ()
+
+
+class SortParser:
+    """Parses sort expressions into orm-neutral field descriptors."""
+
+    def __init__(
+        self,
+        source: str | None,
+        *,
+        limits: SortLimits | None = None,
+    ) -> None:
+        self._source = (source or "").strip()
+        self._limits = limits or DEFAULT_SORT_LIMITS
+        self._selector_parser = DEFAULT_SELECTOR_PARSER
+
+    def parse(self) -> tuple[SortField, ...]:
+        """Parses the configured sort expression."""
+        if not self._source:
+            return _EMPTY_FIELDS
+
+        max_sort_length = self._limits.max_sort_length
+        max_fields = self._limits.max_fields
+        if len(self._source) > max_sort_length:
+            raise SortParseError(
+                "Sort expression exceeds the maximum supported length of "
+                f"{max_sort_length}."
+            )
+
+        fields: list[SortField] = []
+        for clause_index, clause in enumerate(self._source.split(";"), start=1):
+            parsed_field = self._parse_clause(clause, clause_index=clause_index)
+            if parsed_field is None:
+                continue
+            fields.append(parsed_field)
+            if len(fields) > max_fields:
+                raise SortParseError(
+                    "Sort expression exceeds the maximum supported field "
+                    f"count of {max_fields}."
+                )
+        return tuple(fields)
+
+    def _parse_clause(
+        self,
+        clause: str,
+        *,
+        clause_index: int,
+    ) -> SortField | None:
+        """Parses a single semicolon-delimited sort clause."""
+        try:
+            parts = list(
+                self._selector_parser.split_top_level(
+                    clause,
+                    delimiter=",",
+                )
+            )
+        except SelectorParseError as error:
+            raise SortParseError(str(error)) from error
+        if not parts:
+            return None
+        if len(parts) > 3:
+            raise SortParseError(
+                "Sort clause "
+                f"#{clause_index} {clause!r} has too many comma-separated "
+                "parts."
+            )
+
+        selector = self._parse_selector(parts[0], clause_index=clause_index)
+
+        direction = SortDirection.ASCENDING
+        if len(parts) > 1:
+            direction = self._parse_direction(
+                parts[1],
+                clause,
+                clause_index=clause_index,
+            )
+
+        ignore_case = False
+        if len(parts) > 2:
+            ignore_case = self._parse_ignore_case(
+                parts[2],
+                clause,
+                clause_index=clause_index,
+            )
+
+        return SortField(
+            selector=selector,
+            direction=direction,
+            ignore_case=ignore_case,
+        )
+
+    def _parse_direction(
+        self,
+        raw_direction: str,
+        clause: str,
+        *,
+        clause_index: int,
+    ) -> SortDirection:
+        """Parses the direction token for a sort clause."""
+        direction = SortDirection.from_raw(raw_direction)
+        if direction is not None:
+            return direction
+        raise SortParseError(
+            f"Sort clause #{clause_index} {clause!r} has unsupported direction "
+            f"{raw_direction!r}."
+        )
+
+    def _parse_ignore_case(
+        self,
+        raw_flag: str,
+        clause: str,
+        *,
+        clause_index: int,
+    ) -> bool:
+        """Parses the ignore-case modifier for a sort clause."""
+        match raw_flag.lower():
+            case "ic":
+                return True
+            case _:
+                raise SortParseError(
+                    f"Sort clause #{clause_index} {clause!r} has unsupported "
+                    "modifier "
+                    f"{raw_flag!r}."
+                )
+
+    def _parse_selector(
+        self,
+        raw_selector: str,
+        *,
+        clause_index: int,
+    ) -> Selector:
+        """Parses a sort selector recursively."""
+        try:
+            return self._selector_parser.parse(
+                raw_selector,
+                max_length=self._limits.max_field_path_length,
+                context=f"Sort selector in clause #{clause_index}",
+            )
+        except SelectorParseError as error:
+            raise SortParseError(str(error)) from error

pyrsql/sorting/semantic.py

@@ -0,0 +1,15 @@
+"""Semantic sort nodes."""
+
+from dataclasses import dataclass
+
+from pyrsql.selector.semantic import SemanticSelector
+from pyrsql.sorting.ast import SortDirection
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticSortField:
+    """Single sort field after selector normalization."""
+
+    selector: SemanticSelector
+    direction: SortDirection
+    ignore_case: bool

pyrsql-0.0.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: pyrsql
+Version: 0.0.1
+Summary: ORM-oriented RSQL support for Python applications.
+Keywords: rsql,orm,sqlalchemy,fastapi,query-language,rest
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Database
+Requires-Dist: ciso8601>=2.3,<3.0
+Requires-Dist: msgspec>=0.18,<1.0
+Requires-Dist: typing-extensions>=4.10.0 ; python_full_version < '3.11'
+Requires-Dist: fastapi>=0.110,<1.0 ; extra == 'fastapi'
+Requires-Dist: sqlalchemy>=2.0,<3.0 ; extra == 'sqlalchemy'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/wskr00/pyrsql
+Project-URL: Repository, https://github.com/wskr00/pyrsql
+Project-URL: Issues, https://github.com/wskr00/pyrsql/issues
+Project-URL: Documentation, https://github.com/wskr00/pyrsql/blob/main/README.md
+Provides-Extra: fastapi
+Provides-Extra: sqlalchemy
+Description-Content-Type: text/markdown
+
+## pyrsql
+
+`pyrsql` is an ORM-oriented RSQL library for Python.
+
+The project is being designed to support multiple ORMs, starting with
+`SQLAlchemy 2.0`. The core package remains ORM-neutral, while ORM
+implementations live in `orms`, and framework-specific integration lives
+in `adapters`.
+
+Current `SQLAlchemy` support includes:
+
+- filters
+- sorting
+- pagination
+- `distinct`
+- `join_hints`
+- PostgreSQL-style JSON / JSONB path support
+- temporal JSON path semantics via `JSONOptions(use_datetime=True)`
+
+Current adapter support includes:
+
+- `FastAPI` request extraction via dependencies
+- configurable `filter`, `sort`, `page`, and `size` parameters
+- class-based and factory-based FastAPI dependencies
+- `HTTP 422` translation for pyrsql parse and semantic failures
+
+## Development Principles
+
+- Object-oriented design
+- SOLID principles
+- Google Python Style Guide
+- Strong typing
+- ORM-neutral public API
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Usage](docs/usage.md)
+- [Reference](docs/reference.md)
+- [FastAPI Adapter Usage](docs/usage.md#fastapi-adapter)
+- [Google Python Style Guide](docs/pyguide.md)
+- [Quality and Tooling](docs/quality.md)
+- [Testing](docs/testing.md)