Merge pull request #5 from serpapi/kr-params-simplify

General Updates

Author: Kenneth Reitz

docs/index.rst

@@ -78,8 +78,6 @@ This part of the documentation covers all the interfaces of :class:`serpapi` Pyt
 .. module:: serpapi
    :platform: Unix, Windows
    :synopsis: SerpApi Python Library
-   :members:
-   :undoc-members:
 
 .. autofunction:: serpapi.search
 .. autofunction:: serpapi.search_archive
@@ -162,7 +160,7 @@ This class also alleviates the need to pass an ``api_key```  along with every se
 Exceptions
 ----------
 
-.. autoexception:: serpapi.SerpAPIError
+.. autoexception:: serpapi.SerpApiError
    :members:
 
 .. autoexception:: serpapi.SearchIDNotProvided

serpapi/core.py

@@ -28,10 +28,10 @@ class Client(HTTPClient):
     def __repr__(self):
         return "<SerpApi Client>"
 
-    def search(self, **params):
+    def search(self, params: dict = None, **kwargs):
         """Fetch a page of results from SerpApi. Returns a :class:`SerpResults <serpapi.client.SerpResults>` object, or unicode text (*e.g.* if ``'output': 'html'`` was passed).
 
-        The following two calls are equivalent:
+        The following three calls are equivalent:
 
         .. code-block:: python
 
@@ -42,6 +42,11 @@ def search(self, **params):
             >>> params = {"q": "Coffee", "location": "Austin, Texas, United States"}
             >>> s = serpapi.search(**params)
 
+        .. code-block:: python
+
+            >>> params = {"q": "Coffee", "location": "Austin, Texas, United States"}
+            >>> s = serpapi.search(params)
+
 
         :param q: typically, this is the parameter for the search engine query.
         :param engine: the search engine to use. Defaults to ``google``.
@@ -52,12 +57,17 @@ def search(self, **params):
 
         **Learn more**: https://serpapi.com/search-api
         """
+        if params is None:
+            params = {}
+
+        if kwargs:
+            params.update(kwargs)
 
         r = self.request("GET", "/search", params=params)
 
         return SerpResults.from_http_response(r, client=self)
 
-    def search_archive(self, **params):
+    def search_archive(self, params: dict = None, **kwargs):
         """Get a result from the SerpApi Search Archive API.
 
         :param search_id: the Search ID of the search to retrieve from the archive.
@@ -67,6 +77,11 @@ def search_archive(self, **params):
 
         **Learn more**: https://serpapi.com/search-archive-api
         """
+        if params is None:
+            params = {}
+
+        if kwargs:
+            params.update(kwargs)
 
         try:
             search_id = params["search_id"]
@@ -78,7 +93,7 @@ def search_archive(self, **params):
         r = self.request("GET", f"/searches/{ search_id }", params=params)
         return SerpResults.from_http_response(r, client=self)
 
-    def locations(self, **params):
+    def locations(self, params: dict = None, **kwargs):
         """Get a list of supported Google locations.
 
 
@@ -88,6 +103,11 @@ def locations(self, **params):
 
         **Learn more**: https://serpapi.com/locations-api
         """
+        if params is None:
+            params = {}
+
+        if kwargs:
+            params.update(kwargs)
 
         r = self.request(
             "GET",
@@ -97,10 +117,7 @@ def locations(self, **params):
         )
         return r.json()
 
-    def account(
-        self,
-        **params,
-    ):
+    def account(self, params: dict = None, **kwargs):
         """Get SerpApi account information.
 
         :param api_key: the API Key to use for SerpApi.com.
@@ -109,10 +126,17 @@ def account(
         **Learn more**: https://serpapi.com/account-api
         """
 
+        if params is None:
+            params = {}
+
+        if kwargs:
+            params.update(kwargs)
+
         r = self.request("GET", "/account.json", params=params, assert_200=True)
         return r.json()
 
 
+# An un-authenticated client instance.
 _client = Client()
 search = _client.search
 search_archive = _client.search_archive

serpapi/exceptions.py

@@ -1,31 +1,31 @@
 import requests
 
 
-class SerpAPIError(Exception):
+class SerpApiError(Exception):
     """Base class for exceptions in this module."""
 
     pass
 
 
-class APIKeyNotProvided(ValueError, SerpAPIError):
+class APIKeyNotProvided(ValueError, SerpApiError):
     """API key is not provided."""
 
     pass
 
 
-class SearchIDNotProvided(ValueError, SerpAPIError):
+class SearchIDNotProvided(ValueError, SerpApiError):
     """Search ID is not provided."""
 
     pass
 
 
-class HTTPError(requests.exceptions.HTTPError, SerpAPIError):
+class HTTPError(requests.exceptions.HTTPError, SerpApiError):
     """HTTP Error."""
 
     pass
 
 
-class HTTPConnectionError(HTTPError, requests.exceptions.ConnectionError, SerpAPIError):
+class HTTPConnectionError(HTTPError, requests.exceptions.ConnectionError, SerpApiError):
     """Connection Error."""
 
     pass

serpapi/models.py

@@ -10,7 +10,7 @@
 
 
 class SerpResults(UserDict):
-    """A dictionary-like object that represents the results of a SerpAPI request.
+    """A dictionary-like object that represents the results of a SerpApi request.
 
     .. code-block:: python
 

tests/test_integration.py

@@ -68,3 +68,14 @@ def test_coffee_search_next_page(coffee_search):
 
     assert isinstance(next_page, serpapi.SerpResults)
     assert coffee_search["search_metadata"]["id"] != next_page["search_metadata"]["id"]
+
+
+def test_search_function_signature(coffee_params, client):
+    s = client.search(coffee_params)
+    assert s["search_metadata"]["id"]
+
+    s = client.search(**coffee_params)
+    assert s["search_metadata"]["id"]
+
+    s = client.search(q='coffee')
+    assert s["search_metadata"]["id"]