pyrsql 0.0.1__py3-none-any.whl

pyrsql/parsing/ast.py

@@ -0,0 +1,61 @@
+"""AST node definitions for pyrsql parsing."""
+
+import sys
+from dataclasses import dataclass, replace
+from enum import Enum, auto
+
+from pyrsql.parsing.operators import ComparisonOperator
+from pyrsql.parsing.source import SourceSpan
+from pyrsql.selector.ast import Selector
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+@dataclass(frozen=True, slots=True)
+class Argument:
+    """Represents a comparison argument."""
+
+    text: str
+    quoted: bool
+    span: SourceSpan
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """Base AST node."""
+
+    span: SourceSpan
+
+    def with_span(self, span: SourceSpan) -> Self:
+        """Returns a copy of the node with an updated source span."""
+        return replace(self, span=span)
+
+
+@dataclass(frozen=True, slots=True)
+class ComparisonNode(Node):
+    """Leaf node for selector/operator/arguments expressions."""
+
+    selector: Selector
+    operator: ComparisonOperator
+    arguments: tuple[Argument, ...]
+
+
+class LogicalOperator(Enum):
+    """Logical operators supported in the AST."""
+
+    AND = auto()
+    OR = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class LogicalNode(Node):
+    """Logical expression with two or more child nodes."""
+
+    operator: LogicalOperator
+    children: tuple["Expression", ...]
+
+
+Expression = ComparisonNode | LogicalNode

pyrsql/parsing/errors.py

