tavily-python 0.7.21__tar.gz → 0.7.23__tar.gz

{tavily_python-0.7.21 → tavily_python-0.7.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavily-python
-Version: 0.7.21
+Version: 0.7.23
 Summary: Python wrapper for the Tavily API
 Home-page: https://github.com/tavily-ai/tavily-python
 Author: Tavily AI
@@ -25,7 +25,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Tavily Python Wrapper
+# Tavily Python SDK
 
 [![GitHub stars](https://img.shields.io/github/stars/tavily-ai/tavily-python?style=social)](https://github.com/tavily-ai/tavily-python/stargazers)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/tavily-python)](https://pypi.org/project/tavily-python/)
@@ -63,6 +63,21 @@ response = tavily_client.search("Who is Leo Messi?")
 print(response)
 ```
 
+### Using exact match to find specific names or phrases
+
+```python
+from tavily import TavilyClient
+
+client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Use exact_match=True to only return results containing the exact phrase(s) inside quotes
+response = client.search(
+    query='"John Smith" CEO Acme Corp',
+    exact_match=True
+)
+print(response)
+```
+
 This is equivalent to directly querying our REST API.
 
 ### Generating context for a RAG Application
@@ -258,6 +273,53 @@ for chunk in stream:
     print(chunk.decode('utf-8'))
 ```
 
+## Advanced: Custom Session / Client Injection
+
+For enterprise environments that proxy Tavily traffic through an API gateway (e.g., for centralized auth, logging, or policy enforcement), you can pass a pre-configured HTTP session instead of a Tavily API key.
+
+### Sync (custom `requests.Session`)
+
+```python
+import requests
+from tavily import TavilyClient
+
+# Pre-configure a session with your gateway's auth
+session = requests.Session()
+session.headers["Authorization"] = "Bearer your-gateway-token"
+session.headers["X-Subscription-Key"] = "your-subscription-key"
+
+# No Tavily API key needed — auth is handled by the session
+client = TavilyClient(
+    session=session,
+    api_base_url="https://your-gateway.com/tavily",
+)
+
+response = client.search("latest AI research")
+```
+
+### Async (custom `httpx.AsyncClient`)
+
+```python
+import httpx
+from tavily import AsyncTavilyClient
+
+# Pre-configure an async client with your gateway's auth
+custom_client = httpx.AsyncClient(
+    headers={"Authorization": "Bearer your-gateway-token"},
+    base_url="https://your-gateway.com/tavily",
+)
+
+client = AsyncTavilyClient(client=custom_client)
+
+response = await client.search("latest AI research")
+```
+
+**Key behaviors:**
+- If a custom session/client is provided, `api_key` is optional
+- Custom session headers take precedence over SDK defaults (e.g., your `Authorization` won't be overwritten)
+- Custom session proxies take precedence over SDK proxy settings
+- The SDK will **not** close externally-provided sessions — you manage the lifecycle
+
 ## Documentation
 
 For a complete guide on how to use the different endpoints and their parameters, please head to our [Python API Reference](https://docs.tavily.com/sdk/python/reference).

{tavily_python-0.7.21 → tavily_python-0.7.23}/README.md

@@ -1,4 +1,4 @@
-# Tavily Python Wrapper
+# Tavily Python SDK
 
 [![GitHub stars](https://img.shields.io/github/stars/tavily-ai/tavily-python?style=social)](https://github.com/tavily-ai/tavily-python/stargazers)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/tavily-python)](https://pypi.org/project/tavily-python/)
@@ -36,6 +36,21 @@ response = tavily_client.search("Who is Leo Messi?")
 print(response)
 ```
 
+### Using exact match to find specific names or phrases
+
+```python
+from tavily import TavilyClient
+
+client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Use exact_match=True to only return results containing the exact phrase(s) inside quotes
+response = client.search(
+    query='"John Smith" CEO Acme Corp',
+    exact_match=True
+)
+print(response)
+```
+
 This is equivalent to directly querying our REST API.
 
 ### Generating context for a RAG Application
@@ -231,6 +246,53 @@ for chunk in stream:
     print(chunk.decode('utf-8'))
 ```
 
+## Advanced: Custom Session / Client Injection
+
+For enterprise environments that proxy Tavily traffic through an API gateway (e.g., for centralized auth, logging, or policy enforcement), you can pass a pre-configured HTTP session instead of a Tavily API key.
+
+### Sync (custom `requests.Session`)
+
+```python
+import requests
+from tavily import TavilyClient
+
+# Pre-configure a session with your gateway's auth
+session = requests.Session()
+session.headers["Authorization"] = "Bearer your-gateway-token"
+session.headers["X-Subscription-Key"] = "your-subscription-key"
+
+# No Tavily API key needed — auth is handled by the session
+client = TavilyClient(
+    session=session,
+    api_base_url="https://your-gateway.com/tavily",
+)
+
+response = client.search("latest AI research")
+```
+
+### Async (custom `httpx.AsyncClient`)
+
+```python
+import httpx
+from tavily import AsyncTavilyClient
+
+# Pre-configure an async client with your gateway's auth
+custom_client = httpx.AsyncClient(
+    headers={"Authorization": "Bearer your-gateway-token"},
+    base_url="https://your-gateway.com/tavily",
+)
+
+client = AsyncTavilyClient(client=custom_client)
+
+response = await client.search("latest AI research")
+```
+
+**Key behaviors:**
+- If a custom session/client is provided, `api_key` is optional
+- Custom session headers take precedence over SDK defaults (e.g., your `Authorization` won't be overwritten)
+- Custom session proxies take precedence over SDK proxy settings
+- The SDK will **not** close externally-provided sessions — you manage the lifecycle
+
 ## Documentation
 
 For a complete guide on how to use the different endpoints and their parameters, please head to our [Python API Reference](https://docs.tavily.com/sdk/python/reference).

{tavily_python-0.7.21 → tavily_python-0.7.23}/setup.py

@@ -5,7 +5,7 @@ with open('README.md', 'r', encoding='utf-8') as f:
 
 setup(
     name='tavily-python',
-    version='0.7.21',
+    version='0.7.23',
     url='https://github.com/tavily-ai/tavily-python',
     author='Tavily AI',
     author_email='support@tavily.com',

{tavily_python-0.7.21 → tavily_python-0.7.23}/tavily/async_tavily.py

@@ -19,48 +19,63 @@ class AsyncTavilyClient:
                  proxies: Optional[dict[str, str]] = None,
                  api_base_url: Optional[str] = None,
                  client_source: Optional[str] = None,
-                 project_id: Optional[str] = None):
+                 project_id: Optional[str] = None,
+                 client: Optional[httpx.AsyncClient] = None):
         if api_key is None:
             api_key = os.getenv("TAVILY_API_KEY")
 
-        if not api_key:
+        if not api_key and client is None:
             raise MissingAPIKeyError()
 
-        proxies = proxies or {}
+        tavily_project = project_id or os.getenv("TAVILY_PROJECT")
 
-        mapped_proxies = {
-            "http://": proxies.get("http", os.getenv("TAVILY_HTTP_PROXY")),
-            "https://": proxies.get("https", os.getenv("TAVILY_HTTPS_PROXY")),
+        self._api_base_url = api_base_url or "https://api.tavily.com"
+        self._company_info_tags = company_info_tags
+
+        default_headers = {
+            "Content-Type": "application/json",
+            **({"Authorization": f"Bearer {api_key}"} if api_key else {}),
+            "X-Client-Source": client_source or "tavily-python",
+            **({"X-Project-ID": tavily_project} if tavily_project else {})
         }
 
-        mapped_proxies = {key: value for key, value in mapped_proxies.items() if value}
+        self._external_client = client is not None
+
+        if client is not None:
+            self._client = client
+            # Only set headers that aren't already configured on the external client
+            for key, value in default_headers.items():
+                if key not in self._client.headers:
+                    self._client.headers[key] = value
+            # Set base_url if the external client doesn't have one
+            if not str(self._client.base_url):
+                self._client.base_url = self._api_base_url
+        else:
+            proxies = proxies or {}
 
-        proxy_mounts = (
-            {scheme: httpx.AsyncHTTPTransport(proxy=proxy) for scheme, proxy in mapped_proxies.items()}
-            if mapped_proxies
-            else None
-        )
+            mapped_proxies = {
+                "http://": proxies.get("http", os.getenv("TAVILY_HTTP_PROXY")),
+                "https://": proxies.get("https", os.getenv("TAVILY_HTTPS_PROXY")),
+            }
 
-        tavily_project = project_id or os.getenv("TAVILY_PROJECT")
+            mapped_proxies = {key: value for key, value in mapped_proxies.items() if value}
 
-        self._api_base_url = api_base_url or "https://api.tavily.com"
+            proxy_mounts = (
+                {scheme: httpx.AsyncHTTPTransport(proxy=proxy) for scheme, proxy in mapped_proxies.items()}
+                if mapped_proxies
+                else None
+            )
 
-        # Create a persistent client for connection pooling
-        self._client = httpx.AsyncClient(
-            headers={
-                "Content-Type": "application/json",
-                "Authorization": f"Bearer {api_key}",
-                "X-Client-Source": client_source or "tavily-python",
-                **({"X-Project-ID": tavily_project} if tavily_project else {})
-            },
-            base_url=self._api_base_url,
-            mounts=proxy_mounts
-        )
-        self._company_info_tags = company_info_tags
+            self._client = httpx.AsyncClient(
+                headers=default_headers,
+                base_url=self._api_base_url,
+                mounts=proxy_mounts
+            )
 
     async def close(self):
         """Close the client and release connection pool resources."""
-        await self._client.aclose()
+        if not self._external_client:
+            await self._client.aclose()
 
     async def __aenter__(self):
         return self
@@ -88,6 +103,7 @@ class AsyncTavilyClient:
             auto_parameters: bool = None,
             include_favicon: bool = None,
             include_usage: bool = None,
+            exact_match: bool = None,
             **kwargs,
     ) -> dict:
         """
@@ -111,6 +127,7 @@ class AsyncTavilyClient:
             "auto_parameters": auto_parameters,
             "include_favicon": include_favicon,
             "include_usage": include_usage,
+            "exact_match": exact_match,
         }
 
         data = {k: v for k, v in data.items() if v is not None}
@@ -164,6 +181,7 @@ class AsyncTavilyClient:
                      auto_parameters: bool = None,
                      include_favicon: bool = None,
                      include_usage: bool = None,
+                     exact_match: bool = None,
                      **kwargs,  # Accept custom arguments
                      ) -> dict:
         """
@@ -188,6 +206,7 @@ class AsyncTavilyClient:
                                            auto_parameters=auto_parameters,
                                            include_favicon=include_favicon,
                                            include_usage=include_usage,
+                                           exact_match=exact_match,
                                            **kwargs,
                                            )
 

{tavily_python-0.7.21 → tavily_python-0.7.23}/tavily/hybrid_rag/hybrid_rag.py

@@ -1,6 +1,7 @@
 import os
 from typing import Union, Optional, Literal
 
+import requests
 from tavily import TavilyClient
 
 try:
@@ -76,7 +77,8 @@ class TavilyHybridClient():
             embeddings_field: str = 'embeddings',
             content_field: str = 'content',
             embedding_function: Optional[callable] = None,
-            ranking_function: Optional[callable] = None
+            ranking_function: Optional[callable] = None,
+            session: Optional[requests.Session] = None
         ):
         '''
         A client for performing hybrid RAG using both the Tavily API and a local database collection.
@@ -90,9 +92,10 @@ class TavilyHybridClient():
         content_field (str): The name of the field in the collection that contains the content.
         embedding_function (callable): If provided, this function will be used to generate embeddings for the search query and documents.
         ranking_function (callable): If provided, this function will be used to rerank the combined results.
+        session (requests.Session): If provided, this pre-configured session will be used for HTTP requests. When set, api_key is optional.
         '''
-        
-        self.tavily = TavilyClient(api_key)
+
+        self.tavily = TavilyClient(api_key, session=session)
         
         if db_provider != 'mongodb':
             raise ValueError("Only MongoDB is currently supported as a database provider.")

{tavily_python-0.7.21 → tavily_python-0.7.23}/tavily/tavily.py

@@ -11,11 +11,11 @@ class TavilyClient:
     Tavily API client class.
     """
 
-    def __init__(self, api_key: Optional[str] = None, proxies: Optional[dict[str, str]] = None, api_base_url: Optional[str] = None, client_source: Optional[str] = None, project_id: Optional[str] = None):
+    def __init__(self, api_key: Optional[str] = None, proxies: Optional[dict[str, str]] = None, api_base_url: Optional[str] = None, client_source: Optional[str] = None, project_id: Optional[str] = None, session: Optional[requests.Session] = None):
         if api_key is None:
             api_key = os.getenv("TAVILY_API_KEY")
 
-        if not api_key:
+        if not api_key and session is None:
             raise MissingAPIKeyError()
 
         resolved_proxies = {
@@ -32,19 +32,26 @@ class TavilyClient:
         
         self.headers = {
             "Content-Type": "application/json",
-            "Authorization": f"Bearer {self.api_key}",
+            **({"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}),
             "X-Client-Source": client_source or "tavily-python",
             **({"X-Project-ID": tavily_project} if tavily_project else {})
         }
 
-        self.session = requests.Session()
-        self.session.headers.update(self.headers)
+        self._external_session = session is not None
+        self.session = session if session is not None else requests.Session()
+        # For external sessions, only set headers that aren't already configured
+        for key, value in self.headers.items():
+            if key not in self.session.headers:
+                self.session.headers[key] = value
         if self.proxies:
-            self.session.proxies.update(self.proxies)
+            for protocol, url in self.proxies.items():
+                if protocol not in self.session.proxies:
+                    self.session.proxies[protocol] = url
 
     def close(self):
         """Close the session and release resources."""
-        self.session.close()
+        if not self._external_session:
+            self.session.close()
 
     def __enter__(self):
         return self
@@ -71,6 +78,7 @@ class TavilyClient:
                 auto_parameters: bool = None,
                 include_favicon: bool = None,
                 include_usage: bool = None,
+                exact_match: bool = None,
                 **kwargs
                 ) -> dict:
         """
@@ -95,6 +103,7 @@ class TavilyClient:
             "auto_parameters": auto_parameters,
             "include_favicon": include_favicon,
             "include_usage": include_usage,
+            "exact_match": exact_match,
         }
 
         data = {k: v for k, v in data.items() if v is not None}
@@ -151,6 +160,7 @@ class TavilyClient:
                auto_parameters: bool = None,
                include_favicon: bool = None,
                include_usage: bool = None,
+               exact_match: bool = None,
                **kwargs,  # Accept custom arguments
                ) -> dict:
         """
@@ -175,6 +185,7 @@ class TavilyClient:
                                      auto_parameters=auto_parameters,
                                      include_favicon=include_favicon,
                                      include_usage=include_usage,
+                                     exact_match=exact_match,
                                      **kwargs)
         response_dict.setdefault("results", [])
         return response_dict

{tavily_python-0.7.21 → tavily_python-0.7.23}/tavily_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tavily-python
-Version: 0.7.21
+Version: 0.7.23
 Summary: Python wrapper for the Tavily API
 Home-page: https://github.com/tavily-ai/tavily-python
 Author: Tavily AI
@@ -25,7 +25,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Tavily Python Wrapper
+# Tavily Python SDK
 
 [![GitHub stars](https://img.shields.io/github/stars/tavily-ai/tavily-python?style=social)](https://github.com/tavily-ai/tavily-python/stargazers)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/tavily-python)](https://pypi.org/project/tavily-python/)
@@ -63,6 +63,21 @@ response = tavily_client.search("Who is Leo Messi?")
 print(response)
 ```
 
+### Using exact match to find specific names or phrases
+
+```python
+from tavily import TavilyClient
+
+client = TavilyClient(api_key="tvly-YOUR_API_KEY")
+
+# Use exact_match=True to only return results containing the exact phrase(s) inside quotes
+response = client.search(
+    query='"John Smith" CEO Acme Corp',
+    exact_match=True
+)
+print(response)
+```
+
 This is equivalent to directly querying our REST API.
 
 ### Generating context for a RAG Application
@@ -258,6 +273,53 @@ for chunk in stream:
     print(chunk.decode('utf-8'))
 ```
 
+## Advanced: Custom Session / Client Injection
+
+For enterprise environments that proxy Tavily traffic through an API gateway (e.g., for centralized auth, logging, or policy enforcement), you can pass a pre-configured HTTP session instead of a Tavily API key.
+
+### Sync (custom `requests.Session`)
+
+```python
+import requests
+from tavily import TavilyClient
+
+# Pre-configure a session with your gateway's auth
+session = requests.Session()
+session.headers["Authorization"] = "Bearer your-gateway-token"
+session.headers["X-Subscription-Key"] = "your-subscription-key"
+
+# No Tavily API key needed — auth is handled by the session
+client = TavilyClient(
+    session=session,
+    api_base_url="https://your-gateway.com/tavily",
+)
+
+response = client.search("latest AI research")
+```
+
+### Async (custom `httpx.AsyncClient`)
+
+```python
+import httpx
+from tavily import AsyncTavilyClient
+
+# Pre-configure an async client with your gateway's auth
+custom_client = httpx.AsyncClient(
+    headers={"Authorization": "Bearer your-gateway-token"},
+    base_url="https://your-gateway.com/tavily",
+)
+
+client = AsyncTavilyClient(client=custom_client)
+
+response = await client.search("latest AI research")
+```
+
+**Key behaviors:**
+- If a custom session/client is provided, `api_key` is optional
+- Custom session headers take precedence over SDK defaults (e.g., your `Authorization` won't be overwritten)
+- Custom session proxies take precedence over SDK proxy settings
+- The SDK will **not** close externally-provided sessions — you manage the lifecycle
+
 ## Documentation
 
 For a complete guide on how to use the different endpoints and their parameters, please head to our [Python API Reference](https://docs.tavily.com/sdk/python/reference).

{tavily_python-0.7.21 → tavily_python-0.7.23}/tavily_python.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ tavily_python.egg-info/dependency_links.txt
 tavily_python.egg-info/requires.txt
 tavily_python.egg-info/top_level.txt
 tests/test_crawl.py
+tests/test_custom_session.py
 tests/test_errors.py
 tests/test_map.py
 tests/test_research.py

tavily_python-0.7.23/tests/test_custom_session.py

@@ -0,0 +1,410 @@
+import asyncio
+import httpx
+from tests.request_intercept import intercept_requests, clear_interceptor, MockSession
+import tavily.tavily as sync_tavily
+import tavily.async_tavily as async_tavily
+import pytest
+from tavily.errors import MissingAPIKeyError
+
+
+@pytest.fixture
+def sync_interceptor():
+    yield intercept_requests(sync_tavily)
+    clear_interceptor(sync_tavily)
+
+
+@pytest.fixture
+def async_interceptor():
+    yield intercept_requests(async_tavily)
+    clear_interceptor(async_tavily)
+
+
+# --- Sync TavilyClient tests ---
+
+class TestSyncCustomSession:
+    def test_default_session_created_when_none_provided(self, sync_interceptor):
+        client = sync_tavily.TavilyClient(api_key="tvly-test")
+        assert not client._external_session
+
+    def test_custom_session_used(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        client = sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session)
+        assert client._external_session
+        assert client.session is custom_session
+
+    def test_custom_session_preserves_existing_headers(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        custom_session.headers["Authorization"] = "Bearer apim-token-123"
+        custom_session.headers["X-Custom"] = "custom-value"
+
+        client = sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session)
+
+        # Custom Authorization should be preserved (not overwritten by Tavily's)
+        assert client.session.headers["Authorization"] == "Bearer apim-token-123"
+        # Custom header should be preserved
+        assert client.session.headers["X-Custom"] == "custom-value"
+        # Tavily defaults should fill in missing headers
+        assert client.session.headers["Content-Type"] == "application/json"
+        assert client.session.headers["X-Client-Source"] == "tavily-python"
+
+    def test_custom_session_gets_default_headers_when_empty(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        client = sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session)
+
+        assert client.session.headers["Authorization"] == "Bearer tvly-test"
+        assert client.session.headers["Content-Type"] == "application/json"
+
+    def test_custom_session_preserves_existing_proxies(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        custom_session.proxies["https"] = "http://my-proxy:8080"
+
+        client = sync_tavily.TavilyClient(
+            api_key="tvly-test",
+            session=custom_session,
+            proxies={"https": "http://tavily-proxy:9090"},
+        )
+
+        # Custom session proxy should take precedence
+        assert client.session.proxies["https"] == "http://my-proxy:8080"
+
+    def test_close_does_not_close_external_session(self, sync_interceptor):
+        closed = []
+        custom_session = MockSession(sync_interceptor)
+        custom_session.close = lambda: closed.append(True)
+
+        client = sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session)
+        client.close()
+        assert len(closed) == 0
+
+    def test_close_closes_internal_session(self, sync_interceptor):
+        client = sync_tavily.TavilyClient(api_key="tvly-test")
+        # Should not raise — just verifies close() is called on internal session
+        client.close()
+
+    def test_context_manager_does_not_close_external_session(self, sync_interceptor):
+        closed = []
+        custom_session = MockSession(sync_interceptor)
+        custom_session.close = lambda: closed.append(True)
+
+        with sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session):
+            pass
+        assert len(closed) == 0
+
+    def test_custom_session_sends_request(self, sync_interceptor):
+        sync_interceptor.set_response(200, json={"results": []})
+        custom_session = MockSession(sync_interceptor)
+        custom_session.headers["Authorization"] = "Bearer apim-token"
+
+        client = sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session)
+        client.search("test query")
+
+        req = sync_interceptor.get_request()
+        assert req is not None
+        assert req.headers["Authorization"] == "Bearer apim-token"
+
+    # --- API key validation edge cases ---
+
+    def test_no_api_key_no_session_raises(self, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        with pytest.raises(MissingAPIKeyError):
+            sync_tavily.TavilyClient()
+
+    def test_no_api_key_with_session_allowed(self, sync_interceptor, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        custom_session = MockSession(sync_interceptor)
+        custom_session.headers["Authorization"] = "Bearer apim-token"
+        client = sync_tavily.TavilyClient(session=custom_session)
+        assert client.api_key is None
+        assert "Authorization" not in client.headers
+        assert client.session.headers["Authorization"] == "Bearer apim-token"
+
+    def test_no_api_key_with_session_no_auth_header_on_defaults(self, sync_interceptor, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        custom_session = MockSession(sync_interceptor)
+        client = sync_tavily.TavilyClient(session=custom_session)
+        # No api_key means no Authorization in defaults
+        assert "Authorization" not in client.headers
+        # Session shouldn't get an Authorization header either
+        assert "Authorization" not in client.session.headers
+
+    def test_no_api_key_with_session_sends_request(self, sync_interceptor, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        sync_interceptor.set_response(200, json={"results": []})
+        custom_session = MockSession(sync_interceptor)
+        custom_session.headers["Authorization"] = "Bearer apim-token"
+
+        client = sync_tavily.TavilyClient(session=custom_session)
+        client.search("test query")
+
+        req = sync_interceptor.get_request()
+        assert req is not None
+        assert req.headers["Authorization"] == "Bearer apim-token"
+
+    def test_empty_string_api_key_no_session_raises(self, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        with pytest.raises(MissingAPIKeyError):
+            sync_tavily.TavilyClient(api_key="")
+
+    def test_empty_string_api_key_with_session_allowed(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        client = sync_tavily.TavilyClient(api_key="", session=custom_session)
+        assert "Authorization" not in client.headers
+
+    def test_api_key_and_session_both_provided(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        client = sync_tavily.TavilyClient(api_key="tvly-test", session=custom_session)
+        # api_key provided and session has no Authorization, so default fills it in
+        assert client.session.headers["Authorization"] == "Bearer tvly-test"
+
+    def test_custom_session_with_all_endpoints(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        custom_session.headers["Authorization"] = "Bearer apim-token"
+
+        client = sync_tavily.TavilyClient(session=custom_session)
+
+        # search
+        sync_interceptor.set_response(200, json={"results": []})
+        client.search("test")
+        assert sync_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+        # extract
+        sync_interceptor.set_response(200, json={"results": [], "failed_results": []})
+        client.extract(urls=["https://example.com"])
+        assert sync_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+        # crawl
+        sync_interceptor.set_response(200, json={"results": []})
+        client.crawl(url="https://example.com")
+        assert sync_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+        # map
+        sync_interceptor.set_response(200, json={"results": []})
+        client.map(url="https://example.com")
+        assert sync_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+    def test_custom_session_with_custom_base_url(self, sync_interceptor):
+        sync_interceptor.set_response(200, json={"results": []})
+        custom_session = MockSession(sync_interceptor)
+
+        client = sync_tavily.TavilyClient(
+            api_key="tvly-test",
+            session=custom_session,
+            api_base_url="https://apim.corp.com/tavily",
+        )
+        client.search("test")
+
+        req = sync_interceptor.get_request()
+        assert req.url == "https://apim.corp.com/tavily/search"
+
+    def test_custom_session_proxies_fill_missing_protocols(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        custom_session.proxies["http"] = "http://session-proxy:8080"
+
+        client = sync_tavily.TavilyClient(
+            api_key="tvly-test",
+            session=custom_session,
+            proxies={"http": "http://arg-proxy:9090", "https": "http://arg-proxy:9091"},
+        )
+
+        # http: session proxy wins
+        assert client.session.proxies["http"] == "http://session-proxy:8080"
+        # https: session didn't have it, so arg fills it in
+        assert client.session.proxies["https"] == "http://arg-proxy:9091"
+
+    def test_custom_session_project_id_header(self, sync_interceptor):
+        custom_session = MockSession(sync_interceptor)
+        client = sync_tavily.TavilyClient(
+            api_key="tvly-test",
+            session=custom_session,
+            project_id="my-project",
+        )
+        assert client.session.headers["X-Project-ID"] == "my-project"
+
+    def test_shared_session_across_multiple_clients(self, sync_interceptor):
+        sync_interceptor.set_response(200, json={"results": []})
+        shared_session = MockSession(sync_interceptor)
+        shared_session.headers["Authorization"] = "Bearer shared-token"
+
+        client1 = sync_tavily.TavilyClient(session=shared_session)
+        client2 = sync_tavily.TavilyClient(session=shared_session)
+
+        assert client1.session is client2.session
+
+        client1.search("query1")
+        assert sync_interceptor.get_request().headers["Authorization"] == "Bearer shared-token"
+
+        client2.search("query2")
+        assert sync_interceptor.get_request().headers["Authorization"] == "Bearer shared-token"
+
+        # Closing one client should not close the shared session
+        client1.close()
+        client2.search("query3")
+        assert sync_interceptor.get_request() is not None
+
+
+# --- Async AsyncTavilyClient tests ---
+
+class TestAsyncCustomClient:
+    def test_default_client_created_when_none_provided(self):
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test")
+        assert not client._external_client
+
+    def test_custom_client_used(self):
+        custom_client = httpx.AsyncClient()
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+        assert client._external_client
+        assert client._client is custom_client
+
+    def test_custom_client_preserves_existing_headers(self):
+        custom_client = httpx.AsyncClient(headers={
+            "Authorization": "Bearer apim-token-123",
+            "X-Custom": "custom-value",
+        })
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+
+        assert client._client.headers["Authorization"] == "Bearer apim-token-123"
+        assert client._client.headers["X-Custom"] == "custom-value"
+        assert client._client.headers["Content-Type"] == "application/json"
+        assert client._client.headers["X-Client-Source"] == "tavily-python"
+
+    def test_custom_client_gets_default_headers_when_empty(self):
+        custom_client = httpx.AsyncClient()
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+
+        assert client._client.headers["Authorization"] == "Bearer tvly-test"
+        assert client._client.headers["Content-Type"] == "application/json"
+
+    def test_custom_client_base_url_set_when_missing(self):
+        custom_client = httpx.AsyncClient()
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+        assert "api.tavily.com" in str(client._client.base_url)
+
+    def test_custom_client_base_url_preserved_when_set(self):
+        custom_client = httpx.AsyncClient(base_url="https://apim.example.com/tavily")
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+        assert "apim.example.com" in str(client._client.base_url)
+
+    def test_close_does_not_close_external_client(self):
+        closed = []
+        custom_client = httpx.AsyncClient()
+
+        async def run():
+            client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+            original_aclose = custom_client.aclose
+
+            async def track_close():
+                closed.append(True)
+                await original_aclose()
+
+            custom_client.aclose = track_close
+            await client.close()
+
+        asyncio.run(run())
+        assert len(closed) == 0
+
+    def test_context_manager_does_not_close_external_client(self):
+        closed = []
+        custom_client = httpx.AsyncClient()
+
+        async def run():
+            original_aclose = custom_client.aclose
+
+            async def track_close():
+                closed.append(True)
+                await original_aclose()
+
+            custom_client.aclose = track_close
+            async with async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client):
+                pass
+
+        asyncio.run(run())
+        assert len(closed) == 0
+
+    def test_custom_client_sends_request(self, async_interceptor):
+        async_interceptor.set_response(200, json={"results": []})
+        custom_client = httpx.AsyncClient(
+            headers={"Authorization": "Bearer apim-token"},
+            base_url="https://api.tavily.com",
+        )
+
+        client = async_tavily.AsyncTavilyClient(api_key="tvly-test", client=custom_client)
+        asyncio.run(client.search("test query"))
+
+        req = async_interceptor.get_request()
+        assert req is not None
+        assert req.headers["Authorization"] == "Bearer apim-token"
+
+    # --- API key validation edge cases ---
+
+    def test_no_api_key_no_client_raises(self, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        with pytest.raises(MissingAPIKeyError):
+            async_tavily.AsyncTavilyClient()
+
+    def test_no_api_key_with_client_allowed(self, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        custom_client = httpx.AsyncClient(
+            headers={"Authorization": "Bearer apim-token"},
+        )
+        client = async_tavily.AsyncTavilyClient(client=custom_client)
+        assert client._client.headers["Authorization"] == "Bearer apim-token"
+
+    def test_no_api_key_with_client_no_auth_header_on_defaults(self, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        custom_client = httpx.AsyncClient()
+        client = async_tavily.AsyncTavilyClient(client=custom_client)
+        # httpx always has headers dict but Authorization shouldn't be added
+        assert "authorization" not in [k.lower() for k in client._client.headers.keys()
+                                        if k.lower() == "authorization"
+                                        and client._client.headers[k].startswith("Bearer None")]
+
+    def test_no_api_key_with_client_sends_request(self, async_interceptor, monkeypatch):
+        monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+        async_interceptor.set_response(200, json={"results": []})
+        custom_client = httpx.AsyncClient(
+            headers={"Authorization": "Bearer apim-token"},
+            base_url="https://api.tavily.com",
+        )
+
+        client = async_tavily.AsyncTavilyClient(client=custom_client)
+        asyncio.run(client.search("test query"))
+
+        req = async_interceptor.get_request()
+        assert req is not None
+        assert req.headers["Authorization"] == "Bearer apim-token"
+
+    def test_custom_client_with_all_endpoints(self, async_interceptor):
+        custom_client = httpx.AsyncClient(
+            headers={"Authorization": "Bearer apim-token"},
+            base_url="https://api.tavily.com",
+        )
+        client = async_tavily.AsyncTavilyClient(client=custom_client)
+
+        # search
+        async_interceptor.set_response(200, json={"results": []})
+        asyncio.run(client.search("test"))
+        assert async_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+        # extract
+        async_interceptor.set_response(200, json={"results": [], "failed_results": []})
+        asyncio.run(client.extract(urls=["https://example.com"]))
+        assert async_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+        # crawl
+        async_interceptor.set_response(200, json={"results": []})
+        asyncio.run(client.crawl(url="https://example.com"))
+        assert async_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+        # map
+        async_interceptor.set_response(200, json={"results": []})
+        asyncio.run(client.map(url="https://example.com"))
+        assert async_interceptor.get_request().headers["Authorization"] == "Bearer apim-token"
+
+    def test_custom_client_project_id_header(self):
+        custom_client = httpx.AsyncClient()
+        client = async_tavily.AsyncTavilyClient(
+            api_key="tvly-test",
+            client=custom_client,
+            project_id="my-project",
+        )
+        assert client._client.headers["X-Project-ID"] == "my-project"

{tavily_python-0.7.21 → tavily_python-0.7.23}/tests/test_search.py

@@ -32,7 +32,7 @@ def validate_specific(request, response):
     assert request.headers["Authorization"] == "Bearer tvly-test"
     assert request.headers["X-Client-Source"] == "tavily-python"
     assert request.timeout == 10
-    
+
     request_json = request.json()
     for key, value in {
         "query": "What is Tavily?",
@@ -44,7 +44,8 @@ def validate_specific(request, response):
         "exclude_domains": ["example.com"],
         "include_answer": "advanced",
         "include_raw_content": True,
-        "include_images": True
+        "include_images": True,
+        "exact_match": True
     }.items():
         assert request_json.get(key) == value
 
@@ -69,6 +70,7 @@ def test_sync_search_specific(sync_interceptor, sync_client):
         include_answer="advanced",
         include_raw_content=True,
         include_images=True,
+        exact_match=True,
         timeout=10
     )
 
@@ -94,8 +96,61 @@ def test_async_search_specific(async_interceptor, async_client):
         include_answer="advanced",
         include_raw_content=True,
         include_images=True,
+        exact_match=True,
         timeout=10
     ))
 
     request = async_interceptor.get_request()
     validate_specific(request, response)
+
+def test_sync_search_exact_match_not_sent_by_default(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_response)
+    sync_client.search("What is Tavily?")
+    request = sync_interceptor.get_request()
+    assert "exact_match" not in request.json()
+
+def test_sync_search_exact_match_true(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_response)
+    sync_client.search("What is Tavily?", exact_match=True)
+    request = sync_interceptor.get_request()
+    assert request.json()["exact_match"] is True
+
+def test_sync_search_exact_match_false(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_response)
+    sync_client.search("What is Tavily?", exact_match=False)
+    request = sync_interceptor.get_request()
+    assert request.json()["exact_match"] is False
+
+def test_async_search_exact_match_not_sent_by_default(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_response)
+    asyncio.run(async_client.search("What is Tavily?"))
+    request = async_interceptor.get_request()
+    assert "exact_match" not in request.json()
+
+def test_async_search_exact_match_true(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_response)
+    asyncio.run(async_client.search("What is Tavily?", exact_match=True))
+    request = async_interceptor.get_request()
+    assert request.json()["exact_match"] is True
+
+def test_async_search_exact_match_false(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_response)
+    asyncio.run(async_client.search("What is Tavily?", exact_match=False))
+    request = async_interceptor.get_request()
+    assert request.json()["exact_match"] is False
+
+def test_sync_search_exact_match_query_quotes_escaped_in_payload(sync_interceptor, sync_client):
+    sync_interceptor.set_response(200, json=dummy_response)
+    sync_client.search('"John Smith" CEO Acme Corp', exact_match=True)
+    request = sync_interceptor.get_request()
+    # The raw JSON payload should have escaped quotes for the quoted phrase
+    assert r'\"John Smith\"' in request.body
+    # But the parsed query should preserve the original quotes
+    assert request.json()["query"] == '"John Smith" CEO Acme Corp'
+
+def test_async_search_exact_match_query_quotes_escaped_in_payload(async_interceptor, async_client):
+    async_interceptor.set_response(200, json=dummy_response)
+    asyncio.run(async_client.search('"John Smith" CEO Acme Corp', exact_match=True))
+    request = async_interceptor.get_request()
+    assert r'\"John Smith\"' in request.body
+    assert request.json()["query"] == '"John Smith" CEO Acme Corp'