Unify CLI with sub-commands (#55)

* set up unified cli

* update platform handling

* update tests

* update docs

Author: geritwagner

docs/source/cli.rst

@@ -10,17 +10,12 @@ To translate a search query on the command line, run
 
 .. code-block:: bash
 
-    search-query-translate --from wos \
-                            --input input_query.txt \
+    search-query translate --input input_query.json \
                             --to pubmed \
-                            --output output_query.txt
+                            --output output_query.json
 
 **Arguments**
 
-- ``--from`` (required):
-  The source query format.
-  Example: ``wos``
-
 - ``--input`` (required):
   Path to the input file containing the original query.
 
@@ -31,22 +26,10 @@ To translate a search query on the command line, run
 - ``--output`` (required):
   Path to the file where the converted query will be written.
 
-
-**Example**
-
-Suppose you have a Web of Science search query saved in ``input_query.txt`` and you want to convert it to a PubMed-compatible format. Run:
-
-.. code-block:: bash
-
-    search-query-translate --from wos \
-                            --input input_query.txt \
-                            --to pubmed \
-                            --output output_query.txt
-
-The converted query will be saved in ``output_query.txt``.
+The format of the ``input_query.json`` is stored in the ``platform`` field of the JSON file.
 
 Linters can be run on the CLI:
 
 .. code-block:: bash
 
-    search-query-lint search-file.json
+    search-query lint search-file.json

pyproject.toml

@@ -47,8 +47,7 @@ dev = [
 ]
 
 [project.scripts]
-search-query-translate = "search_query.cli:translate"
-search-query-lint = "search_query.cli:lint"
+search-query = "search_query.cli:main"
 
 [tool.pylint.MAIN]
 extension-pkg-whitelist = "lxml.etree"

search_query/cli.py

@@ -1,73 +1,125 @@
 #!/usr/bin/env python3
 """CLI for search-query."""
+from __future__ import annotations
+
 import argparse
 import sys
 from pathlib import Path
 
 import search_query.linter
 import search_query.parser
 from search_query import load_search_file
+from search_query.exception import QuerySyntaxError
+
+def _cmd_translate(args: argparse.Namespace) -> int:
+    """Translate a query file from one platform/format to another."""
+
+    print(f"Reading query from {args.input_file}")
+    input_path = Path(args.input_file)
+    if input_path.suffix != ".json":
+        print("Only .json search files are supported at the moment.", file=sys.stderr)
+        return 2
+
+    search_file = load_search_file(args.input_file)
+    try:
+        query = search_query.parser.parse(
+            search_file.search_string,
+            platform=search_file.platform,
+            field_general=search_file.field,
+        )
+    except QuerySyntaxError as e:
+        print(f"Fatal error parsing query.")
+        return 1
+
+    print(f"Converting from {search_file.platform} to {args.target}")
+    try:
+        translated_query = query.translate(args.target)
+    except Exception as e:
+        print(f"Error translating query: {e}")
+        return 1
+
+    converted_query = translated_query.to_string()
+    search_file.search_string = converted_query
+    search_file.platform = args.target
+    
+    print(f"Writing converted query to {args.output_file}")
+    search_file.save(args.output_file)
+    return 0
+
+
+def _lint(args: argparse.Namespace) -> int:
+    """Lint files."""
+    exit_code = 0
+    for file_path in args.files:
+        search_file = load_search_file(file_path)
+        try:
+            result = search_query.linter.lint_file(search_file)
+            if result:
+                exit_code = 1
+        except QuerySyntaxError as e:
+            print(f"Error linting file {file_path}: {e}")
+            exit_code = 1
 
+    return exit_code
 
-def translate() -> None:
-    """Main entrypoint for the query translation CLI"""
 
+def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        description="Convert search queries between formats"
+        prog="search-query",
+        description="Tools for working with search queries (linting, translation, etc.)",
     )