@@ -0,0 +1,25 @@
+"""Parsing error types."""
+
+from dataclasses import dataclass
+
+from pyrsql.parsing.source import SourceSpan
+
+
+@dataclass(frozen=True, slots=True)
+class ParseError(ValueError):
+    """Base exception for parsing failures."""
+
+    message: str
+    span: SourceSpan
+
+    def __str__(self) -> str:
+        """Formats the parse error with source location 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 LexError(ParseError):
+    """Raised when lexing fails."""

pyrsql/parsing/lexer.py

@@ -0,0 +1,264 @@
+"""Single-pass lexer for pyrsql query strings."""
+
+from collections.abc import Mapping
+
+from pyrsql.parsing.errors import LexError
+from pyrsql.parsing.limits import ParseLimits
+from pyrsql.parsing.operators import OPERATOR_SPELLINGS
+from pyrsql.parsing.source import SourcePosition, SourceSpan, SourceText
+from pyrsql.parsing.tokens import Token, TokenKind
+
+
+class Lexer:
+    """Converts raw query text into a token stream."""
+
+    def __init__(
+        self,
+        source: str | SourceText,
+        *,
+        limits: ParseLimits | None = None,
+        operator_spellings: tuple[str, ...] = OPERATOR_SPELLINGS,
+    ) -> None:
+        self._source = (
+            source if isinstance(source, SourceText) else SourceText(source)
+        )
+        self._limits = limits or ParseLimits()
+        self._operator_spellings = operator_spellings
+        self._operator_spellings_by_prefix = self._index_operator_spellings(
+            operator_spellings
+        )
+        self._index = 0
+        self._line = 1
+        self._column = 1
+        self._validate_source_length()
+
+    def tokenize(self) -> tuple[Token, ...]:
+        """Tokenizes the configured source."""
+        tokens: list[Token] = []
+        while not self._is_at_end():
+            self._skip_whitespace()
+            if self._is_at_end():
+                break
+            tokens.append(self._next_token())
+        tokens.append(
+            self._make_token(
+                TokenKind.EOF,
+                "",
+                self._current_position(),
+            )
+        )
+        return tuple(tokens)
+
+    def _next_token(self) -> Token:
+        """Returns the next token from the stream."""
+        if operator := self._match_operator():
+            return operator
+
+        current_char = self._peek()
+        match current_char:
+            case "(":
+                return self._single_char_token(TokenKind.LPAREN)
+            case ")":
+                return self._single_char_token(TokenKind.RPAREN)
+            case ",":
+                return self._single_char_token(TokenKind.COMMA)
+            case ";":
+                return self._single_char_token(TokenKind.SEMICOLON)
+            case "'":
+                return self._consume_quoted_text()
+            case _:
+                return self._consume_unquoted_text()
+
+    def _consume_quoted_text(self) -> Token:
+        """Consumes a single-quoted text token."""
+        start = self._current_position()
+        self._advance()
+        characters: list[str] = []
+        while not self._is_at_end():
+            current_char = self._advance()
+            if current_char == "'":
+                lexeme = "".join(characters)
+                self._enforce_argument_length(lexeme, start)
+                return self._make_token(TokenKind.QUOTED_TEXT, lexeme, start)
+            if current_char == "\\" and not self._is_at_end():
+                escaped_char = self._advance()
+                characters.append(escaped_char)
+                continue
+            characters.append(current_char)
+        raise LexError(
+            message="Unterminated quoted string",
+            span=SourceSpan(start=start, end=self._current_position()),
+        )
+
+    def _consume_unquoted_text(self) -> Token:
+        """Consumes an unquoted text token."""
+        start = self._current_position()
+        start_index = self._index
+        while not self._is_at_end():
+            current_char = self._peek()
+            if current_char.isspace():
+                break
+            if current_char in "(),;":
+                break
+            if self._starts_with_operator():
+                break
+            self._advance()
+
+        lexeme = self._source.slice(start_index, self._index)
+        if not lexeme:
+            raise LexError(
+                message=f"Unexpected character {self._peek()!r}",
+                span=SourceSpan(start=start, end=self._current_position()),
+            )
+
+        match lexeme:
+            case "and":
+                return self._make_token(TokenKind.AND, lexeme, start)
+            case "or":
+                return self._make_token(TokenKind.OR, lexeme, start)
+            case _:
+                pass
+
+        self._enforce_selector_length(lexeme, start)
+        return self._make_token(TokenKind.UNQUOTED_TEXT, lexeme, start)
+
+    def _single_char_token(self, kind: TokenKind) -> Token:
+        """Consumes a fixed-width token."""
+        start = self._current_position()
+        lexeme = self._advance()
+        return self._make_token(kind, lexeme, start)
+
+    def _match_operator(self) -> Token | None:
+        """Consumes a comparison operator when present."""
+        start = self._current_position()
+        for spelling in self._candidate_operator_spellings():
+            if self._source.text.startswith(spelling, self._index):
+                self._advance_operator(spelling)
+                return self._make_token(
+                    TokenKind.COMPARISON_OPERATOR,
+                    spelling,
+                    start,
+                )
+        return None
+
+    def _starts_with_operator(self) -> bool:
+        """Checks whether the current position begins an operator."""
+        for spelling in self._candidate_operator_spellings():
+            if self._source.text.startswith(spelling, self._index):
+                return True
+        return False
+
+    def _candidate_operator_spellings(self) -> tuple[str, ...]:
+        """Returns spellings matching the current prefix character."""
+        current_char = self._peek()
+        return self._operator_spellings_by_prefix.get(
+            current_char,
+            self._operator_spellings,
+        )
+
+    def _index_operator_spellings(
+        self,
+        operator_spellings: tuple[str, ...],
+    ) -> Mapping[str, tuple[str, ...]]:
+        """Indexes operator spellings by their first character."""
+        spellings_by_prefix: dict[str, list[str]] = {}
+        for spelling in operator_spellings:
+            spellings_by_prefix.setdefault(spelling[0], []).append(spelling)
+        return {
+            prefix: tuple(spellings)
+            for prefix, spellings in spellings_by_prefix.items()
+        }
+
+    def _skip_whitespace(self) -> None:
+        """Skips ASCII whitespace characters."""
+        while not self._is_at_end():
+            if not self._peek().isspace():
+                break
+            self._advance()
+
+    def _validate_source_length(self) -> None:
+        """Enforces the global query size limit."""
+        if self._source.length > self._limits.max_query_length:
+            position = SourcePosition(index=0, line=1, column=1)
+            raise LexError(
+                message=(
+                    "Query exceeds the maximum supported length of "
+                    f"{self._limits.max_query_length} characters"
+                ),
+                span=SourceSpan(start=position, end=position),
+            )
+
+    def _enforce_selector_length(
+        self,
+        lexeme: str,
+        position: SourcePosition,
+    ) -> None:
+        """Enforces the unquoted text length limit."""
+        if len(lexeme) > self._limits.max_selector_length:
+            raise LexError(
+                message=(
+                    "Unquoted token exceeds the maximum supported length of "
+                    f"{self._limits.max_selector_length} characters"
+                ),
+                span=SourceSpan(start=position, end=self._current_position()),
+            )
+
+    def _enforce_argument_length(
+        self,
+        lexeme: str,
+        position: SourcePosition,
+    ) -> None:
+        """Enforces the quoted argument length limit."""
+        if len(lexeme) > self._limits.max_argument_length:
+            raise LexError(
+                message=(
+                    "Quoted token exceeds the maximum supported length of "
+                    f"{self._limits.max_argument_length} characters"
+                ),
+                span=SourceSpan(start=position, end=self._current_position()),
+            )
+
+    def _advance(self) -> str:
+        """Consumes the current character and updates source position."""
+        character = self._source.text[self._index]
+        self._index += 1
+        if character == "\n":
+            self._line += 1
+            self._column = 1
+        else:
+            self._column += 1
+        return character
+
+    def _advance_operator(self, operator: str) -> None:
+        """Consumes a comparison operator in one step."""
+        self._index += len(operator)
+        self._column += len(operator)
+
+    def _peek(self) -> str:
+        """Returns the current character without consuming it."""
+        return self._source.text[self._index]
+
+    def _current_position(self) -> SourcePosition:
+        """Returns the current source position."""
+        return SourcePosition(
+            index=self._index,
+            line=self._line,
+            column=self._column,
+        )
+
+    def _make_token(
+        self,
+        kind: TokenKind,
+        lexeme: str,
+        start: SourcePosition,
+    ) -> Token:
+        """Builds a token from a start position and current cursor."""
+        return Token(
+            kind=kind,
+            lexeme=lexeme,
+            span=SourceSpan(start=start, end=self._current_position()),
+        )
+
+    def _is_at_end(self) -> bool:
+        """Checks whether the lexer reached the end of the source."""
+        return self._index >= self._source.length

pyrsql/parsing/limits.py

@@ -0,0 +1,15 @@
+"""Safety limits for lexing and parsing."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ParseLimits:
+    """Configurable safety limits for query processing."""
+
+    max_query_length: int = 4096
+    max_selector_length: int = 256
+    max_argument_length: int = 1024
+    max_arguments_per_list: int = 100
+    max_expression_depth: int = 16
+    max_node_count: int = 1024

