diffbot-python 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

diffbot/__init__.py

@@ -2,8 +2,14 @@
 diffbot - Python client library for the Diffbot APIs.
 """
 
-__version__ = "0.1.0"
+from importlib.metadata import PackageNotFoundError, version as _version
 
+try:
+    __version__ = _version("diffbot-python")
+except PackageNotFoundError:  # not installed (e.g. running from a source tree)
+    __version__ = "0.0.0"
+
+from ._auth import resolve_token
 from .client import Diffbot, DiffbotAsync
 from .crawl import CrawlEvent, CrawlEventType
 from .errors import (
@@ -14,12 +20,15 @@ from .errors import (
     RateLimitError,
     ValidationError,
 )
+from .ontology import Ontology
 
 __all__ = [
     "Diffbot",
     "DiffbotAsync",
+    "resolve_token",
     "CrawlEvent",
     "CrawlEventType",
+    "Ontology",
     "DiffbotError",
     "AuthError",
     "ExtractionError",

diffbot/_auth.py

@@ -0,0 +1,41 @@
+"""Shared Diffbot credential resolution for both the library and the CLI.
+
+The same lookup chain is used everywhere so a single credential works for the
+``db`` CLI and any Python script that constructs a client:
+
+1. An explicit token passed to the client / function.
+2. The ``DIFFBOT_API_TOKEN`` environment variable.
+3. A ``DIFFBOT_API_TOKEN=...`` line in ``~/.diffbot/credentials``.
+"""
+
+import os
+import pathlib
+from typing import Optional
+
+TOKEN_ENV_VAR = "DIFFBOT_API_TOKEN"
+CREDENTIALS_PATH = pathlib.Path.home() / ".diffbot" / "credentials"
+
+
+def _read_credentials_file() -> str:
+    if not CREDENTIALS_PATH.exists():
+        return ""
+    for line in CREDENTIALS_PATH.read_text().splitlines():
+        line = line.strip()
+        if line.startswith(f"{TOKEN_ENV_VAR}="):
+            return line[len(TOKEN_ENV_VAR) + 1:].strip()
+    return ""
+
+
+def resolve_token(token: Optional[str] = None) -> str:
+    """Resolve a Diffbot API token from the explicit argument, env var, or file.
+
+    Returns an empty string if no token can be found.
+    """
+    if token and token.strip():
+        return token.strip()
+
+    env_token = os.environ.get(TOKEN_ENV_VAR, "").strip()
+    if env_token:
+        return env_token
+
+    return _read_credentials_file()

diffbot/cli/_common.py

@@ -1,35 +1,20 @@
-import os
-import pathlib
-
 import click
 
-from diffbot import Diffbot
-
-CREDENTIALS_PATH = pathlib.Path.home() / ".diffbot" / "credentials"
-
-
-def resolve_token() -> str:
-    """Return the Diffbot API token from the env var, falling back to ~/.diffbot/credentials."""
-    token = os.environ.get("DIFFBOT_API_TOKEN", "").strip()
-    if token:
-        return token
-
-    if CREDENTIALS_PATH.exists():
-        for line in CREDENTIALS_PATH.read_text().splitlines():
-            line = line.strip()
-            if line.startswith("DIFFBOT_API_TOKEN="):
-                return line[len("DIFFBOT_API_TOKEN="):].strip()
-
-    return ""
+from diffbot import Diffbot, resolve_token
+from diffbot._auth import CREDENTIALS_PATH, TOKEN_ENV_VAR
 
 
 def get_client() -> Diffbot:
+    """Build a Diffbot client using the shared credential resolution chain.
+
+    Looks at the DIFFBOT_API_TOKEN env var, then ~/.diffbot/credentials.
+    """
     token = resolve_token()
     if not token:
         click.echo(
             "Error: no Diffbot API token found.\n"
-            "  Set a DIFFBOT_API_TOKEN environment variable, or\n"
-            f"  write 'DIFFBOT_API_TOKEN=YOUR_TOKEN' to {CREDENTIALS_PATH}",
+            f"  Set a {TOKEN_ENV_VAR} environment variable, or\n"
+            f"  write '{TOKEN_ENV_VAR}=YOUR_TOKEN' to {CREDENTIALS_PATH}",
             err=True,
         )
         raise click.Abort()

diffbot/cli/dql.py

@@ -15,7 +15,9 @@ from rich.table import Table
 from diffbot import DiffbotError
 
 from . import ontology
-from ._common import get_client, resolve_token
+from diffbot import resolve_token
+
+from ._common import get_client
 
 
 class _DqlGroup(click.Group):

diffbot/cli/ontology.py

@@ -1,14 +1,24 @@
+"""CLI-side ontology access: a disk cache over the storage-agnostic core.
+
+The navigation logic lives in :mod:`diffbot.ontology` (the `Ontology` class).
+This module adds the CLI's caching policy on top: the ontology is read once from
+``~/.diffbot/ontology.json`` (populated by `db dql init`) and held in
+``_CACHE``. The module-level functions preserve the historical CLI surface and
+simply delegate to an `Ontology` built from the cached document.
+"""
+
 import json
 import pathlib
-import re
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
+
+from diffbot.ontology import Ontology
 
 ONTOLOGY_PATH = pathlib.Path.home() / ".diffbot" / "ontology.json"
 
 _CACHE: Dict[str, Any] = {}
 
 
-def load() -> Dict[str, Any]:
+def _data() -> Dict[str, Any]:
     if "data" not in _CACHE:
         if not ONTOLOGY_PATH.exists():
             raise FileNotFoundError(
@@ -18,113 +28,47 @@ def load() -> Dict[str, Any]:
     return _CACHE["data"]
 
 
+def _ontology() -> Ontology:
+    return Ontology(_data())
+
+
 def list_types() -> List[str]:
-    return sorted(load().get("types", {}).keys())
+    return _ontology().types()
 
 
 def list_composites() -> List[str]:
-    return sorted(load().get("composites", {}).keys())
+    return _ontology().composites()
 
 
 def list_enums() -> List[str]:
-    return sorted(load().get("enums", {}).keys())
+    return _ontology().enums()
 
 
 def list_taxonomies() -> List[str]:
-    return sorted(load().get("taxonomies", {}).keys())
-
-
-def _fields_of(container: Dict[str, Any], type_name: str) -> Dict[str, Any]:
-    entry = container.get(type_name)
-    if entry is None:
-        raise KeyError(f"Unknown name: {type_name}")
-    return entry.get("fields", {})
+    return _ontology().taxonomies()
 
 
 def fields_for(type_name: str) -> Dict[str, Any]:
-    data = load()
-    types = data.get("types", {})
-    composites = data.get("composites", {})
-    if type_name in types:
-        return _fields_of(types, type_name)
-    if type_name in composites:
-        return _fields_of(composites, type_name)
-    raise KeyError(f"{type_name} is not a known entity type or composite")
+    return _ontology().fields_for(type_name)
 
 
 def format_field(name: str, meta: Dict[str, Any]) -> str:
-    t = meta.get("type", "?")
-    if t == "LinkedEntity":
-        le = meta.get("leType") or []
-        if le:
-            t = f"LinkedEntity ({le[0]})"
-    flags = []
-    if meta.get("isList"):
-        flags.append("isList")
-    if meta.get("isComposite"):
-        flags.append("isComposite")
-    if meta.get("isEnum"):
-        flags.append("isEnum")
-    if meta.get("isDeprecated"):
-        flags.append("DEPRECATED")
-    suffix = "".join(f" [{f}]" for f in flags)
-    return f"{name}: [{t}]{suffix}"
-
-
-def filter_fields(fields: Dict[str, Any], search: Optional[str], include_deprecated: bool = False) -> List[tuple]:
-    pattern = re.compile(search, re.IGNORECASE) if search else None
-    out = []
-    for name, meta in fields.items():
-        if not include_deprecated and meta.get("isDeprecated"):
-            continue
-        if pattern and not pattern.search(name):
-            continue
-        out.append((name, meta))
-    return out
+    return Ontology.format_field(name, meta)
 
 
-def taxonomy_values(name: str, search: Optional[str] = None) -> List[str]:
-    data = load()
-    tax = data.get("taxonomies", {}).get(name)
-    if tax is None:
-        raise KeyError(f"Unknown taxonomy: {name}")
-    pattern = re.compile(search, re.IGNORECASE) if search else None
-    out: List[str] = []
+def filter_fields(
+    fields: Dict[str, Any], search: Optional[str], include_deprecated: bool = False
+) -> List[Tuple[str, Dict[str, Any]]]:
+    return Ontology.filter_fields(fields, search, include_deprecated=include_deprecated)
 
-    def walk(node: Dict[str, Any]) -> None:
-        n = node.get("name")
-        if n and (pattern is None or pattern.search(n)):
-            out.append(n)
-        for child in node.get("children", []) or []:
-            walk(child)
 
-    for cat in tax.get("categories", []) or []:
-        walk(cat)
-    return out
+def taxonomy_values(name: str, search: Optional[str] = None) -> List[str]:
+    return _ontology().taxonomy_values(name, search)
 
 
 def enum_values(name: str) -> List[str]:
-    data = load()
-    enum = data.get("enums", {}).get(name)
-    if enum is None:
-        raise KeyError(f"Unknown enum: {name}")
-    return list(enum.get("values", []))
+    return _ontology().enum_values(name)
 
 
 def find_named(search: str) -> List[str]:
-    pattern = re.compile(search, re.IGNORECASE)
-    found = set()
-
-    def walk(node: Any) -> None:
-        if isinstance(node, dict):
-            n = node.get("name")
-            if isinstance(n, str) and pattern.search(n):
-                found.add(n)
-            for v in node.values():
-                walk(v)
-        elif isinstance(node, list):
-            for v in node:
-                walk(v)
-
-    walk(load())
-    return sorted(found)
+    return _ontology().find_named(search)

diffbot/client.py

@@ -24,9 +24,13 @@ from .crawl import (
 from .kg import (
     dql as _dql,
     dql_async as _dql_async,
+    dql_fetch_ontology as _dql_fetch_ontology,
+    dql_fetch_ontology_async as _dql_fetch_ontology_async,
     dql_parallel as _dql_parallel,
+    dql_parallel_async as _dql_parallel_async,
     dql_refresh_ontology as _dql_refresh_ontology,
 )
+from .ontology import Ontology
 from .web_search import (
     WEB_SEARCH_BASE,
     web_search as _web_search,
@@ -48,8 +52,8 @@ class Diffbot:
     """Client for the Diffbot APIs.
 
     Example:
-        >>> from diffbot import Diffbot
-        >>> db = Diffbot(token=os.getenv("DIFFBOT_API_TOKEN"))
+        >>> from diffbot import Diffbot, resolve_token
+        >>> db = Diffbot(token=resolve_token())  # env var or ~/.diffbot/credentials
         >>> db.extract("https://example.com")
     """
 
@@ -155,6 +159,10 @@ class Diffbot:
         """Download the Diffbot Knowledge Graph ontology and write it to dest."""
         _dql_refresh_ontology(self, dest)
 
+    def dql_fetch_ontology(self) -> Ontology:
+        """Download the ontology and return it as a queryable Ontology (no caching)."""
+        return _dql_fetch_ontology(self)
+
     def web_search(self, text: str, *, num_results: Optional[int] = None, max_tokens: Optional[int] = None) -> Dict[str, Any]:
         """Search the web via the Diffbot LLM web search API."""
         return _web_search(self, text, num_results=num_results, max_tokens=max_tokens)
@@ -272,6 +280,14 @@ class DiffbotAsync:
         """
         return await _dql_async(self, query, size=size, from_=from_, format=format, filter=filter, exportspec=exportspec, extra=extra, raw=raw)
 
+    async def dql_parallel(self, queries: Sequence[Dict[str, Any]], *, workers: int = 8) -> List[Union[Dict[str, Any], bytes]]:
+        """Run multiple DQL queries concurrently. Each item is a dict of dql() keyword args."""
+        return await _dql_parallel_async(self, queries, workers=workers)
+
+    async def dql_fetch_ontology(self) -> Ontology:
+        """Download the ontology and return it as a queryable Ontology (no caching)."""
+        return await _dql_fetch_ontology_async(self)
+
     async def web_search(self, text: str, *, num_results: Optional[int] = None, max_tokens: Optional[int] = None) -> Dict[str, Any]:
         """Search the web via the Diffbot LLM web search API."""
         return await _web_search_async(self, text, num_results=num_results, max_tokens=max_tokens)