-    parser.add_argument(
-        "--from",
-        dest="source",
-        required=True,
-        help="Source query format (e.g., colrev_web_of_science)",
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>", required=True)
+
+    # translate
+    p_tr = subparsers.add_parser(
+        "translate",
+        help="Convert search queries between formats",
+        description="Convert search queries between formats.",
     )
-    parser.add_argument(
+    p_tr.add_argument(
         "--input",
         dest="input_file",
         required=True,
-        help="Input file containing the query",
+        help="Input .json file containing the query",
     )
-    parser.add_argument(
+    p_tr.add_argument(
         "--to",
         dest="target",
         required=True,
         help="Target query format (e.g., colrev_pubmed)",
     )
-    parser.add_argument(
+    p_tr.add_argument(
         "--output",
         dest="output_file",
         required=True,
-        help="Output file for the converted query",
+        help="Output file path for the converted query",
     )
+    p_tr.set_defaults(func=_cmd_translate)
 
-    args = parser.parse_args()
-
-    # Placeholder: Print what would happen
-    print(f"Converting from {args.source} to {args.target}")
-    print(f"Reading query from {args.input_file}")
-    print(f"Writing converted query to {args.output_file}")
-    print(f"Convert from {args.source} to {args.target}")
-
-    if Path(args.input_file).suffix == ".json":
-        search_file = load_search_file(args.input_file)
-        query = search_query.parser.parse(
-            search_file.search_string,
-            platform=args.source,
-            field_general=search_file.field,
-        )
-
-        translated_query = query.translate(args.target)
-        converted_query = translated_query.to_string()
-        search_file.search_string = converted_query
-        search_file.save(args.output_file)
+    # lint
+    p_li = subparsers.add_parser(
+        "lint",
+        help="Lint query files",
+        description="Lint one or more query files. Intended for standalone use or pre-commit.",
+    )
+    p_li.add_argument(
+        "files",
+        nargs="+",
+        help="File(s) to lint",
+    )
+    p_li.set_defaults(func=_lint)
 
-    else:
-        raise NotImplementedError
+    return parser
 
 
-def lint() -> None:
-    """Main entrypoint for the query linter hook"""
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        return 130
 
-    file_path = sys.argv[1]
 
-    raise SystemExit(search_query.linter.pre_commit_hook(file_path))
+if __name__ == "__main__":
+    raise SystemExit(main())

search_query/linter.py

@@ -20,20 +20,19 @@ def _get_parser(
 ) -> QueryStringParser:
     """Run the linter on the search string"""
 
+    platform = search_query.parser.get_platform(platform)
     parser_class = search_query.parser.PARSERS[platform]
     parser = parser_class(search_string, field_general=field_general)  # type: ignore
 
     try:
         parser.parse()
     except Exception as exc:
-        print(f"Error parsing query: {exc}")
         assert parser.linter.messages  # type: ignore
     return parser
 
 
 def lint_file(search_file: SearchFile) -> dict:
     """Lint a search file and return the messages."""
-    # pylint: disable=too-many-locals
     platform = search_query.parser.get_platform(search_file.platform)
     if platform not in search_query.parser.PARSERS:
         raise ValueError(
@@ -43,7 +42,7 @@ def lint_file(search_file: SearchFile) -> dict:
 
     return lint_query_string(
         search_file.search_string,
-        platform=search_file.platform,
+        platform=platform,
         field_general=search_file.field,
     )
 

test/test_cli.py

@@ -16,8 +16,8 @@ def test_translate_cli() -> None:
 
     result = subprocess.run(
         [
-            "search-query-translate",
-            "--from=wos",
+            "search-query",
+            "translate",
             f"--input={input_file}",
             "--to=ebscohost",
             f"--output={output_file}",
@@ -28,7 +28,7 @@ def test_translate_cli() -> None:
     print(result.stdout)
     print(result.stderr)
     assert result.returncode == 0
-    assert "Converting from wos to ebscohost" in result.stdout
+    assert "Converting from Web of Science to ebscohost" in result.stdout
     assert "Writing converted query to" in result.stdout
     assert output_file.exists()
 
@@ -44,7 +44,7 @@ def test_linter_cli() -> None:
     input_file = test_data_dir / "search_history_file_2_linter.json"
 
     result = subprocess.run(
-        ["search-query-lint", f"{input_file}"],
+        ["search-query", "lint", f"{input_file}"],
         capture_output=True,
         text=True,
     )
@@ -53,7 +53,6 @@ def test_linter_cli() -> None:
     print("STDERR:", result.stderr)
     print("RETURN CODE:", result.returncode)
 
-    assert "Lint: search_history_file_2_linter.json (wos)" in result.stdout
     assert "Unbalanced closing parenthesis" in result.stdout
     assert (
         "The query uses multiple operators with different precedence levels"