pyrsql/parsing/operators.py

@@ -0,0 +1,201 @@
+"""Supported comparison operators."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+
+
+@dataclass(frozen=True, slots=True)
+class ComparisonOperator:
+    """Represents a supported comparison operator."""
+
+    name: str
+    spellings: tuple[str, ...]
+    minimum_arguments: int
+    maximum_arguments: int | None
+
+    def __post_init__(self) -> None:
+        """Validates operator invariants."""
+        if not self.name:
+            raise ValueError("Operator name cannot be empty.")
+        if not self.spellings:
+            raise ValueError("Operator must define at least one spelling.")
+        if self.minimum_arguments < 0:
+            raise ValueError("minimum_arguments cannot be negative.")
+        if (
+            self.maximum_arguments is not None
+            and self.maximum_arguments < self.minimum_arguments
+        ):
+            raise ValueError(
+                "maximum_arguments cannot be less than minimum_arguments."
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class OperatorRegistry:
+    """Immutable registry of supported comparison operators."""
+
+    operators: tuple[ComparisonOperator, ...] = field(default_factory=tuple)
+    operators_by_spelling: Mapping[str, ComparisonOperator] = field(init=False)
+    operator_spellings: tuple[str, ...] = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Builds lookup structures and validates uniqueness."""
+        operators_by_spelling: dict[str, ComparisonOperator] = {}
+        for operator in self.operators:
+            for spelling in operator.spellings:
+                if spelling in operators_by_spelling:
+                    raise ValueError(
+                        f"Duplicate operator spelling registered: {spelling!r}."
+                    )
+                operators_by_spelling[spelling] = operator
+        object.__setattr__(
+            self,
+            "operators_by_spelling",
+            MappingProxyType(operators_by_spelling),
+        )
+        object.__setattr__(
+            self,
+            "operator_spellings",
+            tuple(
+                sorted(
+                    operators_by_spelling,
+                    key=len,
+                    reverse=True,
+                )
+            ),
+        )
+
+    def get(self, spelling: str) -> ComparisonOperator:
+        """Returns the operator registered for the provided spelling."""
+        return self.operators_by_spelling[spelling]
+
+
+EQUAL = ComparisonOperator(
+    name="equal",
+    spellings=("==",),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+NOT_EQUAL = ComparisonOperator(
+    name="not_equal",
+    spellings=("!=",),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+GREATER_THAN = ComparisonOperator(
+    name="greater_than",
+    spellings=("=gt=", ">"),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+GREATER_THAN_OR_EQUAL = ComparisonOperator(
+    name="greater_than_or_equal",
+    spellings=("=ge=", ">="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+LESS_THAN = ComparisonOperator(
+    name="less_than",
+    spellings=("=lt=", "<"),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+LESS_THAN_OR_EQUAL = ComparisonOperator(
+    name="less_than_or_equal",
+    spellings=("=le=", "<="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+IN = ComparisonOperator(
+    name="in",
+    spellings=("=in=",),
+    minimum_arguments=1,
+    maximum_arguments=None,
+)
+NOT_IN = ComparisonOperator(
+    name="not_in",
+    spellings=("=out=",),
+    minimum_arguments=1,
+    maximum_arguments=None,
+)
+IS_NULL = ComparisonOperator(
+    name="is_null",
+    spellings=("=na=", "=isnull=", "=null="),
+    minimum_arguments=0,
+    maximum_arguments=1,
+)
+NOT_NULL = ComparisonOperator(
+    name="not_null",
+    spellings=("=nn=", "=notnull=", "=isnotnull="),
+    minimum_arguments=0,
+    maximum_arguments=1,
+)
+LIKE = ComparisonOperator(
+    name="like",
+    spellings=("=like=", "=ke="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+NOT_LIKE = ComparisonOperator(
+    name="not_like",
+    spellings=("=notlike=", "=nk="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+IGNORE_CASE = ComparisonOperator(
+    name="ignore_case",
+    spellings=("=ic=", "=icase="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+IGNORE_CASE_LIKE = ComparisonOperator(
+    name="ignore_case_like",
+    spellings=("=ilike=", "=ik="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+IGNORE_CASE_NOT_LIKE = ComparisonOperator(
+    name="ignore_case_not_like",
+    spellings=("=inotlike=", "=ni="),
+    minimum_arguments=1,
+    maximum_arguments=1,
+)
+BETWEEN = ComparisonOperator(
+    name="between",
+    spellings=("=bt=", "=between="),
+    minimum_arguments=2,
+    maximum_arguments=2,
+)
+NOT_BETWEEN = ComparisonOperator(
+    name="not_between",
+    spellings=("=nb=", "=notbetween="),
+    minimum_arguments=2,
+    maximum_arguments=2,
+)
+
+SUPPORTED_COMPARISON_OPERATORS = (
+    EQUAL,
+    NOT_EQUAL,
+    GREATER_THAN,
+    GREATER_THAN_OR_EQUAL,
+    LESS_THAN,
+    LESS_THAN_OR_EQUAL,
+    IN,
+    NOT_IN,
+    IS_NULL,
+    NOT_NULL,
+    LIKE,
+    NOT_LIKE,
+    IGNORE_CASE,
+    IGNORE_CASE_LIKE,
+    IGNORE_CASE_NOT_LIKE,
+    BETWEEN,
+    NOT_BETWEEN,
+)
+
+DEFAULT_OPERATOR_REGISTRY = OperatorRegistry(
+    operators=SUPPORTED_COMPARISON_OPERATORS
+)
+OPERATOR_SPELLINGS = DEFAULT_OPERATOR_REGISTRY.operator_spellings
+OPERATORS_BY_SPELLING = DEFAULT_OPERATOR_REGISTRY.operators_by_spelling