pyrsql 0.0.1__py3-none-any.whl

pyrsql/parsing/parser.py

@@ -0,0 +1,292 @@
+"""Recursive-descent parser for pyrsql token streams."""
+
+from pyrsql.parsing.ast import (
+    Argument,
+    ComparisonNode,
+    Expression,
+    LogicalNode,
+    LogicalOperator,
+)
+from pyrsql.parsing.errors import ParseError
+from pyrsql.parsing.lexer import Lexer
+from pyrsql.parsing.limits import ParseLimits
+from pyrsql.parsing.operators import (
+    DEFAULT_OPERATOR_REGISTRY,
+    ComparisonOperator,
+    OperatorRegistry,
+)
+from pyrsql.parsing.source import SourceSpan
+from pyrsql.parsing.tokens import Token, TokenKind
+from pyrsql.selector.ast import Selector
+from pyrsql.selector.parser import DEFAULT_SELECTOR_PARSER, SelectorParseError
+
+
+class Parser:
+    """Parses pyrsql query strings into AST nodes.
+
+    The parser consumes a token stream and builds a syntax tree that later
+    semantic analysis and ORM compilation stages can consume.
+    """
+
+    def __init__(
+        self,
+        source: str,
+        *,
+        limits: ParseLimits | None = None,
+        operator_registry: OperatorRegistry = DEFAULT_OPERATOR_REGISTRY,
+    ) -> None:
+        self._limits = limits or ParseLimits()
+        self._operator_registry = operator_registry
+        self._tokens = Lexer(
+            source,
+            limits=self._limits,
+            operator_spellings=operator_registry.operator_spellings,
+        ).tokenize()
+        self._selector_parser = DEFAULT_SELECTOR_PARSER
+        self._index = 0
+        self._node_count = 0
+
+    def parse(self) -> Expression:
+        """Parses the configured query into an AST.
+
+        Returns:
+            The parsed expression tree.
+        """
+        node = self._parse_or_expression(depth=1)
+        self._expect(TokenKind.EOF, message="Unexpected trailing tokens")
+        return node
+
+    def _parse_or_expression(self, depth: int) -> Expression:
+        """Parses OR-precedence logical expressions."""
+        self._enforce_depth(depth)
+        nodes = [self._parse_and_expression(depth + 1)]
+        while self._match(TokenKind.OR, TokenKind.COMMA):
+            nodes.append(self._parse_and_expression(depth + 1))
+        if len(nodes) == 1:
+            return nodes[0]
+        return self._make_logical_node(LogicalOperator.OR, nodes)
+
+    def _parse_and_expression(self, depth: int) -> Expression:
+        """Parses AND-precedence logical expressions."""
+        self._enforce_depth(depth)
+        nodes = [self._parse_primary_expression(depth + 1)]
+        while self._match(TokenKind.AND, TokenKind.SEMICOLON):
+            nodes.append(self._parse_primary_expression(depth + 1))
+        if len(nodes) == 1:
+            return nodes[0]
+        return self._make_logical_node(LogicalOperator.AND, nodes)
+
+    def _parse_primary_expression(self, depth: int) -> Expression:
+        """Parses grouped or comparison expressions."""
+        self._enforce_depth(depth)
+        if self._current().kind is TokenKind.LPAREN:
+            opening = self._expect(
+                TokenKind.LPAREN,
+                message="Expected '(' to start grouped expression",
+            )
+            expression = self._parse_or_expression(depth + 1)
+            closing = self._expect(
+                TokenKind.RPAREN,
+                message="Expected ')' to close grouped expression",
+            )
+            return expression.with_span(
+                SourceSpan.cover(opening.span, closing.span),
+            )
+        return self._parse_comparison()
+
+    def _parse_comparison(self) -> ComparisonNode:
+        """Parses a comparison expression."""
+        selector = self._expect(
+            TokenKind.UNQUOTED_TEXT,
+            message="Expected a selector before the comparison operator",
+        )
+        try:
+            parsed_selector = self._selector_parser.parse(
+                selector.lexeme,
+                max_length=self._limits.max_selector_length,
+                context="Comparison selector",
+            )
+        except SelectorParseError as error:
+            raise ParseError(message=str(error), span=selector.span) from error
+        operator_token = self._expect(
+            TokenKind.COMPARISON_OPERATOR,
+            message="Expected a comparison operator after the selector",
+        )
+        operator = self._operator_registry.get(operator_token.lexeme)
+        arguments = self._parse_arguments()
+        self._validate_argument_count(operator_token, operator, arguments)
+        return self._make_comparison_node(
+            selector,
+            parsed_selector,
+            operator_token,
+            operator,
+            arguments,
+        )
+
+    def _parse_arguments(self) -> tuple[Argument, ...]:
+        """Parses comparison arguments."""
+        if self._current().kind is TokenKind.LPAREN:
+            return self._parse_argument_list()
+        if self._current().kind in (
+            TokenKind.EOF,
+            TokenKind.RPAREN,
+            TokenKind.AND,
+            TokenKind.OR,
+            TokenKind.SEMICOLON,
+            TokenKind.COMMA,
+        ):
+            return ()
+        argument_token = self._expect_value("Expected a comparison argument")
+        return (self._make_argument(argument_token),)
+
+    def _parse_argument_list(self) -> tuple[Argument, ...]:
+        """Parses a parenthesized argument list."""
+        self._expect(
+            TokenKind.LPAREN,
+            message="Expected '(' to start argument list",
+        )
+        arguments: list[Argument] = []
+        if self._current().kind is TokenKind.RPAREN:
+            self._advance()
+            return ()
+
+        while True:
+            if len(arguments) >= self._limits.max_arguments_per_list:
+                raise ParseError(
+                    message=(
+                        "Argument list exceeds the maximum supported size of "
+                        f"{self._limits.max_arguments_per_list}"
+                    ),
+                    span=self._current().span,
+                )
+            argument_token = self._expect_value(
+                "Expected an argument inside list"
+            )
+            arguments.append(self._make_argument(argument_token))
+            if self._match(TokenKind.COMMA):
+                continue
+            self._expect(
+                TokenKind.RPAREN,
+                message="Expected ')' to close argument list",
+            )
+            return tuple(arguments)
+
+    def _validate_argument_count(
+        self,
+        operator_token: Token,
+        operator: ComparisonOperator,
+        arguments: tuple[Argument, ...],
+    ) -> None:
+        """Validates operator arity."""
+        minimum_arguments = operator.minimum_arguments
+        maximum_arguments = operator.maximum_arguments
+        if len(arguments) < minimum_arguments:
+            raise ParseError(
+                message=(
+                    f"Operator {operator_token.lexeme!r} expects at least "
+                    f"{minimum_arguments} argument(s)"
+                ),
+                span=operator_token.span,
+            )
+        if maximum_arguments is not None and len(arguments) > maximum_arguments:
+            raise ParseError(
+                message=(
+                    f"Operator {operator_token.lexeme!r} expects at most "
+                    f"{maximum_arguments} argument(s)"
+                ),
+                span=operator_token.span,
+            )
+
+    def _make_logical_node(
+        self,
+        operator: LogicalOperator,
+        children: list[Expression],
+    ) -> LogicalNode:
+        """Builds a logical node while tracking parser limits."""
+        self._register_node()
+        return LogicalNode(
+            span=SourceSpan.cover(children[0].span, children[-1].span),
+            operator=operator,
+            children=tuple(children),
+        )
+
+    def _make_comparison_node(
+        self,
+        selector_token: Token,
+        selector: Selector,
+        operator_token: Token,
+        operator: ComparisonOperator,
+        arguments: tuple[Argument, ...],
+    ) -> ComparisonNode:
+        """Builds a comparison node while tracking parser limits."""
+        self._register_node()
+        end_span = arguments[-1].span if arguments else operator_token.span
+        return ComparisonNode(
+            span=SourceSpan.cover(selector_token.span, end_span),
+            selector=selector,
+            operator=operator,
+            arguments=arguments,
+        )
+
+    def _make_argument(self, token: Token) -> Argument:
+        """Builds an argument node from a value token."""
+        return Argument(
+            text=token.lexeme,
+            quoted=token.kind is TokenKind.QUOTED_TEXT,
+            span=token.span,
+        )
+
+    def _expect_value(self, message: str) -> Token:
+        """Consumes the next value token."""
+        current = self._current()
+        if current.kind not in (TokenKind.UNQUOTED_TEXT, TokenKind.QUOTED_TEXT):
+            raise ParseError(message=message, span=current.span)
+        self._advance()
+        return current
+
+    def _expect(self, kind: TokenKind, *, message: str) -> Token:
+        """Consumes the next token if it matches the expected kind."""
+        current = self._current()
+        if current.kind is not kind:
+            raise ParseError(message=message, span=current.span)
+        self._advance()
+        return current
+
+    def _match(self, *kinds: TokenKind) -> bool:
+        """Consumes the current token if it matches one of the kinds."""
+        if self._current().kind in kinds:
+            self._advance()
+            return True
+        return False
+
+    def _register_node(self) -> None:
+        """Tracks AST node creation against parser limits."""
+        self._node_count += 1
+        if self._node_count > self._limits.max_node_count:
+            raise ParseError(
+                message=(
+                    "Query exceeds the maximum supported node count of "
+                    f"{self._limits.max_node_count}"
+                ),
+                span=self._current().span,
+            )
+
+    def _enforce_depth(self, depth: int) -> None:
+        """Enforces the maximum expression depth."""
+        if depth > self._limits.max_expression_depth:
+            raise ParseError(
+                message=(
+                    "Query exceeds the maximum supported expression depth of "
+                    f"{self._limits.max_expression_depth}"
+                ),
+                span=self._current().span,
+            )
+
+    def _current(self) -> Token:
+        """The current token."""
+        return self._tokens[self._index]
+
+    def _advance(self) -> None:
+        """Advances to the next token when possible."""
+        if self._index < len(self._tokens) - 1:
+            self._index += 1

