Update docs: illustration of API searches (#31)

* add page

* extend API docs

* revisions

* update index

* update SearchFile

* Update api_search docs

---------

Co-authored-by: Anna Geßler <76491696+annaglr@users.noreply.github.com>

Author: geritwagner

docs/source/api_search/api_search.rst

@@ -0,0 +1,61 @@
+.. _api_search:
+
+API searches
+==========================================================
+
+To run API searches, it is often necessary to represent a query in the form of a URL as opposed to a query string.
+Using the Crossref API as an example, the following illustrates how to construct such a URL to retrieve and store records.
+
+.. code-block:: python
+   :linenos:
+
+   import datetime
+   from pathlib import Path
+   from colrev.packages.crossref.src import crossref_api
+   from colrev.writer.write_utils import write_file
+   
+   from search_query.constants import Fields, Operators
+   from search_query.or_query import OrQuery
+   from search_query.search_file import SearchFile
+   
+   def to_crossref_url(query):
+       """Translate query into a Crossref-compatible URL."""
+       if query.value != Operators.OR:
+           raise ValueError("Crossref serializer only supports OR queries.")
+   
+       query_parts = []
+       for child in query.children:
+           if child.operator:
+               raise ValueError("Nested operators are not supported in Crossref serializer.")
+           if child.search_field.value != Fields.TITLE:
+               raise ValueError(f"Only title field is supported in Crossref serializer ({child.search_field})")
+           query_parts.append(child.value.strip())
+   
+       # Crossref uses '+' for spaces in query values
+       query_string = "+".join(query_parts)
+       return f"https://api.crossref.org/works?query.title={query_string}"
+   
+   if __name__ == "__main__":
+   
+       query = OrQuery(["microsourcing", "lululemon"], search_field="ti")
+   
+       url = to_crossref_url(query)
+       api_crossref = crossref_api.CrossrefAPI(params={"url": url})
+       records = api_crossref.get_records()
+   
+       sf = SearchFile(
+           search_string=query.to_string(),
+           platform="crossref",
+           authors=[{"name": "Tom Brady"}],
+           record_info={"source": "manual", "url": url},
+           date={"data_entry": datetime.datetime.now().strftime("%Y-%m-%d %H:%M")},
+           search_field="title",
+           description="Search for work authored by Tom Brady",
+           tags=["microsourcing", "lululemon", "research"]
+       )
+   
+       sf.save("test/tom_brady_search.json")
+   
+       records_dict = {record.get_value("doi"): record.get_data() for record in records}
+       write_file(records_dict=records_dict, filename=Path("test/crossref_records.bib"))
+

docs/source/index.rst

@@ -246,3 +246,4 @@ References
    :maxdepth: 1
 
    dev_docs/parser
+   api_search/api_search

search_query/__init__.py

@@ -7,9 +7,18 @@
 from search_query.or_query import OrQuery
 from search_query.and_query import AndQuery
 from search_query.near_query import NEARQuery
+from search_query.search_file import SearchFile, load_search_file
 from .__version__ import __version__
 
-__all__ = ["__version__", "Query", "OrQuery", "AndQuery", "NEARQuery"]
+__all__ = [
+    "__version__",
+    "Query",
+    "OrQuery",
+    "AndQuery",
+    "NEARQuery",
+    "SearchFile",
+    "load_search_file",
+]
 
 # Instead of adding elements to __all__,
 # prefixing methods/variables with "__" is preferred.

search_query/linter.py

@@ -35,7 +35,7 @@ def pre_commit_hook() -> int:
     file_path = sys.argv[1]
 
     try:
-        search_file = load_search_file(file_path)
+        search_file = SearchFile(file_path, platform="unknown")
         platform = search_query.parser.get_platform(search_file.platform)
     except Exception as e:  # pylint: disable=broad-except
         print(e)

search_query/search_file.py

@@ -22,7 +22,6 @@ def __init__(
         authors: Optional[list[dict]] = None,
         record_info: Optional[dict] = None,
         date: Optional[dict] = None,
-        search_field: Optional[str] = None,
         filepath: Optional[str | Path] = None,
         **kwargs: dict,
     ) -> None:
@@ -31,7 +30,6 @@ def __init__(
         self.authors = authors or []
         self.record_info = record_info or {}
         self.date = date or {}
-        self.search_field = search_field or ""
         self._filepath = Path(filepath) if filepath else None
 
         for key, value in kwargs.items():