Requested changes

Author: nils-herrmann

docs/reference/sciencedirect/ScienceDirectSearch.rst

@@ -2,7 +2,7 @@ pybliometrics.sciencedirect.ScienceDirectSearch
 ===============================================
 
 `ScienceDirectSearch()` implements the `ScienceDirect Search API <https://nonprod-devportal.elsevier.com/documentation/ScienceDirectSearchAPI.wadl>`_ using the `PUT` method.  It executes a query to search for documents and retrieves the resulting records.
-The class takes a `query` dictionary as input which has to follow this schema:
+The class takes a `query` string that searches through all the article's or chapter's content. You can also pass any of the following parameters as keyword arguments:
 
 .. code-block:: text
 
@@ -44,16 +44,15 @@ Examples
 --------
 
 The class is initialized with a search query.
-We can pass the field `qs`` to search for specific keywords.
+We can pass `date` as keyword argument to search for documents published in a specific date.
 Using `verbose=True` will print the progress of the download.
 
 .. code-block:: python
 
     >>> from pybliometrics.sciencedirect import ScienceDirectSearch, init
     >>> init()
-    >>> # Retrieve documents based on the search query  
-    >>> query = query = {'qs': '"neural radiance fields" AND "3D rendering"', 'date': '2024'}
-    >>> sds = ScienceDirectSearch(query, verbose=True)
+    >>> # Retrieve documents based on the search query and date
+    >>> sds = ScienceDirectSearch('"neural radiance fields" AND "3D rendering"', date='2024', verbose=True)
     Downloading results for query "{'qs': '"neural radiance fields" AND "3D rendering"', 'date': '2024', 'display': {'offset': 0, 'show': 100, 'sortBy': 'date'}, 'cursor': '*'}":
     100%|██████████| 1/1 [00:00<00:00,  3.23it/s]
 

pybliometrics/sciencedirect/sciencedirect_search.py

@@ -65,21 +65,21 @@ def results(self) -> Optional[list]:
         return out or None
 
     def __init__(self,
-                 query: dict,
+                 query: str = '',
                  refresh: Union[bool, int] = False,
                  view: Optional[str] = None,
                  verbose: bool = False,
                  download: bool = True,
                  integrity_fields: Optional[Union[list[str], tuple[str, ...]]] = None,
                  integrity_action: str = "raise",
                  subscriber: bool = True,
+                 **kwds: str
                  ) -> None:
         """
         Parameters
         ----------
-        query : dict
-            The query to be sent to the API, e.g.,
-            {'qs': '"Neural Networks" AND "Shapley"', 'date': '2019-2020'}
+        query : str
+            The query to be sent to the API, e.g. '"Neural Networks" AND "Shapley"'
 
         refresh : bool or int, optional
             Whether to refresh the cached file. If an int is passed, the cache
@@ -107,6 +107,12 @@ def __init__(self,
         subscriber : bool, optional
             If True, cursor navigation is enabled, allowing more than 5,000 results.
         
+        **kwds: str
+            Additional keyword arguments to be passed to the API. These can be any available
+            search fields, such as `authors`, `pub-date` and `title`. For a full list of
+            available fields, see the `ScienceDirect Search API Migration Documentation
+            <https://dev.elsevier.com/tecdoc_sdsearch_migration.html>`__.
+        
         Raises
         ------
         ScopusQueryError
