Merge branch 'master' into full_documentation

Author: Kenneth Reitz

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
     - name: Checkout repository

HISTORY.md

@@ -1,12 +1,23 @@
 Release History
 ===============
 
-dev
----
+0.1.3 (2023-10-06)
+------------------
 
-* Initial release
+- Replace deprecated serpapi_pagination.next_link with 'next'. 
+- Improve documentation: how to use the client directly for pagination searches.
 
-1.0.0 (planned)
----------------
+0.1.2 (2023-10-03)
+------------------
 
-- First planned release
+- Update project status to Production/Stable.
+
+0.1.1 (2023-10-03)
+------------------
+
+- Update documentation link to point to Read the Docs.
+
+0.1.0 (2023-10-03)
+------------------
+
+- First release on PyPI.

README.md

@@ -3,18 +3,15 @@
 <h1 align="center">SerpApi Python Library & Package</h1>
   <img src="https://user-images.githubusercontent.com/78694043/233921372-bb57c347-9005-4b59-8f09-993698a87eb6.svg" width="600" alt="serpapi python library logo">
 
-  <!-- <a href="https://badge.fury.io/py/serpapi-python">![Package](https://badge.fury.io/py/serpapi.svg)</a>
-  <a href="https://pepy.tech/project/serpapi-python">![Downloads](https://static.pepy.tech/personalized-badge/serpapi?period=month&units=international_system&left_color=grey&right_color=brightgreen&left_text=Downloads)</a>  -->
+  <a href="https://badge.fury.io/py/serpapi-python">![Package](https://badge.fury.io/py/serpapi.svg)</a>
+  
   [![serpapi-python](https://github.com/serpapi/serpapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-python/actions/workflows/ci.yml)
 </div>
 
 This repository is the home of the *soon–to–be* official Python API wrapper for [SerpApi](https://serpapi.com). This `serpapi` module allows you to access search data in your Python application.
 
 [SerpApi](https://serpapi.com) supports Google, Google Maps, Google Shopping, Bing, Baidu, Yandex, Yahoo, eBay, App Stores, and more. Check out the [documentation](https://serpapi.com/search-api) for a full list.
 
-## Current Status
-
-This project is under development, and will be released to the public on PyPi soon.
 
 ## Installation
 
@@ -24,7 +21,7 @@ To install the `serpapi` package, simply run the following command:
 $ pip install serpapi
 ```
 
-Please note that this package is separate from the *soon–to–be* legacy `serpapi` module, which is currently available on PyPi as `google-search-results`.
+Please note that this package is separate from the legacy `serpapi` module, which is available on PyPi as `google-search-results`. This package is maintained by SerpApi, and is the recommended way to access the SerpApi service from Python.
 
 ## Usage
 

docs/index.rst

@@ -1,4 +1,4 @@
-.. serapi-python documentation master file, created by
+.. serpapi-python documentation master file, created by
    sphinx-quickstart on Sun Apr  3 21:09:40 2022.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -37,6 +37,11 @@ For example, the API endpoint ``https://serpapi.com/search.json`` is represented
 
 Any parameters that you pass to ``search()`` will be passed to the API. This includes the ``api_key`` parameter, which is required for all requests.
 
+.. _using-api-client-directly:
+
+Using the API Client directly
+^^^^^^^^^
+
 To make this less repetitive, and gain the benefit of connection pooling, let's start using the API Client directly::
 
    >>> client = serpapi.Client(api_key="secret_api_key")
@@ -116,9 +121,11 @@ You can get the next page of results::
    >>> type(s.next_page())
    <class 'serpapi.models.SerpResults'>
 
-Or iterate over all pages of results::
+To iterate over all pages of results, it's recommended to :ref:`use the API Client directly <using-api-client-directly>`::
 
-   >>> for page in s.yield_pages():
+   >>> client = serpapi.Client(api_key="secret_api_key")
+   >>> search = client.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
+   >>> for page in search.yield_pages():
    ...     print(page["search_metadata"]["page_number"])
    1
    2

serpapi/__version__.py

@@ -1 +1 @@
-__version__ = "0.0.1"
+__version__ = "0.1.3"

serpapi/models.py

@@ -51,7 +51,7 @@ def next_page_url(self):
         serpapi_pagination = self.data.get("serpapi_pagination")
 
         if serpapi_pagination:
-            return serpapi_pagination.get("next_link")
+            return serpapi_pagination.get("next")
 
     def next_page(self):
         """Return the next page of results, if any."""

setup.py

@@ -46,6 +46,27 @@
     about["__version__"] = VERSION
 
 
+class TestCommand(Command):
+    """Support setup.py test."""
+
+    description = "Test the package."
+    user_options = []
+
+    @staticmethod
+    def status(s):
+        """Prints things in bold."""
+        print("\033[1m{0}\033[0m".format(s))
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        os.system("{0} -m pytest".format(sys.executable))
+        sys.exit()
+
 class UploadCommand(Command):
     """Support setup.py upload."""
 
@@ -104,7 +125,7 @@ def run(self):
     extras_require=EXTRAS,
     include_package_data=True,
     license="MIT",
-    project_urls={"Documentation": "https://serpapi.com/search-api"},
+    project_urls={"Documentation": "https://serpapi-python.readthedocs.io/en/latest/"},
     keywords="scrape,serp,api,serpapi,scraping,json,search,localized,rank,google,bing,baidu,yandex,yahoo,ebay,scale,datamining,training,machine,ml,youtube,naver,walmart,apple,store,app,serpapi",
     classifiers=[
         # Trove classifiers
@@ -119,6 +140,7 @@ def run(self):
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
         "Natural Language :: English",
         "Topic :: Utilities",
         "Topic :: Internet :: WWW/HTTP",
@@ -129,5 +151,6 @@ def run(self):
     # $ setup.py publish support.
     cmdclass={
         "upload": UploadCommand,
+        "test": TestCommand
     },
 )

tests/example_search_apple_app_store_test.py

@@ -3,16 +3,10 @@
 import os
 import serpapi
 
-@pytest.mark.skipif((os.getenv("API_KEY") == None), reason="no api_key provided")
-def test_search_apple_app_store():
-  client = serpapi.Client(api_key=os.getenv("API_KEY"))
+def test_search_apple_app_store(client):
   data = client.search({
       'engine': 'apple_app_store',
       'term': 'coffee',
   })
   assert data.get('error') is None
   assert data['organic_results']
-
-# os.getenv("API_KEY") is your secret API Key
-# copy/paste from [http://serpapi.com/dashboard] to your bash
-# ```export API_KEY="your_secure_api_key"```

tests/example_search_baidu_test.py

@@ -3,16 +3,11 @@
 import os
 import serpapi
 
-@pytest.mark.skipif((os.getenv("API_KEY") == None), reason="no api_key provided")
-def test_search_baidu():
-  client = serpapi.Client(api_key=os.getenv("API_KEY"))
+
+def test_search_baidu(client):
   data = client.search({
       'engine': 'baidu',
       'q': 'coffee',
   })
   assert data.get('error') is None
   assert data['organic_results']
-
-# os.getenv("API_KEY") is your secret API Key
-# copy/paste from [http://serpapi.com/dashboard] to your bash
-# ```export API_KEY="your_secure_api_key"```

tests/example_search_bing_test.py

@@ -3,16 +3,10 @@
 import os
 import serpapi
 
-@pytest.mark.skipif((os.getenv("API_KEY") == None), reason="no api_key provided")
-def test_search_bing():
-  client = serpapi.Client(api_key=os.getenv("API_KEY"))
+def test_search_bing(client):
   data = client.search({
       'engine': 'bing',
       'q': 'coffee',
   })
   assert data.get('error') is None
   assert data['organic_results']
-
-# os.getenv("API_KEY") is your secret API Key
-# copy/paste from [http://serpapi.com/dashboard] to your bash
-# ```export API_KEY="your_secure_api_key"```