Constructor query validation (#36)

* validate queries in constructor call

* updates

* update

* add_linter_messages: position+S

* search-term/operator restrictions

* update linters

* update

* update docs

* resolve comments

* rename: origin_platform > platform

* update platform handling

* activate ebsco validation

* update constant useage

* refactor wos: handle_year_search

* update docs

* pre-compile regex

* update database

* refactor/generalize checks

Author: geritwagner

.gitignore

@@ -5,3 +5,4 @@ docs/build
 search_query/ebsco/__pycache__/*
 search_query/pubmed/__pycache__/*
 search_query/wos/__pycache__/*
+search_query/generic/__pycache__/*

docs/source/dev_docs/linter_development.rst

@@ -13,7 +13,8 @@ Use the appropriate base class when developing a new linter:
 - `QueryStringLinter`: for single query strings
 - `QueryListLinter`: for list-based query formats
 
-Each linter must override the `validate_tokens()` method and optionally `validate_query_tree()` for deeper semantic checks.
+Each linter must override the `validate_tokens()` method and the `validate_query_tree()`.
+`validate_tokens()` is called when the query is parsed, and `validate_query_tree()` is called when the query tree is built (i.e., at the end of the parsing process **and** when the query is constructed programmatically).
 
 Best Practices
 --------------

docs/source/dev_docs/linter_skeleton.py

@@ -1,7 +1,12 @@
+import typing
+
 from search_query.constants import QueryErrorCode
 from search_query.constants import TokenTypes
 from search_query.linter_base import QueryStringLinter
 
+if typing.TYPE_CHECKING:
+    from search_query.query import Query
+
 
 class XYQueryStringLinter(QueryStringLinter):
     """Linter for XY query strings"""
@@ -19,26 +24,27 @@ class XYQueryStringLinter(QueryStringLinter):
         # ...
     }
 
-    def validate_tokens(self) -> None:
+    def validate_tokens(
+        self,
+        *,
+        tokens: typing.List[Token],
+        query_str: str,
+        search_field_general: str = "",
+    ) -> typing.List[Token]:
         """Main validation routine"""
+
+        self.tokens = tokens
+        self.query_str = query_str
+        self.search_field_general = search_field_general
+
         self.check_unbalanced_parentheses()
         self.check_unknown_token_types()
         self.check_invalid_token_sequences()
         self.check_operator_capitalization()
-        self.check_invalid_characters_in_search_term("@&%$^~\\<>{}()[]#")
 
         # custom validation
-        self.check_unsupported_search_fields()
-        self.check_field_positioning()
 
-    def check_unsupported_search_fields(self) -> None:
-        for token in self.parser.tokens:
-            if token.type == TokenTypes.FIELD and token.value not in VALID_FIELDS:
-                self.add_linter_message(
-                    QueryErrorCode.SEARCH_FIELD_UNSUPPORTED,
-                    position=token.position,
-                    details=f"Field {token.value} is not supported",
-                )
+        return self.tokens
 
     def check_invalid_token_sequences(self) -> None:
         for i, token in enumerate(self.parser.tokens[:-1]):
@@ -49,3 +55,15 @@ def check_invalid_token_sequences(self) -> None:
                     position=self.parser.tokens[i + 1].position,
                     details=f"Unexpected token after {token.type}",
                 )
+
+    def validate_query_tree(self, query: Query) -> None:
+        """
+        Validate the query tree.
+        This method is called after the query tree has been built.
+        """
+
+        self.check_quoted_search_terms_query(query)
+        self.check_operator_capitalization_query(query)
+        self.check_invalid_characters_in_search_term_query(query, "@&%$^~\\<>{}()[]#")
+        self.check_unsupported_search_fields_in_query(query)
+        # term_field_query = self.get_query_with_fields_at_terms(query)

docs/source/dev_docs/tests.rst

@@ -124,5 +124,5 @@ Test Types
 
 .. note::
 
-   - Use helper functions like `print_debug_tokens()` to ease debugging.
+   - Use helper functions like `parser.print_tokens()` to ease debugging.
    - Use `assert ... == ...` with fallbacks for `print(...)` for inspection.

docs/source/index.rst

@@ -47,9 +47,9 @@ Creating a query programmatically is simple:
     from search_query import OrQuery, AndQuery
 
     # Typical building-blocks approach
-    digital_synonyms = OrQuery(["digital", "virtual", "online"], search_field="Abstract")
-    work_synonyms = OrQuery(["work", "labor", "service"], search_field="Abstract")
-    query = AndQuery([digital_synonyms, work_synonyms], search_field="Author Keywords")
+    digital_synonyms = OrQuery(["digital", "virtual", "online"], search_field="ab")
+    work_synonyms = OrQuery(["work", "labor", "service"], search_field="ab")
+    query = AndQuery([digital_synonyms, work_synonyms])
 
 ..
     Parameters:

docs/source/lint/F1011.rst

@@ -0,0 +1,14 @@
+.. _F1011:
+
+F1011 — too-many-operators
+==========================
+
+**Error Code**: F1011
+
+**Message**: ``Too many operators in the query``
+
+**Scope**: PLATFORM.WOS
+
+**Description**: Too many operators in the query
+
+**Back to**: :ref:`lint`

docs/source/lint/F1012.rst

@@ -0,0 +1,14 @@
+.. _F1012:
+
+F1012 — too-many-search-terms
+=============================
+
+**Error Code**: F1012
+
+**Message**: ``Too many search terms in the query``
+
+**Scope**: PLATFORM.WOS
+
+**Description**: Too many search terms in the query
+
+**Back to**: :ref:`lint`

docs/source/lint/F2012.rst

@@ -1,6 +1,6 @@
 .. _F2012:
 
-F2012 — year-without-search-field
+F2012 — year-without-search-terms
 =================================
 
 **Error Code**: F2012

docs/source/lint/F2014.rst

@@ -0,0 +1,14 @@
+.. _F2014:
+
+F2014 — year-format-invalid
+===========================
+
+**Error Code**: F2014
+
+**Message**: ``Invalid year format.``
+
+**Scope**: PLATFORM.WOS
+
+**Description**: Invalid year format.
+
+**Back to**: :ref:`lint`

docs/source/lint/W0013.rst

@@ -0,0 +1,14 @@
+.. _W0013:
+
+W0013 — non-standard-quotes
+===========================
+
+**Error Code**: W0013
+
+**Message**: ``Non-standard quotes``
+
+**Scope**: all
+
+**Description**: Non-standard quotes
+
+**Back to**: :ref:`lint`