lexcql-parser 1.2.0__tar.gz → 1.3.0__tar.gz

{lexcql_parser-1.2.0 → lexcql_parser-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lexcql-parser
-Version: 1.2.0
+Version: 1.3.0
 Summary: LexCQL Query Grammar and Parser
 Keywords: LexCQL,FCS,CQL,Query Parser
 Author: Erik Körner
@@ -141,6 +141,7 @@ assert error.message == "Unknown index 'post'!"
 assert error.fragment == "post = NOUN"
 assert error.position.start == 0
 assert error.position.stop == 11
+assert error.type == "validation-error"
 ```
 
 ## Development

{lexcql_parser-1.2.0 → lexcql_parser-1.3.0}/README.md

@@ -101,6 +101,7 @@ assert error.message == "Unknown index 'post'!"
 assert error.fragment == "post = NOUN"
 assert error.position.start == 0
 assert error.position.stop == 11
+assert error.type == "validation-error"
 ```
 
 ## Development

{lexcql_parser-1.2.0 → lexcql_parser-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lexcql-parser"
-version = "1.2.0"
+version = "1.3.0"
 description = "LexCQL Query Grammar and Parser"
 readme = "README.md"
 license = "MIT"

{lexcql_parser-1.2.0 → lexcql_parser-1.3.0}/src/lexcql/__init__.py

@@ -32,6 +32,18 @@ class ExceptionThrowingErrorListener(ErrorListener):
 
 
 def antlr_parse(input: str) -> LexParser.QueryContext:
+    """Run the low-level ANTLR4 tokenization and parsing. This returns the parsing
+    context ANTLR4 uses instead of the simplified LexCQL query node types.
+
+    Args:
+        input: raw query string
+
+    Returns:
+        LexParser.QueryContext: the ANTLR4 root parsing context (query)
+
+    Throws:
+        SyntaxError: if an error occurred while parsing
+    """
     input_stream = InputStream(input)
     lexer = LexLexer(input_stream)
     stream = CommonTokenStream(lexer)
@@ -78,12 +90,17 @@ def can_parse(input: str):
         return False
 
 
+# ---------------------------------------------------------------------------
+
+
 @overload
 def validate(
     input: str,
     *,
     version: str = DEFAULT_VALIDATOR_SPECIFICATION_VERSION,
     return_errors: Literal[False] = False,
+    case_insensitive: bool = True,
+    warnings_as_errors: bool = False,
 ) -> bool: ...
 
 
@@ -93,6 +110,8 @@ def validate(
     *,
     version: str = DEFAULT_VALIDATOR_SPECIFICATION_VERSION,
     return_errors: Literal[True] = True,
+    case_insensitive: bool = True,
+    warnings_as_errors: bool = False,
 ) -> List[ErrorDetail]: ...
 
 
@@ -101,7 +120,30 @@ def validate(
     *,
     version: str = DEFAULT_VALIDATOR_SPECIFICATION_VERSION,
     return_errors: bool = False,
+    case_insensitive: bool = True,
+    warnings_as_errors: bool = False,
 ):
+    """Validate input query string by trying to parse it and if successful run a LexCQL
+    specification validation. Collect errors/warnings.
+
+    Args:
+        input: the raw query input string
+        version: the specification version to validate against.
+                 Defaults to DEFAULT_VALIDATOR_SPECIFICATION_VERSION ("0.3").
+        return_errors: whether to return simply a boolean if valid or a list of errors.
+                       Defaults to False.
+        case_insensitive: how to handle keywords/indexes in LexCQL. Defaults to True.
+        warnings_as_errors: handle warnings as errors. Defaults to False.
+
+    Raises:
+        ValueError: raised if ``version`` argument specifies an unknown LexCQL specification
+                    or no ``Validator`` can be found for this version.
+
+    Returns:
+        bool: if ``return_errors`` is ``False`` only return a boolean.
+              Returns ``True`` if parsing and validation is without issues, ``False`` otherwise.
+        List[ErrorDetail]: if ``return_errors`` is ``True`` return a list of errors AND warnings.
+    """
     # "check" params
     validator_cls = VALIDATORS.get(version, None)
     if validator_cls is None:
@@ -109,7 +151,12 @@ def validate(
 
     # create parser/validator
     parser = QueryParser(enableSourceLocations=True)
-    validator = validator_cls(query=input, raise_at_first_violation=not return_errors)
+    validator = validator_cls(
+        query=input,
+        case_insensitive=case_insensitive,
+        raise_at_first_violation=not return_errors,
+        warnings_as_errors=warnings_as_errors,
+    )
 
     # try to parse the input query string
     try:
@@ -128,14 +175,15 @@ def validate(
     try:
         validator.validate(qn)
     except SpecificationValidationError:
+        # not will raise if raise_at_first_violation enabled
         return False
 
-    if validator.errors:
-        if not return_errors:
-            return False
-        return list(validator.errors)
+    errors = list()
+    errors.extend(validator.errors)
+    if warnings_as_errors:
+        errors.extend(validator.warnings)
 
-    return [] if return_errors else True
+    return errors if return_errors else not bool(errors)
 
 
 # ---------------------------------------------------------------------------

{lexcql_parser-1.2.0 → lexcql_parser-1.3.0}/src/lexcql/parser.py

@@ -32,7 +32,9 @@ from lexcql.LexParserVisitor import LexParserVisitor
 LOGGER = logging.getLogger(__name__)
 
 _T = TypeVar("_T", bound="QueryNode")
+"""Type of ``QueryNode``."""
 _R = TypeVar("_R")
+"""Result type for ``QueryVisitor``."""
 
 # ---------------------------------------------------------------------------
 
@@ -640,10 +642,17 @@ class Subquery(QueryNode):
 
 @dataclass(frozen=True)
 class ErrorDetail:
+    """Wrapper for error or warnings messages to include the type of issue
+    with optional position and query string fragment."""
+
     message: str
-    type: Optional[Union[Literal["syntax-error", "validation-error"], str]] = None
+    """the error or warning message"""
+    type: Optional[Union[Literal["syntax-error", "validation-error", "validation-warning"], str]] = None
+    """the type of error or warning"""
     position: Optional[Union[int, SourceLocation]] = None
+    """optional position information in the raw query string"""
     fragment: Optional[str] = None
+    """optional query string fragment, may be a substring to quickly locate the issue"""
 
 
 class ErrorListener(antlr4.error.ErrorListener.ErrorListener):

{lexcql_parser-1.2.0 → lexcql_parser-1.3.0}/src/lexcql/validation.py

@@ -4,6 +4,9 @@ from typing import Deque
 from typing import Dict
 from typing import List
 from typing import Optional
+from typing import Set
+from typing import Type
+from typing import TypeVar
 
 from lexcql.parser import ErrorDetail
 from lexcql.parser import Modifier
@@ -11,6 +14,12 @@ from lexcql.parser import QueryNode
 from lexcql.parser import QueryVisitorAdapter
 from lexcql.parser import Relation
 from lexcql.parser import SearchClause
+from lexcql.parser import SearchClauseGroup
+from lexcql.parser import Subquery
+
+# ---------------------------------------------------------------------------
+
+_R = TypeVar("_R")
 
 # ---------------------------------------------------------------------------
 
@@ -25,12 +34,13 @@ class SpecificationValidationError(Exception):
 # TODO: create custom error classes for each error type? or add some type id?
 
 
-class Validator(QueryVisitorAdapter[None], metaclass=ABCMeta):
+class Validator(QueryVisitorAdapter[_R], metaclass=ABCMeta):
     """An abstract base Validator for LexCQL queries.
 
     Subclasses should override the ``visit_`` QueryNode methods to
     implement the validation logic and use the ``.validation_error()``
-    to raise/track validation errors.
+    to raise/track validation errors and ``.validation_warning()`` for
+    warnings (may also raise errors depending on configuration).
     """
 
     def __init__(
@@ -39,6 +49,7 @@ class Validator(QueryVisitorAdapter[None], metaclass=ABCMeta):
         query: Optional[str] = None,
         case_insensitive: bool = True,
         raise_at_first_violation: bool = True,
+        warnings_as_errors: bool = False,
     ):
         """Creates a LexCQL Validator that checks that only known indexes are used
         and that relations and relation modifiers are valid.
@@ -52,9 +63,13 @@ class Validator(QueryVisitorAdapter[None], metaclass=ABCMeta):
                                       conformance validation or try to gather as many infos
                                       as possible. Will be available in ``.errors`` attribute.
                                       Defaults to True.
+            warnings_as_errors: Handle warnings the same as errors. May raise ``SpecificationValidationError``.
         """
         super().__init__()
 
+        self.stack: Deque[QueryNode] = deque()
+        """(internal) Query node stack to keep track of query node parents."""
+
         self.query = query
         """query string to add context to error messages for better error locations"""
 
@@ -63,8 +78,13 @@ class Validator(QueryVisitorAdapter[None], metaclass=ABCMeta):
 
         self.raise_at_first_violation = raise_at_first_violation
         """Whether to raise at first violation."""
+        self.warnings_as_errors = warnings_as_errors
+        """Whether to handle warnings the same as errors."""
         self.errors: List[ErrorDetail] = list()
         """List of specification validation errors if ``.raise_at_first_violation`` is ``False``"""
+        self.warnings: List[ErrorDetail] = list()
+        """List of warnings about not-quite-violations of the specification but bad practice or
+        what can be unexpected results."""
 
     def validate(self, node: QueryNode, *, query: Optional[str] = None):
         """Validate parse query node tree.
@@ -112,12 +132,12 @@ class Validator(QueryVisitorAdapter[None], metaclass=ABCMeta):
         except SpecificationValidationError:
             return False
 
-    def validation_error(self, node: QueryNode, error: str):
-        """(Internal) Raises or tracks a new validation  error.
+    def validation_error(self, node: QueryNode, message: str):
+        """(Internal) Raises or tracks a new validation error.
 
         Args:
             node: the query node where the validation error was caused
-            error: the error message
+            message: the error message
 
         Raises:
             SpecificationValidationError: the raised error if ``.raise_at_first_violation``
@@ -128,22 +148,98 @@ class Validator(QueryVisitorAdapter[None], metaclass=ABCMeta):
             fragment = self.query[node.location.start : node.location.stop]  # noqa: E203
 
         if self.raise_at_first_violation:
-            raise SpecificationValidationError(error, node, fragment)
+            raise SpecificationValidationError(message, node, fragment)
 
         self.errors.append(
             ErrorDetail(
-                message=error,
+                message=message,
                 type="validation-error",
                 position=node.location,
                 fragment=fragment,
             )
         )
 
+    def validation_warning(self, node: QueryNode, message: str):
+        """(Internal) Tracks validation warnings.
+
+        If ``.warnings_as_errors`` is ``True`` and ``.raise_at_first_violation``
+        is ``True``, it will raise ``SpecificationValidationError``.
+
+        Args:
+            node: the query node where the validation error was caused
+            message: the error message
+
+        Raises:
+            SpecificationValidationError: the raised error if ``.raise_at_first_violation``
+                                          and ``.warnings_as_errors`` are set to ``True``
+        """
+        fragment = None
+        if self.query and node.location:
+            fragment = self.query[node.location.start : node.location.stop]  # noqa: E203
+
+        if self.warnings_as_errors:
+            if self.raise_at_first_violation:
+                raise SpecificationValidationError(message, node, fragment)
+
+        self.warnings.append(
+            ErrorDetail(
+                message=message,
+                type="validation-warning",
+                position=node.location,
+                fragment=fragment,
+            )
+        )
+
+    # ----------------------------------------------------
+
+    @property
+    def parent_node(self) -> Optional[QueryNode]:
+        """Get the current parent ``QueryNode`` or ``None`` if unavailable.
+
+        Intended to be used in the ``visit_`` ``QueryNode`` handlers.
+
+        Returns:
+            Optional[QueryNode]: the parent query node or ``None``
+        """
+        if self.stack:
+            return self.stack[-1]
+        return None
+
+    def visit_Subquery(self, node: Subquery) -> _R:
+        self.stack.append(node)
+        result = super().visit_Subquery(node)
+        self.stack.pop()
+        return result
+
+    def visit_SearchClauseGroup(self, node: SearchClauseGroup) -> _R:
+        self.stack.append(node)
+        result = super().visit_SearchClauseGroup(node)
+        self.stack.pop()
+        return result
+
+    def visit_SearchClause(self, node: SearchClause) -> _R:
+        self.stack.append(node)
+        result = super().visit_SearchClause(node)
+        self.stack.pop()
+        return result
+
+    def visit_Relation(self, node: Relation) -> _R:
+        self.stack.append(node)
+        result = super().visit_Relation(node)
+        self.stack.pop()
+        return result
+
+    def visit_Modifier(self, node: Modifier) -> _R:
+        self.stack.append(node)
+        result = super().visit_Modifier(node)
+        self.stack.pop()
+        return result
+
 
 # ---------------------------------------------------------------------------
 
 
-class LexCQLValidatorV0_3(Validator):
+class LexCQLValidatorV0_3(Validator[None]):
     """LexCQL Query Validator for LexCQL Spec v0.3."""
 
     SPECIFICATION_VERSION = "0.3"
@@ -194,14 +290,24 @@ class LexCQLValidatorV0_3(Validator):
         "fullMatch",
     ]
     """List of LexCQL relation modifiers"""
+    MUTUALLY_EXCLUSIVE_MODIFIERS = [
+        # TODO: masked/unmasked/regex ?
+        {"masked", "unmasked"},
+        {"ignoreCase", "respectCase"},
+        {"ignoreAccents", "respectAccents"},
+        {"partialMatch", "fullMatch"},
+    ]
+    """List of mutually exclusive relation modifiers. They should not appear together."""
 
     def __init__(
         self,
         *,
         allowed_indexes: Optional[List[str]] = None,
+        allowed_modifiers: Optional[List[str]] = None,
         query: Optional[str] = None,
         case_insensitive: bool = True,
         raise_at_first_violation: bool = True,
+        warnings_as_errors: bool = False,
     ):
         """Creates a LexCQL v0.3 Validator that checks that only known indexes are used
         and that relations and relation modifiers are valid.
@@ -209,6 +315,8 @@ class LexCQLValidatorV0_3(Validator):
         Args:
             allowed_indexes: Override the default ``KNOWN_INDEXES`` list of LexCQL field names.
                              Defaults to None.
+            allowed_modifiers: Override the default ``KNOWN_MODIFIERS`` list of LexCQL
+                               relation modifiers. Defaults to None.
             query: the original query string used for constructing the query node tree.
                    Used to provide more context for validation errors. Defaults to None.
             case_insensitive: Whether indexes (field names) are check case-insensitively.
@@ -217,27 +325,33 @@ class LexCQLValidatorV0_3(Validator):
                                       conformance validation or try to gather as many infos
                                       as possible. Will be available in ``.errors`` attribute.
                                       Defaults to True.
+            warnings_as_errors: Handle warnings the same as errors. May raise ``SpecificationValidationError``.
         """
 
         super().__init__(
             query=query,
             case_insensitive=case_insensitive,
             raise_at_first_violation=raise_at_first_violation,
+            warnings_as_errors=warnings_as_errors,
         )
 
-        self.stack: Deque[QueryNode] = deque()
-        """(internal) Query node stack to keep track of parents."""
-
         self.allowed_indexes = allowed_indexes
         """User-defined list of known indexes (LexCQL field names)"""
+        self.allowed_modifiers = allowed_modifiers
+        """User-defined list of known modifiers (LexCQL relation modifiers)"""
 
         if self.case_insensitive:
             # NOTE: overrides on instance (not on class level)
             self.KNOWN_INDEXES = list(map(str.lower, self.KNOWN_INDEXES))
+            self.KNOWN_RELATIONS = list(map(str.lower, self.KNOWN_RELATIONS))
             self.KNOWN_MODIFIERS = list(map(str.lower, self.KNOWN_MODIFIERS))
+            self.MUTUALLY_EXCLUSIVE_MODIFIERS = [set(map(str.lower, ms)) for ms in self.MUTUALLY_EXCLUSIVE_MODIFIERS]
 
             if self.allowed_indexes:
                 self.allowed_indexes = list(map(str.lower, self.allowed_indexes))
+            if self.allowed_modifiers:
+                self.allowed_modifiers = list(map(str.lower, self.allowed_modifiers))
+                # TODO: update self.MUTUALLY_EXCLUSIVE_MODIFIERS?
 
     # ----------------------------------------------------
 
@@ -257,29 +371,62 @@ class LexCQLValidatorV0_3(Validator):
 
         # TODO: check `search_term` against relations/modifiers? (regex/masked)
 
-        self.stack.append(node)
+        # warn about single quotes (not working being quotes?)
+        search_term = node.search_term
+        if search_term.startswith("'") and search_term.endswith("'"):
+            self.validation_warning(
+                node,
+                (
+                    f"Search term {search_term!r} is enclosed with single quotes [']."
+                    ' Single quotes are not used quoting, only double qoutes ["]!'
+                    " Endpoint may include the literal single quote when searching."
+                ),
+            )
+
         super().visit_SearchClause(node)
-        self.stack.pop()
 
     def visit_Relation(self, node: Relation):
         #  parent = self.stack[-1]
 
         relation = node.relation
-        if relation is not None:
-            if self.case_insensitive:
-                relation = relation.lower()
-            if relation not in self.KNOWN_RELATIONS:
-                self.validation_error(node, f"Relation '{node.relation}' is unspecified!")
+        if self.case_insensitive:
+            relation = relation.lower()
+        if relation not in self.KNOWN_RELATIONS:
+            self.validation_error(node, f"Relation '{node.relation}' is unspecified!")
 
-            if relation == "is" and node.modifiers:
+        # check modifiers
+        if node.modifiers:
+            if relation == "is":
                 self.validation_error(node, f"Relation '{node.relation}' does not support any modifiers!")
+            # TODO: relation == "==", what modifiers make sense here?
+
+            # check duplicate modifiers (should not be useful in any scenario imaginable)
+            modifier_names: Set[str] = set()
+            for modifier in node.modifiers:
+                modifier_name = modifier.name
+                if self.case_insensitive:
+                    modifier_name = modifier_name.lower()
+                if modifier_name in modifier_names:
+                    self.validation_warning(
+                        node, f"Relation '{node.relation}' has duplicate modifier '{modifier.name}'?"
+                    )
+                modifier_names.add(modifier_name)
+
+            # check modifiers that ignore/respect do not appear together
+            if len(modifier_names) >= 2:
+                for i, excl_set in enumerate(self.MUTUALLY_EXCLUSIVE_MODIFIERS):
+                    intersection = excl_set & modifier_names
+                    if len(intersection) > 1:
+                        self.validation_warning(
+                            node,
+                            (
+                                f"Relation '{node.relation}' uses mutually exclusive modifiers"
+                                f" {sorted(modifier_names)!r} (not allowed together "
+                                f"{sorted(LexCQLValidatorV0_3.MUTUALLY_EXCLUSIVE_MODIFIERS[i])!r})!"
+                            ),
+                        )
 
-            # TODO: check modifiers that ignore/respect do not appear together
-            # TODO: masked/unmasked/regex should not appear together
-
-        self.stack.append(node)
         super().visit_Relation(node)
-        self.stack.pop()
 
     def visit_Modifier(self, node: Modifier):
         #  parent = self.stack[-1]
@@ -287,24 +434,36 @@ class LexCQLValidatorV0_3(Validator):
         name = node.name
         if self.case_insensitive:
             name = name.lower()
-
-        if name not in self.KNOWN_MODIFIERS:
-            self.validation_error(node, f"Modifier '{node.name}' is unspecified!")
+        if self.allowed_modifiers:
+            if name not in self.allowed_modifiers:
+                self.validation_error(
+                    node, f"Unknown modifier '{node.name}' (only allowed: {self.allowed_modifiers!r})!"
+                )
+        else:
+            if name not in self.KNOWN_MODIFIERS:
+                self.validation_error(node, f"Modifier '{node.name}' is unspecified!")
 
         # check against parent? --> visit_Relation "is" check
 
         relation = node.relation
         if relation and name != "lang":
-            self.validation_error(node, f"Modifier '{node.name}' does not support any extra relation!")
+            if self.allowed_modifiers and name in self.allowed_modifiers and name not in self.KNOWN_MODIFIERS:
+                self.validation_warning(node, f"Custom modifier '{node.name}' may not support any extra relation?")
+            else:
+                self.validation_error(node, f"Modifier '{node.name}' does not support any extra relation!")
+
+        if not relation and name == "lang":
+            self.validation_error(node, f"Modifier '{node.name}' requires a relation value, e.g. 'lang=deu'.")
+
+        if relation and relation != "=":
+            self.validation_error(node, f"Modifier '{node.name}' uses unspecified relation: {relation!r}!")
 
-        if relation and name == "lang":
-            # TODO: do a valid language code check
-            pass
+        # TODO: check valid `node.value` for lang modifier?
 
 
 # ---------------------------------------------------------------------------
 
-VALIDATORS: Dict[str, Validator] = {
+VALIDATORS: Dict[str, Type[Validator]] = {
     LexCQLValidatorV0_3.SPECIFICATION_VERSION: LexCQLValidatorV0_3,
 }
 """Mapping of all known LexCQL Validators. Uses the LexCQL specification