diffbot/kg.py

@@ -1,9 +1,12 @@
 """Diffbot Knowledge Graph APIs: DQL search and entity enhancement."""
 
+import asyncio
 import pathlib
 from concurrent.futures import ThreadPoolExecutor
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Union
 
+from .ontology import Ontology
+
 if TYPE_CHECKING:
     from .client import Diffbot, DiffbotAsync
 
@@ -83,8 +86,43 @@ def dql_parallel(
         return list(ex.map(lambda q: dql(client, **q), queries))
 
 
+async def dql_parallel_async(
+    client: "DiffbotAsync",
+    queries: Sequence[Dict[str, Any]],
+    *,
+    workers: int = 8,
+) -> List[Union[Dict[str, Any], bytes]]:
+    if not queries:
+        return []
+    sem = asyncio.Semaphore(workers)
+
+    async def _one(q: Dict[str, Any]) -> Union[Dict[str, Any], bytes]:
+        async with sem:
+            return await dql_async(client, **q)
+
+    return await asyncio.gather(*(_one(q) for q in queries))
+
+
 def dql_refresh_ontology(client: "Diffbot", dest: pathlib.Path) -> None:
     response = client._http.get(KG_ONTOLOGY_ENDPOINT)
     client._raise_for_status(response)
     dest.parent.mkdir(parents=True, exist_ok=True)
     dest.write_bytes(response.content)
+
+
+def dql_fetch_ontology(client: "Diffbot") -> Ontology:
+    """Download the ontology and return it as a queryable :class:`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)
+    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)
+    client._raise_for_status(response)
+    return Ontology.from_json(response.content)

diffbot/ontology.py

@@ -0,0 +1,160 @@
+"""In-memory navigation of the Diffbot Knowledge Graph ontology.
+
+The ontology is a JSON document describing the Knowledge Graph's entity types,
+composite types, enums, and taxonomies. An agent constructing DQL needs it to
+look up real field paths and taxonomy values instead of guessing them.
+
+This module is pure and storage-agnostic: build an :class:`Ontology` from
+already-parsed data (or from raw JSON / a file path) and query it. How the
+ontology document is fetched, and whether or where it is cached, is left
+entirely to the caller — the `db` CLI caches it on disk at
+``~/.diffbot/ontology.json``; an in-process consumer (e.g. langchain) can cache
+the :class:`Ontology` in memory. Fetch a fresh one over HTTP with
+:meth:`diffbot.Diffbot.dql_fetch_ontology`.
+"""
+
+import json
+import pathlib
+import re
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+
+class Ontology:
+    """Queryable view over a parsed Diffbot ontology document.
+
+    The instance holds the parsed document on :attr:`data` and exposes pure
+    lookup methods over it. Nothing here performs I/O — construct with already
+    parsed data, or use :meth:`from_json` / :meth:`from_path` for convenience.
+    """
+
+    def __init__(self, data: Dict[str, Any]):
+        self.data = data
+
+    @classmethod
+    def from_json(cls, raw: Union[str, bytes]) -> "Ontology":
+        """Build from a raw JSON string or bytes (e.g. an HTTP response body)."""
+        return cls(json.loads(raw))
+
+    @classmethod
+    def from_path(cls, path: Union[str, pathlib.Path]) -> "Ontology":
+        """Build from a JSON file on disk."""
+        return cls(json.loads(pathlib.Path(path).read_text()))
+
+    def types(self) -> List[str]:
+        """All entity type names (e.g. ``Organization``, ``Person``)."""
+        return sorted(self.data.get("types", {}).keys())
+
+    def composites(self) -> List[str]:
+        """All composite type names (e.g. ``Location``, ``Employment``)."""
+        return sorted(self.data.get("composites", {}).keys())
+
+    def enums(self) -> List[str]:
+        """All enum type names (e.g. ``Language``, ``Gender``)."""
+        return sorted(self.data.get("enums", {}).keys())
+
+    def taxonomies(self) -> List[str]:
+        """All taxonomy names (e.g. ``OrganizationCategory``)."""
+        return sorted(self.data.get("taxonomies", {}).keys())
+
+    @staticmethod
+    def _fields_of(container: Dict[str, Any], type_name: str) -> Dict[str, Any]:
+        entry = container.get(type_name)
+        if entry is None:
+            raise KeyError(f"Unknown name: {type_name}")
+        return entry.get("fields", {})
+
+    def fields_for(self, type_name: str) -> Dict[str, Any]:
+        """Return the field map of an entity type or composite.
+
+        Auto-routes: ``type_name`` may be an entity type (``Organization``) or a
+        composite (``Location``). Raises ``KeyError`` if it is neither.
+        """
+        types = self.data.get("types", {})
+        composites = self.data.get("composites", {})
+        if type_name in types:
+            return self._fields_of(types, type_name)
+        if type_name in composites:
+            return self._fields_of(composites, type_name)
+        raise KeyError(f"{type_name} is not a known entity type or composite")
+
+    @staticmethod
+    def filter_fields(
+        fields: Dict[str, Any],
+        search: Optional[str],
+        include_deprecated: bool = False,
+    ) -> List[Tuple[str, Dict[str, Any]]]:
+        """Filter a field map by a name regex, dropping deprecated by default."""
+        pattern = re.compile(search, re.IGNORECASE) if search else None
+        out = []
+        for name, meta in fields.items():
+            if not include_deprecated and meta.get("isDeprecated"):
+                continue
+            if pattern and not pattern.search(name):
+                continue
+            out.append((name, meta))
+        return out
+
+    def taxonomy_values(self, name: str, search: Optional[str] = None) -> List[str]:
+        """Flatten a taxonomy's values (recursing into children), optionally filtered."""
+        tax = self.data.get("taxonomies", {}).get(name)
+        if tax is None:
+            raise KeyError(f"Unknown taxonomy: {name}")
+        pattern = re.compile(search, re.IGNORECASE) if search else None
+        out: List[str] = []
+
+        def walk(node: Dict[str, Any]) -> None:
+            n = node.get("name")
+            if n and (pattern is None or pattern.search(n)):
+                out.append(n)
+            for child in node.get("children", []) or []:
+                walk(child)
+
+        for cat in tax.get("categories", []) or []:
+            walk(cat)
+        return out
+
+    def enum_values(self, name: str) -> List[str]:
+        """Return the allowed values of an enum."""
+        enum = self.data.get("enums", {}).get(name)
+        if enum is None:
+            raise KeyError(f"Unknown enum: {name}")
+        return list(enum.get("values", []))
+
+    def find_named(self, search: str) -> List[str]:
+        """Fallback search: every ``name`` anywhere in the document matching a regex."""
+        pattern = re.compile(search, re.IGNORECASE)
+        found = set()
+
+        def walk(node: Any) -> None:
+            if isinstance(node, dict):
+                n = node.get("name")
+                if isinstance(n, str) and pattern.search(n):
+                    found.add(n)
+                for v in node.values():
+                    walk(v)
+            elif isinstance(node, list):
+                for v in node:
+                    walk(v)
+
+        walk(self.data)
+        return sorted(found)
+
+    @staticmethod
+    def format_field(name: str, meta: Dict[str, Any]) -> str:
+        """Render one field as ``<name>: [<type>] [flags...]`` for display."""
+        t = meta.get("type", "?")
+        if t == "LinkedEntity":
+            le = meta.get("leType") or []
+            if le:
+                t = f"LinkedEntity ({le[0]})"
+        flags = []
+        if meta.get("isList"):
+            flags.append("isList")
+        if meta.get("isComposite"):
+            flags.append("isComposite")
+        if meta.get("isEnum"):
+            flags.append("isEnum")
+        if meta.get("isDeprecated"):
+            flags.append("DEPRECATED")
+        suffix = "".join(f" [{f}]" for f in flags)
+        return f"{name}: [{t}]{suffix}"

diffbot/web_search.py

@@ -18,7 +18,7 @@ def web_search(
     headers = {"Authorization": f"Bearer {client.token}"}
     params: Dict[str, Any] = {"text": text}
     if num_results is not None:
-        params["num_results"] = num_results
+        params["size"] = num_results
     if max_tokens is not None:
         params["maxTokens"] = max_tokens
     response = client._http.get(client.web_search_url, headers=headers, params=params)
@@ -36,7 +36,7 @@ async def web_search_async(
     headers = {"Authorization": f"Bearer {client.token}"}
     params: Dict[str, Any] = {"text": text}
     if num_results is not None:
-        params["num_results"] = num_results
+        params["size"] = num_results
     if max_tokens is not None:
         params["maxTokens"] = max_tokens
     response = await client._http.get(client.web_search_url, headers=headers, params=params)

{diffbot_python-0.1.0.dist-info → diffbot_python-0.2.1.dist-info}/METADATA

@@ -1,18 +1,30 @@
 Metadata-Version: 2.4
 Name: diffbot-python
-Version: 0.1.0
+Version: 0.2.1
 Summary: Python client library for Diffbot APIs
 Project-URL: Homepage, https://github.com/diffbot/diffbot-python
+Project-URL: Documentation, https://github.com/diffbot/diffbot-python#readme
 Project-URL: Repository, https://github.com/diffbot/diffbot-python
 Project-URL: Issues, https://github.com/diffbot/diffbot-python/issues
 Author-email: Jerome Choo <jerome@diffbot.com>, Mike Tung <miket@diffbot.com>
 License-Expression: MIT
 License-File: LICENSE
+Keywords: api-client,crawler,diffbot,extract,knowledge-graph,llm,nlp,web-scraping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click>=8.1.0
 Requires-Dist: httpx>=0.27.0
@@ -29,7 +41,7 @@ Python client library for [Diffbot](https://www.diffbot.com) APIs.
 ## Installation
 
 ```bash
-pip install git+https://github.com/diffbot/diffbot-python.git
+python3 -m pip install diffbot-python
 ```
 
 Or, for local development:
@@ -41,12 +53,38 @@ pip install -e ".[dev]"
 ## Usage
 
 ### Authentication
-Set your Diffbot API token in your environment or .env.
+
+The CLI and the library can share a single credential. The token always has to be
+passed to the client explicitly, but `resolve_token()` gives you the same lookup the
+CLI uses, in this order:
+
+1. An explicit token passed to `resolve_token(token)`.
+2. The `DIFFBOT_API_TOKEN` environment variable.
+3. A `DIFFBOT_API_TOKEN=...` line in `~/.diffbot/credentials`.
+
+Set it once and it works for both the CLI and your scripts. Either export it:
 
 ```bash
 export DIFFBOT_API_TOKEN=<TOKEN>
 ```
 
+…or write it to the shared credentials file (handy for keeping it out of your shell environment):
+
+```bash
+mkdir -p ~/.diffbot
+printf 'DIFFBOT_API_TOKEN=%s\n' '<TOKEN>' > ~/.diffbot/credentials
+chmod 600 ~/.diffbot/credentials
+```
+
+With either in place, resolve the token and pass it to the client:
+
+```python
+from diffbot import Diffbot, resolve_token
+
+db = Diffbot(token=resolve_token())  # from env var or ~/.diffbot/credentials
+data = db.extract("https://www.example.com")
+```
+
 ### Extract structured content
 ```python
 from diffbot import Diffbot
@@ -189,7 +227,15 @@ asyncio.run(main())
 
 ## CLI
 
-This library also includes a CLI.
+This library also includes a CLI exposed as the `db` command.
+
+To make `db` available from anywhere, install it as an isolated tool with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install .
+```
+
+This drops a `db` executable into `~/.local/bin` (ensure it is on your `PATH`). Use `--force` to reinstall or upgrade after changes, or `--editable` to have source edits take effect immediately. Alternatively, a plain `pip install .` (or `pip install -e .`) also installs the `db` entry point into the active environment.
 
 ```bash
 export DIFFBOT_API_TOKEN=your-token-here
@@ -212,7 +258,9 @@ Run the mock test suite:
 python -m pytest
 ```
 
-Run live integration tests against the real API (requires a valid token):
+Run live integration tests against the real API (requires a valid token).
+The token is resolved the same way as everywhere else — the `DIFFBOT_API_TOKEN`
+environment variable or `~/.diffbot/credentials`:
 ```bash
-DIFFBOT_TOKEN=your_token python -m pytest -m live
+DIFFBOT_API_TOKEN=your_token python -m pytest -m live
 ```

diffbot_python-0.2.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+diffbot/__init__.py,sha256=OUDi3bVvKowQAQB4m8I4t761ct4pC-3de461qPI4Zok,827
+diffbot/_auth.py,sha256=dzNMWqIjtG3YtRBb_EKpPRiBxvZgogxvoE0ABLvzfOk,1251
+diffbot/ask.py,sha256=iNv613j4CoIfdDTOE-pl9KUkjqI-2AxGDMR1prm3DGM,1853
+diffbot/client.py,sha256=G6vYUEDEaIqjJXcIRxAjwS_cvaXvM7KdQFVMIedkgUY,11315
+diffbot/crawl.py,sha256=iYMFmf7HKrbefJrGg14VnlfiBFLOE_Z1pfO4Rn_cDXc,8893
+diffbot/errors.py,sha256=5-AceX5MyNVUhe9pvR_4rnQQmBhvLfwWmrRl7dRZUSg,1576
+diffbot/extract.py,sha256=R9SVxaOi4FjHOQIX5ho_75OwaJ7VdX-mdAoV_UY-lrM,1452
+diffbot/kg.py,sha256=my-5vR4Vbe3LHzBDYVHLHo99KTtyiRXCT5625glsrlQ,3930
+diffbot/nlp.py,sha256=lZJW4MkjhVklIEM2OBfhc8LvresXTy7RsuImPteYsOA,1153
+diffbot/ontology.py,sha256=GWD5m2rz7ECWY6RrO1TeN3kk3DYTgmEHz6gFKASMvAU,6283
+diffbot/web_search.py,sha256=RSaEK0pdAdLgtilc500Mf2MNmJ1DmiYYmIlBQBWvOpE,1356
+diffbot/cli/__init__.py,sha256=UVGD3uevKTHmqEdbDhhR2PzO6-3i0xu8d7D_94jLLRo,16488
+diffbot/cli/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
+diffbot/cli/_common.py,sha256=_s8WRukzSX3krjJW6HJmT7_3hEjNyv1i_y45tm81b2A,654
+diffbot/cli/dql.py,sha256=iIMaGysMWTScnbAHAdWei2iVUJpMV5lA1pk1E9uQg4s,11439
+diffbot/cli/entities.py,sha256=tsHKexF0b6NnsoUEZJUS2rJidTIE8lt6xrcSenPbwtY,5630
+diffbot/cli/ontology.py,sha256=cLuRQ0KTsOJnFCXdG_zIX9J1ODK8ThPznWVDDEpO1pg,2055
+diffbot_python-0.2.1.dist-info/METADATA,sha256=xNpRnsnbGtPxU-zUAPwozdiHprTBS82zjUD87BMO36U,7402
+diffbot_python-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+diffbot_python-0.2.1.dist-info/entry_points.txt,sha256=FCxJhrbl7VNEsTK7zl7qYvXID7gQ1_wxhiw5_Vllb_M,40
+diffbot_python-0.2.1.dist-info/licenses/LICENSE,sha256=UZlamI1XGeiG0Mit8dsHssNhOuMGKfmNOp5qpf1533w,1063
+diffbot_python-0.2.1.dist-info/RECORD,,

{diffbot_python-0.1.0.dist-info → diffbot_python-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

diffbot_python-0.1.0.dist-info/RECORD

@@ -1,20 +0,0 @@
-diffbot/__init__.py,sha256=WyzW2kAw75vgEmAyvrFkfcu_m0gL8uhOixeYVCKaHf4,518
-diffbot/ask.py,sha256=iNv613j4CoIfdDTOE-pl9KUkjqI-2AxGDMR1prm3DGM,1853
-diffbot/client.py,sha256=C5MIhyx8YZGgD4GjKj5QrIg-eRtUF3qhmUzYW77Sh9Q,10426
-diffbot/crawl.py,sha256=iYMFmf7HKrbefJrGg14VnlfiBFLOE_Z1pfO4Rn_cDXc,8893
-diffbot/errors.py,sha256=5-AceX5MyNVUhe9pvR_4rnQQmBhvLfwWmrRl7dRZUSg,1576
-diffbot/extract.py,sha256=R9SVxaOi4FjHOQIX5ho_75OwaJ7VdX-mdAoV_UY-lrM,1452
-diffbot/kg.py,sha256=Y7XTrPNAfPdX9vvhFmgmU4G4KTF9fwpYkm2Hh3c6DLA,2708
-diffbot/nlp.py,sha256=lZJW4MkjhVklIEM2OBfhc8LvresXTy7RsuImPteYsOA,1153
-diffbot/web_search.py,sha256=1sKBojzsslZj2zzl2kJ4s43AUaRn1i1fGgPUjFdsW6Q,1370
-diffbot/cli/__init__.py,sha256=UVGD3uevKTHmqEdbDhhR2PzO6-3i0xu8d7D_94jLLRo,16488
-diffbot/cli/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
-diffbot/cli/_common.py,sha256=0I-oHnKVM9zLCaVNDc-7qf17b5u827IK7ezXITjsdW4,1006
-diffbot/cli/dql.py,sha256=lJzAEjTIoF1l1xTwMcVIlq36pKZKrvgZYz0RuX5jUGc,11419
-diffbot/cli/entities.py,sha256=tsHKexF0b6NnsoUEZJUS2rJidTIE8lt6xrcSenPbwtY,5630
-diffbot/cli/ontology.py,sha256=FLIIe6ZY34zLHLt_bB9Zci0zlrKEAIIgNSdz5KwXqzw,3773
-diffbot_python-0.1.0.dist-info/METADATA,sha256=KrMqxyqa2g6GPee1zc8A6J1SPXDLukELFslwbuMj9CM,5281
-diffbot_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-diffbot_python-0.1.0.dist-info/entry_points.txt,sha256=FCxJhrbl7VNEsTK7zl7qYvXID7gQ1_wxhiw5_Vllb_M,40
-diffbot_python-0.1.0.dist-info/licenses/LICENSE,sha256=UZlamI1XGeiG0Mit8dsHssNhOuMGKfmNOp5qpf1533w,1063
-diffbot_python-0.1.0.dist-info/RECORD,,