pyrsql/parsing/source.py

@@ -0,0 +1,48 @@
+"""Source location models for parsing."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class SourcePosition:
+    """Represents a single position in the input source."""
+
+    index: int
+    line: int
+    column: int
+
+
+@dataclass(frozen=True, slots=True)
+class SourceSpan:
+    """Represents a half-open span in the input source."""
+
+    start: SourcePosition
+    end: SourcePosition
+
+    @classmethod
+    def cover(cls, start: "SourceSpan", end: "SourceSpan") -> "SourceSpan":
+        """Builds a span that covers two existing spans."""
+        return cls(start=start.start, end=end.end)
+
+
+@dataclass(frozen=True, slots=True)
+class SourceText:
+    """Wraps immutable source text and exposes helper methods."""
+
+    text: str
+    _length: int = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        """Validates the source text."""
+        if not isinstance(self.text, str):
+            raise TypeError("Source text must be a string.")
+        object.__setattr__(self, "_length", len(self.text))
+
+    @property
+    def length(self) -> int:
+        """Returns the source length."""
+        return self._length
+
+    def slice(self, start: int, end: int) -> str:
+        """Returns a substring by raw indices."""
+        return self.text[start:end]

pyrsql/parsing/tokens.py

@@ -0,0 +1,30 @@
+"""Token models for the lexer."""
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+from pyrsql.parsing.source import SourceSpan
+
+
+class TokenKind(Enum):
+    """Token kinds emitted by the lexer."""
+
+    EOF = auto()
+    LPAREN = auto()
+    RPAREN = auto()
+    COMMA = auto()
+    SEMICOLON = auto()
+    AND = auto()
+    OR = auto()
+    COMPARISON_OPERATOR = auto()
+    UNQUOTED_TEXT = auto()
+    QUOTED_TEXT = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Token:
+    """Represents a lexical token."""
+
+    kind: TokenKind
+    lexeme: str
+    span: SourceSpan

pyrsql/selector/__init__.py

@@ -0,0 +1,30 @@
+"""Shared selector primitives for pyrsql."""
+
+from pyrsql.selector.ast import (
+    ColumnSelector,
+    FunctionSelector,
+    LiteralSelector,
+    Selector,
+    SelectorLiteral,
+)
+from pyrsql.selector.parser import SelectorParseError, SelectorParser
+from pyrsql.selector.semantic import (
+    SemanticColumnSelector,
+    SemanticFunctionSelector,
+    SemanticLiteralSelector,
+    SemanticSelector,
+)
+
+__all__ = [
+    "ColumnSelector",
+    "FunctionSelector",
+    "LiteralSelector",
+    "Selector",
+    "SelectorLiteral",
+    "SelectorParseError",
+    "SelectorParser",
+    "SemanticColumnSelector",
+    "SemanticFunctionSelector",
+    "SemanticLiteralSelector",
+    "SemanticSelector",
+]

pyrsql/selector/analyzer.py

@@ -0,0 +1,58 @@
+"""Shared semantic normalization for pyrsql selectors."""
+
+from collections.abc import Callable, Mapping
+
+from pyrsql.selector.ast import (
+    ColumnSelector,
+    FunctionSelector,
+    LiteralSelector,
+    Selector,
+)
+from pyrsql.selector.semantic import (
+    SemanticColumnSelector,
+    SemanticFunctionSelector,
+    SemanticLiteralSelector,
+    SemanticSelector,
+)
+
+
+class SelectorSemanticAnalyzer:
+    """Normalizes parsed selectors into semantic selector nodes."""
+
+    def __init__(self, field_mapping: Mapping[str, str]) -> None:
+        self._field_mapping = field_mapping
+
+    def analyze(
+        self,
+        selector: Selector,
+        *,
+        validate_field: Callable[[str], None],
+        validate_function: Callable[[str], None],
+    ) -> SemanticSelector:
+        """Analyzes one parsed selector recursively."""
+        if isinstance(selector, ColumnSelector):
+            field_path = self._field_mapping.get(
+                selector.selector,
+                selector.selector,
+            )
+            validate_field(field_path)
+            return SemanticColumnSelector(
+                selector=selector.selector,
+                field_path=field_path,
+            )
+        if isinstance(selector, LiteralSelector):
+            return SemanticLiteralSelector(value=selector.value)
+        if not isinstance(selector, FunctionSelector):
+            raise TypeError("Expected FunctionSelector")
+        validate_function(selector.function_name)
+        return SemanticFunctionSelector(
+            function_name=selector.function_name,
+            arguments=tuple(
+                self.analyze(
+                    argument,
+                    validate_field=validate_field,
+                    validate_function=validate_function,
+                )
+                for argument in selector.arguments
+            ),
+        )

pyrsql/selector/ast.py

@@ -0,0 +1,31 @@
+"""AST nodes for shared pyrsql selectors."""
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+SelectorLiteral: TypeAlias = str | int | float | bool | None
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnSelector:
+    """Column-path selector."""
+
+    selector: str
+
+
+@dataclass(frozen=True, slots=True)
+class LiteralSelector:
+    """Static literal selector."""
+
+    value: SelectorLiteral
+
+
+@dataclass(frozen=True, slots=True)
+class FunctionSelector:
+    """Function selector."""
+
+    function_name: str
+    arguments: tuple["Selector", ...]
+
+
+Selector: TypeAlias = ColumnSelector | LiteralSelector | FunctionSelector

pyrsql/selector/parser.py

@@ -0,0 +1,130 @@
+"""Shared recursive parser for pyrsql selectors."""
+
+import re
+
+from pyrsql.selector import ast
+
+
+class SelectorParseError(ValueError):
+    """Raised when a selector expression is malformed."""
+
+
+class SelectorParser:
+    """Parses column, literal, and function selectors."""
+
+    _INTEGER_PATTERN = re.compile(r"-?\d+")
+    _FLOAT_PATTERN = re.compile(r"-?\d+(?:\.\d+)?")
+
+    def parse(
+        self,
+        raw_selector: str,
+        *,
+        max_length: int,
+        context: str,
+    ) -> ast.Selector:
+        """Parses a selector recursively."""
+        if len(raw_selector) > max_length:
+            raise SelectorParseError(
+                f"{context} exceeds the maximum supported length of "
+                f"{max_length}."
+            )
+        if raw_selector.startswith("@"):
+            return self._parse_function_selector(
+                raw_selector,
+                max_length=max_length,
+                context=context,
+            )
+        if raw_selector.startswith("#"):
+            return ast.LiteralSelector(
+                value=self._parse_literal_value(raw_selector[1:])
+            )
+        return ast.ColumnSelector(selector=raw_selector)
+
+    def split_top_level(self, text: str, *, delimiter: str) -> tuple[str, ...]:
+        """Splits text on a delimiter while respecting nested brackets."""
+        parts: list[str] = []
+        start_index = 0
+        depth = 0
+        for index, character in enumerate(text):
+            if character == "[":
+                depth += 1
+            elif character == "]":
+                depth -= 1
+                if depth < 0:
+                    raise SelectorParseError(
+                        f"Selector fragment {text!r} has unbalanced brackets."
+                    )
+            elif character == delimiter and depth == 0:
+                part = text[start_index:index].strip()
+                if part:
+                    parts.append(part)
+                start_index = index + 1
+        if depth != 0:
+            raise SelectorParseError(
+                f"Selector fragment {text!r} has unbalanced brackets."
+            )
+        final_part = text[start_index:].strip()
+        if final_part:
+            parts.append(final_part)
+        return tuple(parts)
+
+    def _parse_function_selector(
+        self,
+        raw_selector: str,
+        *,
+        max_length: int,
+        context: str,
+    ) -> ast.FunctionSelector:
+        """Parses a function selector recursively."""
+        argument_start = raw_selector.find("[")
+        argument_end = raw_selector.rfind("]")
+        if (
+            argument_start <= 1
+            or argument_end <= argument_start
+            or argument_end != len(raw_selector) - 1
+        ):
+            raise SelectorParseError(
+                f"{context} has invalid function selector {raw_selector!r}."
+            )
+        function_name = raw_selector[1:argument_start].strip()
+        if not function_name:
+            raise SelectorParseError(f"{context} has empty function name.")
+        arguments_text = raw_selector[argument_start + 1 : argument_end]
+        argument_fragments = self.split_top_level(arguments_text, delimiter="|")
+        if not argument_fragments:
+            raise SelectorParseError(
+                f"{context} function {function_name!r} must have at least one "
+                "argument."
+            )
+        return ast.FunctionSelector(
+            function_name=function_name,
+            arguments=tuple(
+                self.parse(
+                    fragment,
+                    max_length=max_length,
+                    context=context,
+                )
+                for fragment in argument_fragments
+            ),
+        )
+
+    def _parse_literal_value(self, raw_literal: str) -> ast.SelectorLiteral:
+        """Parses a static literal selector value."""
+        normalized_literal = raw_literal.replace("\t", " ")
+        match normalized_literal.lower():
+            case "null":
+                return None
+            case "true":
+                return True
+            case "false":
+                return False
+            case _:
+                pass
+        if self._INTEGER_PATTERN.fullmatch(normalized_literal):
+            return int(normalized_literal)
+        if self._FLOAT_PATTERN.fullmatch(normalized_literal):
+            return float(normalized_literal)
+        return normalized_literal
+
+
+DEFAULT_SELECTOR_PARSER = SelectorParser()

pyrsql/selector/semantic.py

@@ -0,0 +1,34 @@
+"""Semantic nodes for shared pyrsql selectors."""
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from pyrsql.selector.ast import SelectorLiteral
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticColumnSelector:
+    """Column-path selector after semantic normalization."""
+
+    selector: str
+    field_path: str
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticLiteralSelector:
+    """Static literal selector after semantic normalization."""
+
+    value: SelectorLiteral
+
+
+@dataclass(frozen=True, slots=True)
+class SemanticFunctionSelector:
+    """Function selector after semantic normalization."""
+
+    function_name: str
+    arguments: tuple["SemanticSelector", ...]
+
+
+SemanticSelector: TypeAlias = (
+    SemanticColumnSelector | SemanticLiteralSelector | SemanticFunctionSelector
+)

pyrsql/semantic/__init__.py

@@ -0,0 +1,23 @@
+"""ORM-neutral semantic analysis primitives."""
+
+from pyrsql.semantic.analyzer import SemanticAnalyzer
+from pyrsql.semantic.ast import (
+    SemanticComparison,
+    SemanticExpression,
+    SemanticLogical,
+)
+from pyrsql.semantic.errors import (
+    FieldBlacklistedError,
+    FieldNotWhitelistedError,
+    SemanticError,
+)
+
+__all__ = [
+    "FieldBlacklistedError",
+    "FieldNotWhitelistedError",
+    "SemanticAnalyzer",
+    "SemanticComparison",
+    "SemanticError",
+    "SemanticExpression",
+    "SemanticLogical",
+]