🛠️ HTTPx Adapter Support, 📝 Comprehensive Test Suite, 📖 Update Examples

README.md

@@ -9,12 +9,16 @@
 ```bash
 pip install google-custom-search
 ```
-or if you want use async/await, please install.
+
+or if you want use `async`/`await`, please install your preferred async http client
+
 ```bash
-pip install google-custom-search[async]
+pip install google-custom-search[aiohttp]  # asyncio only
+pip install google-custom-search[httpx]  # works with Curio, Trio, anyio
 ```
 
 ## Sample code
+
 ```py
 import google_custom_search
 
@@ -26,16 +30,16 @@ results = google.search("Hello")
 for result in results:
     # get a title.
     print(result.title)
-  
+
     # get a link.
     print(result.url)
-  
+
     # get a displayLink.
     print(result.display_url)
 
     # get a htmlTitle.
     print(result.html_title)
-  
+
     # get a snippet.
     print(result.snippet)
 ```
@@ -45,27 +49,30 @@ for result in results:
 import asyncio
 import google_custom_search
 
+
 google = google_custom_search.CustomSearch(token="your api_key", engine_id="your engine_id", image=True)
 # if image is True, it's can search, but you need to setting at google console search
 
 async def main():
-    results = await google.search_async("word!")
-    for result in results:
-        # get a title.
-        print(result.title)
-
-        # get a link.
-        print(result.url)
-
-        # get a displayLink.
-        print(result.display_url)
+    # also available: HttpxAdapter() - usage differs subtly
+    # see runnable ./examples/async.py example
+    async with AiohttpAdapter() as adapter:
+        for result in await CustomSearch(adapter).search("how to use async with in python"):
+            # get a title.
+            print(result.title)
+
+            # get a link.
+            print(result.url)
+
+            # get a displayLink.
+            print(result.display_url)
+
+            # get a htmlTitle.
+            print(result.html_title)
+
+            # get a snippet.
+            print(result.snippet)
 
-        # get a htmlTitle.
-        print(result.html_title)
-
-        # get a snippet.
-        print(result.snippet)
-
 asyncio.run(main())
 ```
 
@@ -82,18 +89,18 @@ async def main():
     async for item in google.search_async_iterator("word!"):
         # get a title.
         print(item.title)
-  
+
         # get a link.
         print(item.url)
-  
+
         # get a displayLink.
         print(item.display_url)
 
         # get a htmlTitle.
         print(item.html_title)
-  
+
         # get a snippet.
         print(item.snippet)
-    
+
 asyncio.run(main())
 ```

examples/async.py

@@ -1,12 +1,46 @@
-from google_custom_search import CustomSearch, AiohttpAdapter
+from google_custom_search import CustomSearch, AiohttpAdapter, HttpxAdapter
 import asyncio
+from pprint import pprint
 
 
-customsearch = CustomSearch(AiohttpAdapter("apikey", "engine"))
+async def main_aiohttp():
+    """Example using AiohttpAdapter with async iterator."""
+    async with AiohttpAdapter() as adapter:
+        # Using asearch returns an async generator, so we need async for
+        async for item in CustomSearch(adapter).asearch(
+            "python frameworks httpx vs aiohttp - when to use aiohttp", limit=5
+        ):
+            pprint(item.data)
+            print("-" * 80)
 
 
-async def main():
-    for item in await customsearch.search("python"):
-        print(item.title)
+async def main_httpx():
+    """Example using HttpxAdapter with async iterator."""
+    async with HttpxAdapter() as adapter:
+        # Using asearch returns an async generator, so we need async for
+        async for item in CustomSearch(adapter).asearch(
+            "python frameworks httpx vs aiohttp - when to use httpx", limit=5
+        ):
+            pprint(item.data)
+            print("-" * 80)
 
-asyncio.run(main())
+
+async def main_httpx_list():
+    """Example using HttpxAdapter with search_async to get a list."""
+    async with HttpxAdapter() as adapter:
+        # Using search_async returns a list, so we can use regular for
+        results = await adapter.search_async("python async web frameworks")
+        for item in results[:5]:
+            pprint(item.data)
+            print("-" * 80)
+
+
+# Run examples
+print("=== Running AiohttpAdapter example ===")
+asyncio.run(main_aiohttp())
+
+print("\n=== Running HttpxAdapter with async iterator example ===")
+asyncio.run(main_httpx())
+
+print("\n=== Running HttpxAdapter with search_async example ===")
+asyncio.run(main_httpx_list())

examples/sync.py

@@ -1,6 +1,7 @@
+from pprint import pprint
 from google_custom_search import CustomSearch, RequestsAdapter
 
 
-customsearch = CustomSearch(RequestsAdapter("apikey", "engine_id"))
-for item in customsearch.search("python"):
-    print(item.title)
+customsearch = CustomSearch(RequestsAdapter())
+for item in customsearch.search("pip install google-custom-search"):
+    pprint(item.data)

google_custom_search/__init__.py

@@ -1,8 +1,22 @@
-from .search import *
-from .types import *
-from .errors import *
-from .adapter import *
+from .search import CustomSearch
+from .types import Item
+from .errors import ApiNotEnabled, AsyncError
+from .adapter import BaseAdapter, RequestsAdapter, AiohttpAdapter, HttpxAdapter
+from . import results_schema
 
+# Build __all__ list
+__all__ = [
+    "CustomSearch",
+    "Item",
+    "ApiNotEnabled",
+    "AsyncError",
+    "BaseAdapter",
+    "RequestsAdapter",
+    "AiohttpAdapter",
+    "HttpxAdapter",
+    "results_schema",
+]  # noqa: F405
 
-__version__ = "3.0.0"
+
+__version__ = "3.1.0a1"  # PEP 440
 __author__ = "mc-fdc-dev"