Make DQL and ontology endpoints configurable on the client

Add dql_url and ontology_url to Diffbot and DiffbotAsync, matching the
dqlUrl/ontologyUrl options in @diffbot/typescript. kg.py now reads the
endpoints from the client instead of module constants, which remain the
defaults. Document all client options in a README "Client configuration"
section and cover its examples in test_readme_examples.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: shixish

README.md

@@ -58,6 +58,49 @@ db = Diffbot(token=resolve_token())  # from env var or ~/.diffbot/credentials
 data = db.extract("https://www.example.com")
 ```
 
+### Client configuration
+
+`Diffbot` and `DiffbotAsync` take the same keyword arguments — the client is the single
+place to configure the SDK.
+
+| Argument | Default | Used by |
+|----------|---------|---------|
+| `token` | — (required) | all |
+| `timeout` | `30.0` (seconds) | all |
+| `transport` | httpx default | all |
+| `analyze_url` | `https://api.diffbot.com/v3` | `extract` |
+| `crawler_url` | `https://api.diffbot.com/v3/crawl` | `crawl`, `crawl_list_jobs`, `crawl_get_job`, `crawl_delete_job` |
+| `llm_url` | `https://llm.diffbot.com/rag/v1/chat/completions` | `ask`, `ask_json` |
+| `web_search_url` | `https://llm.diffbot.com/api/v1/web_search` | `web_search` |
+| `nlp_url` | `https://nl.diffbot.com/v1/` | `entities` |
+| `dql_url` | `https://kg.diffbot.com/kg/v3/dql` | `dql`, `dql_parallel` |
+| `ontology_url` | `https://kg.diffbot.com/kg/ontology` | `dql_fetch_ontology`, `dql_refresh_ontology` |
+
+```python
+from diffbot import Diffbot
+
+db = Diffbot(
+    token="YOUR_TOKEN",
+    timeout=60.0,
+    dql_url="http://localhost:8080/kg/v3/dql",
+)
+```
+
+`analyze_url` is a base the SDK appends `/{api}` to, and `crawler_url` is used as given
+for job management and with `/data` appended for crawl results. The rest are complete
+endpoints, used as given.
+
+Passing `transport` replaces the httpx transport, which is the hook for retries, proxies,
+or mocking in tests. `Diffbot` takes an `httpx.BaseTransport`, `DiffbotAsync` an
+`httpx.AsyncBaseTransport`:
+
+```python
+import httpx
+from diffbot import Diffbot
+
+db = Diffbot(token="YOUR_TOKEN", transport=httpx.HTTPTransport(retries=3))
+```
+
 ### Extract structured content
 ```python
 from diffbot import Diffbot

src/diffbot/client.py

@@ -27,6 +27,8 @@
     crawl_list_jobs_async as _crawl_list_jobs_async,
 )
 from .kg import (
+    KG_DQL_ENDPOINT,
+    KG_ONTOLOGY_ENDPOINT,
     dql as _dql,
     dql_async as _dql_async,
     dql_fetch_ontology as _dql_fetch_ontology,
@@ -72,6 +74,8 @@ def __init__(
         crawler_url: str = CRAWL_BASE,
         web_search_url: str = WEB_SEARCH_BASE,
         nlp_url: str = NLP_BASE,
+        dql_url: str = KG_DQL_ENDPOINT,
+        ontology_url: str = KG_ONTOLOGY_ENDPOINT,
         transport: Optional[httpx.BaseTransport] = None,
     ):
         if not token:
@@ -82,6 +86,8 @@ def __init__(
         self.crawler_url = crawler_url
         self.web_search_url = web_search_url
         self.nlp_url = nlp_url
+        self.dql_url = dql_url
+        self.ontology_url = ontology_url
         self._http = httpx.Client(
             timeout=timeout,
             headers={"User-Agent": f"diffbot-python/{__version__}"},
@@ -222,6 +228,8 @@ def __init__(
         crawler_url: str = CRAWL_BASE,
         web_search_url: str = WEB_SEARCH_BASE,
         nlp_url: str = NLP_BASE,
+        dql_url: str = KG_DQL_ENDPOINT,
+        ontology_url: str = KG_ONTOLOGY_ENDPOINT,
         transport: Optional[httpx.AsyncBaseTransport] = None,
     ):
         if not token:
@@ -232,6 +240,8 @@ def __init__(
         self.crawler_url = crawler_url
         self.web_search_url = web_search_url
         self.nlp_url = nlp_url
+        self.dql_url = dql_url
+        self.ontology_url = ontology_url
         self._http = httpx.AsyncClient(
             timeout=timeout,
             headers={"User-Agent": f"diffbot-python/{__version__}"},

src/diffbot/kg.py

@@ -51,7 +51,7 @@ def dql(
     raw: bool = False,
 ) -> Union[Dict[str, Any], bytes]:
     params = _build_dql_params(client, query, size, from_, format, filter, exportspec, extra)
-    response = client._http.get(KG_DQL_ENDPOINT, params=params)
+    response = client._http.get(client.dql_url, params=params)
     client._raise_for_status(response)
     return response.content if raw else response.json()
 
@@ -69,7 +69,7 @@ async def dql_async(
     raw: bool = False,
 ) -> Union[Dict[str, Any], bytes]:
     params = _build_dql_params(client, query, size, from_, format, filter, exportspec, extra)
-    response = await client._http.get(KG_DQL_ENDPOINT, params=params)
+    response = await client._http.get(client.dql_url, params=params)
     client._raise_for_status(response)
     return response.content if raw else response.json()
 
@@ -104,7 +104,7 @@ async def _one(q: Dict[str, Any]) -> Union[Dict[str, Any], bytes]:
 
 
 def dql_refresh_ontology(client: "Diffbot", dest: pathlib.Path) -> None:
-    response = client._http.get(KG_ONTOLOGY_ENDPOINT)
+    response = client._http.get(client.ontology_url)
     client._raise_for_status(response)
     dest.parent.mkdir(parents=True, exist_ok=True)
     dest.write_bytes(response.content)
@@ -116,13 +116,13 @@ def dql_fetch_ontology(client: "Diffbot") -> Ontology:
     Performs no caching — the caller decides whether and where to hold onto the
     result. Use :func:`dql_refresh_ontology` instead to persist raw bytes to disk.
     """
-    response = client._http.get(KG_ONTOLOGY_ENDPOINT)
+    response = client._http.get(client.ontology_url)
     client._raise_for_status(response)
     return Ontology.from_json(response.content)
 
 
 async def dql_fetch_ontology_async(client: "DiffbotAsync") -> Ontology:
     """Async variant of :func:`dql_fetch_ontology`."""
-    response = await client._http.get(KG_ONTOLOGY_ENDPOINT)
+    response = await client._http.get(client.ontology_url)
     client._raise_for_status(response)
     return Ontology.from_json(response.content)

tests/test_dql.py

@@ -1,5 +1,91 @@
+import httpx
 import pytest
 
+from diffbot import Diffbot, DiffbotAsync
+
+
+"""
+Endpoint configuration
+"""
+
+
+def test_dql_defaults_to_public_endpoint():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url).startswith("https://kg.diffbot.com/kg/v3/dql")
+        return httpx.Response(200, json={"data": []})
+
+    db = Diffbot(token="test-token", transport=httpx.MockTransport(handler))
+    db.dql("type:Organization")
+
+
+def test_dql_honors_custom_dql_url():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url).startswith("http://localhost:8080/kg/v3/dql")
+        return httpx.Response(200, json={"data": []})
+
+    db = Diffbot(
+        token="test-token",
+        dql_url="http://localhost:8080/kg/v3/dql",
+        transport=httpx.MockTransport(handler),
+    )
+    db.dql("type:Organization")
+
+
+def test_dql_parallel_honors_custom_dql_url():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url).startswith("http://localhost:8080/kg/v3/dql")
+        return httpx.Response(200, json={"hits": 1})
+
+    db = Diffbot(
+        token="test-token",
+        dql_url="http://localhost:8080/kg/v3/dql",
+        transport=httpx.MockTransport(handler),
+    )
+    results = db.dql_parallel([{"query": "type:Organization", "size": 0}] * 2)
+    assert results == [{"hits": 1}, {"hits": 1}]
+
+
+def test_ontology_honors_custom_ontology_url():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url) == "http://localhost:8080/kg/ontology"
+        return httpx.Response(200, json={"types": {"Organization": {"fields": {}}}})
+
+    db = Diffbot(
+        token="test-token",
+        ontology_url="http://localhost:8080/kg/ontology",
+        transport=httpx.MockTransport(handler),
+    )
+    assert db.dql_fetch_ontology().types() == ["Organization"]
+
+
+@pytest.mark.anyio
+async def test_async_dql_honors_custom_dql_url():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url).startswith("http://localhost:8080/kg/v3/dql")
+        return httpx.Response(200, json={"data": []})
+
+    db = DiffbotAsync(
+        token="test-token",
+        dql_url="http://localhost:8080/kg/v3/dql",
+        transport=httpx.MockTransport(handler),
+    )
+    await db.dql("type:Organization")
+
+
+@pytest.mark.anyio
+async def test_async_ontology_honors_custom_ontology_url():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url) == "http://localhost:8080/kg/ontology"
+        return httpx.Response(200, json={"types": {"Person": {"fields": {}}}})
+
+    db = DiffbotAsync(
+        token="test-token",
+        ontology_url="http://localhost:8080/kg/ontology",
+        transport=httpx.MockTransport(handler),
+    )
+    ont = await db.dql_fetch_ontology()
+    assert ont.types() == ["Person"]
+
 
 """
 Live

tests/test_readme_examples.py

@@ -23,6 +23,31 @@
 )
 
 
+# ---------------------------------------------------------------------------
+# Client configuration
+# ---------------------------------------------------------------------------
+
+def test_readme_client_configuration_custom_dql_url():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert str(request.url).startswith("http://localhost:8080/kg/v3/dql")
+        return httpx.Response(200, json={"data": [{"entity": {"name": "Diffbot"}}]})
+
+    db = Diffbot(
+        token="YOUR_TOKEN",
+        timeout=60.0,
+        dql_url="http://localhost:8080/kg/v3/dql",
+        transport=httpx.MockTransport(handler),
+    )
+    results = db.dql('type:Organization name:"Diffbot"')
+    assert "data" in results
+
+
+def test_readme_client_configuration_transport():
+    transport = httpx.HTTPTransport(retries=3)
+    with Diffbot(token="YOUR_TOKEN", transport=transport) as db:
+        assert db._http._transport is transport
+
+
 # ---------------------------------------------------------------------------
 # Sync Usage
 # ---------------------------------------------------------------------------