@@ -117,8 +123,13 @@ def __init__(self,
             is not one of the allowed values.
 
         """
+        # Check if the query and keyword arguments are empty
+        if not (query or kwds):
+            msg = "The query is empty. Please provide either a query string or keyword arguments."
+            raise ValueError(msg)
+
         if view:
-            check_parameter_value(view, VIEWS['ScienceDirectSearch'], "view")
+            check_parameter_value(view, VIEWS["ScienceDirectSearch"], "view")
         else:
             view = "STANDARD"
 
@@ -133,7 +144,7 @@ def __init__(self,
 
         Search.__init__(self, query=query,
                         cursor=subscriber, download=download,
-                        verbose=verbose)
+                        verbose=verbose, **kwds)
 
     def __str__(self):
         """Print a summary string."""

pybliometrics/sciencedirect/tests/test_ScienceDirectSearch.py

@@ -8,18 +8,21 @@
 
 init()
 
-one_article_query = {'title': 'Assessing LLMs in malicious code deobfuscation of real-world malware campaigns',
-                     'date': '2024'}
-sds_standard = ScienceDirectSearch(one_article_query, refresh=30)
+sds_standard = ScienceDirectSearch(title='Assessing LLMs in malicious code deobfuscation of real-world malware campaigns',
+                                   date='2024',
+                                   refresh=30)
 
-empty_query = {'title': 'Not a realistic title', 'date': '2012'}
-sds_empty = ScienceDirectSearch(empty_query, view="STANDARD", refresh=30)
+sds_empty = ScienceDirectSearch(title='Not a realistic title',
+                                date='2012',
+                                view="STANDARD", refresh=30)
 
-huge_query = {'qs': 'Neural Networks', 'date': '2015-2020'}
-sds_huge = ScienceDirectSearch(huge_query, view="STANDARD", download=False, refresh=30)
+sds_huge = ScienceDirectSearch('Neural Networks',
+                               date='2015-2020',
+                               view="STANDARD", download=False, refresh=30)
 
-pagination_query = {'qs': '"Neural Networks" AND "Shapley"', 'date': '2020'}
-sds_pagination = ScienceDirectSearch(pagination_query, view="STANDARD", refresh=30)
+sds_pagination = ScienceDirectSearch('"Neural Networks" AND "Shapley"',
+                                     date='2020',
+                                     view="STANDARD", refresh=30)
 
 def test_all_fields():
     fields = 'authors doi loadDate openAccess first_page last_page pii publicationDate ' \
@@ -66,18 +69,19 @@ def test_empty_results():
 
 
 def test_field_consistency():
-    am_wrong_field = ScienceDirectSearch(one_article_query,
-                                 integrity_fields=["notExistingField"],
-                                 integrity_action="warn",
-                                 view="STANDARD",
-                                 refresh=30)
+    am_wrong_field = ScienceDirectSearch(query='',
+                                   title='Assessing LLMs in malicious code deobfuscation of real-world malware campaigns',
+                                   date='2024',
+                                   integrity_fields=["notExistingField"],
+                                   integrity_action="warn",
+                                   view="STANDARD", refresh=30)
     with pytest.raises(ValueError):
         _ = am_wrong_field.results
 
 
 def test_large_results():
     with pytest.raises(ScopusQueryError):
-        _ = ScienceDirectSearch(huge_query, view="STANDARD", download=True, refresh=30)
+        _ = ScienceDirectSearch('Neural Networks', view="STANDARD", download=True, refresh=30)
 
 
 def test_length():
@@ -88,5 +92,5 @@ def test_length():
 
 
 def test_string():
-    expected_str = "Search '{'title': 'Assessing LLMs in malicious code deobfuscation of real-world malware campaigns', 'date': '2024'}' yielded 1 document as of 2025-05-07:\n    10.1016/j.eswa.2024.124912"
-    assert str(sds_standard) == expected_str
+    expected_str = "Search '' yielded 1 document as of"
+    assert str(sds_standard).startswith(expected_str)

pybliometrics/superclasses/search.py

@@ -39,15 +39,16 @@ def __init__(self,
         count = COUNTS[api][self._view]
 
         if api == 'ScienceDirectSearch':
-            # Add default parameters
-            params = {**query}
+            # Set qs, keyword arguments and add default parameters
+            params = {'qs': query, **kwds}
+            # Flatten query and create name
+            flat_query = flatten_dict(params)
+            name = "&".join(["=".join(map(str, t)) for t in zip(flat_query.keys(), flat_query.values())])
+            # Add default parameters for pagination
             params.setdefault('display', {})
             defaults = {'offset': 0, 'show': count, 'sortBy': 'date'}
             for key, default in defaults.items():
                 params['display'].setdefault(key, default)
-            # Flatten query and create name
-            flat_query = flatten_dict(query)
-            name = "&".join(["=".join(map(str, t)) for t in zip(flat_query.keys(), flat_query.values())])
         else:
             params = {'count': count, 'view': self._view, **kwds}