crawlora-duckduckgo 0.1.0__tar.gz

crawlora_duckduckgo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crawlora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crawlora_duckduckgo-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: crawlora-duckduckgo
+Version: 0.1.0
+Summary: Typed DuckDuckGo client for the Crawlora hosted API
+Author: Crawlora
+License-Expression: MIT
+Project-URL: Homepage, https://crawlora.net/?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-homepage
+Project-URL: Documentation, https://crawlora.net/docs?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-api-docs
+Project-URL: Repository, https://github.com/Crawlora-org/crawlora-duckduckgo
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.7; python_version < "3.11"
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == "async"
+Provides-Extra: test
+Requires-Dist: mypy>=1.11; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# crawlora-duckduckgo
+
+Python client for Crawlora's hosted DuckDuckGo API. It calls Crawlora's
+service at [Crawlora](https://crawlora.net/?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-homepage); it does not run a browser or scrape
+DuckDuckGo locally. A Crawlora account and `CRAWLORA_API_KEY` are required,
+and API use is billed under your Crawlora account. Crawlora is independent from and not endorsed by
+DuckDuckGo or its owners.
+
+## Install
+
+```sh
+python -m pip install crawlora-duckduckgo
+```
+
+## Get an API key
+
+Create an account at [crawlora.net](https://crawlora.net/signup?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-signup), then open the [Crawlora console](https://crawlora.net/app?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-console) for API-key setup. Set your key in the shell before running the client:
+
+```sh
+export CRAWLORA_API_KEY="your-crawlora-api-key"
+```
+
+## Use
+
+Save this example as `example.py`, then run `python example.py` after installing the package and setting your API key.
+
+```python
+import os
+
+from crawlora_duckduckgo import DuckDuckGoClient
+
+api_key = os.environ.get("CRAWLORA_API_KEY")
+if not api_key:
+    raise RuntimeError("Set CRAWLORA_API_KEY before running this example.")
+
+with DuckDuckGoClient(api_key=api_key) as client:
+    result_1 = client.search(q='open source web crawler')
+    print(result_1)
+    result_2 = client.news(q='technology')
+    print(result_2)
+```
+
+The package also exports `Client` as an alias for `DuckDuckGoClient`. Operation
+methods are available directly in snake_case and through the `duckduckgo`
+group. The async package client is `AsyncDuckDuckGoClient`; see the [online
+endpoint and parameter reference](https://github.com/Crawlora-org/crawlora-duckduckgo/blob/main/docs/usage.md) and [runnable example](https://github.com/Crawlora-org/crawlora-duckduckgo/blob/main/examples/python.py).
+
+### Async usage
+
+The package also exports `AsyncClient` for asynchronous requests:
+
+```python
+import asyncio
+import os
+
+from crawlora_duckduckgo import AsyncClient
+
+async def main():
+    api_key = os.environ.get("CRAWLORA_API_KEY")
+    if not api_key:
+        raise RuntimeError("Set CRAWLORA_API_KEY before running this example.")
+    async with AsyncClient(api_key=api_key) as client:
+        result_1 = await client.search(q='open source web crawler')
+        print(result_1)
+
+asyncio.run(main())
+```
+
+See the [runnable example](https://github.com/Crawlora-org/crawlora-duckduckgo/blob/main/examples/python.py) for a complete usage example.
+
+## Configuration
+
+Pass your key through `api_key` or read `CRAWLORA_API_KEY` from the environment.
+Keep credentials out of source control and logs. Requests go to Crawlora's
+hosted API.

crawlora_duckduckgo-0.1.0/README.md

@@ -0,0 +1,75 @@
+# crawlora-duckduckgo
+
+Python client for Crawlora's hosted DuckDuckGo API. It calls Crawlora's
+service at [Crawlora](https://crawlora.net/?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-homepage); it does not run a browser or scrape
+DuckDuckGo locally. A Crawlora account and `CRAWLORA_API_KEY` are required,
+and API use is billed under your Crawlora account. Crawlora is independent from and not endorsed by
+DuckDuckGo or its owners.
+
+## Install
+
+```sh
+python -m pip install crawlora-duckduckgo
+```
+
+## Get an API key
+
+Create an account at [crawlora.net](https://crawlora.net/signup?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-signup), then open the [Crawlora console](https://crawlora.net/app?utm_source=pypi&utm_medium=referral&utm_campaign=platform-clients&utm_content=duckduckgo-python-console) for API-key setup. Set your key in the shell before running the client:
+
+```sh
+export CRAWLORA_API_KEY="your-crawlora-api-key"
+```
+
+## Use
+
+Save this example as `example.py`, then run `python example.py` after installing the package and setting your API key.
+
+```python
+import os
+
+from crawlora_duckduckgo import DuckDuckGoClient
+
+api_key = os.environ.get("CRAWLORA_API_KEY")
+if not api_key:
+    raise RuntimeError("Set CRAWLORA_API_KEY before running this example.")
+
+with DuckDuckGoClient(api_key=api_key) as client:
+    result_1 = client.search(q='open source web crawler')
+    print(result_1)
+    result_2 = client.news(q='technology')
+    print(result_2)
+```
+
+The package also exports `Client` as an alias for `DuckDuckGoClient`. Operation
+methods are available directly in snake_case and through the `duckduckgo`
+group. The async package client is `AsyncDuckDuckGoClient`; see the [online
+endpoint and parameter reference](https://github.com/Crawlora-org/crawlora-duckduckgo/blob/main/docs/usage.md) and [runnable example](https://github.com/Crawlora-org/crawlora-duckduckgo/blob/main/examples/python.py).
+
+### Async usage
+
+The package also exports `AsyncClient` for asynchronous requests:
+
+```python
+import asyncio
+import os
+
+from crawlora_duckduckgo import AsyncClient
+
+async def main():
+    api_key = os.environ.get("CRAWLORA_API_KEY")
+    if not api_key:
+        raise RuntimeError("Set CRAWLORA_API_KEY before running this example.")
+    async with AsyncClient(api_key=api_key) as client:
+        result_1 = await client.search(q='open source web crawler')
+        print(result_1)
+
+asyncio.run(main())
+```
+
+See the [runnable example](https://github.com/Crawlora-org/crawlora-duckduckgo/blob/main/examples/python.py) for a complete usage example.
+
+## Configuration
+
+Pass your key through `api_key` or read `CRAWLORA_API_KEY` from the environment.
+Keep credentials out of source control and logs. Requests go to Crawlora's
+hosted API.

crawlora_duckduckgo-0.1.0/crawlora_duckduckgo/__init__.py

@@ -0,0 +1,18 @@
+"""Typed DuckDuckGo client for the Crawlora hosted API."""
+
+from .platform import DuckDuckGoClient, AsyncDuckDuckGoClient
+from .client import CrawloraClientError, CrawloraError, CrawloraNetworkError, CrawloraServerError
+from .operations import OPERATION_COUNT, OPERATION_IDS, PLATFORM
+
+Client = DuckDuckGoClient
+AsyncClient = AsyncDuckDuckGoClient
+__version__ = '0.1.0'
+DISPLAY_NAME = 'DuckDuckGo'
+PLATFORM = 'duckduckgo'
+CONTRACT_REVISION = 'sha256:5c59c5ab37b393d0e018ef034c0638d14301e8a02f310239be2ce08110cd77b9'
+
+__all__ = [
+    "DuckDuckGoClient", "AsyncDuckDuckGoClient", "Client", "AsyncClient",
+    "CrawloraError", "CrawloraClientError", "CrawloraServerError", "CrawloraNetworkError",
+    "DISPLAY_NAME", "PLATFORM", "CONTRACT_REVISION", "OPERATION_COUNT", "OPERATION_IDS", "__version__",
+]

crawlora_duckduckgo-0.1.0/crawlora_duckduckgo/__init__.pyi

@@ -0,0 +1,10 @@
+from .platform import DuckDuckGoClient as DuckDuckGoClient
+from .platform import AsyncDuckDuckGoClient as AsyncDuckDuckGoClient
+Client = DuckDuckGoClient
+AsyncClient = AsyncDuckDuckGoClient
+from .client import CrawloraClientError as CrawloraClientError, CrawloraError as CrawloraError, CrawloraNetworkError as CrawloraNetworkError, CrawloraServerError as CrawloraServerError
+from .operations import OPERATION_COUNT as OPERATION_COUNT, OPERATION_IDS as OPERATION_IDS, PLATFORM as PLATFORM
+__version__: str
+DISPLAY_NAME: str
+CONTRACT_REVISION: str
+__all__ = ['DuckDuckGoClient', 'AsyncDuckDuckGoClient', 'Client', 'AsyncClient', 'CrawloraError', 'CrawloraClientError', 'CrawloraServerError', 'CrawloraNetworkError', 'DISPLAY_NAME', 'PLATFORM', 'CONTRACT_REVISION', 'OPERATION_COUNT', 'OPERATION_IDS', '__version__']

crawlora_duckduckgo-0.1.0/crawlora_duckduckgo/_pagination.py

@@ -0,0 +1,44 @@
+"""Shared pagination helpers used by the sync and async clients.
+
+This module deliberately has no `.pyi` stub so type checkers read its inline
+annotations directly (the `client.pyi` stub shadows `client.py`).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+PAGE_PARAM_NAMES = ("page", "offset")
+
+
+def detect_page_param(operation: Mapping[str, Any]) -> str | None:
+    names = {parameter["name"] for parameter in operation.get("queryParams", [])}
+    for candidate in PAGE_PARAM_NAMES:
+        if candidate in names:
+            return candidate
+    return None
+
+
+def page_is_empty(response: Any) -> bool:
+    data = response
+    if isinstance(response, Mapping) and "data" in response:
+        data = response["data"]
+    if data is None:
+        return True
+    if isinstance(data, (list, tuple, dict, str)):
+        return len(data) == 0
+    return not data
+
+
+def default_start(page_param: str) -> int:
+    return 0 if page_param == "offset" else 1
+
+
+def default_items(response: Any) -> list[Any]:
+    """Default item extractor: the response's ``data`` list (Crawlora envelope),
+    or the response itself when it is already a list."""
+    if isinstance(response, Mapping) and isinstance(response.get("data"), list):
+        return list(response["data"])
+    if isinstance(response, list):
+        return list(response)
+    return []

crawlora_duckduckgo-0.1.0/crawlora_duckduckgo/_transport_sync.py

@@ -0,0 +1,114 @@
+"""Keep-alive HTTP transport for the synchronous client (standard library only).
+
+Maintains a small pool of reusable connections per ``(scheme, host, port)`` so
+the sync client avoids a fresh TCP + TLS handshake on every request. Each
+request checks out its own connection, so the transport is safe to use from
+multiple threads (e.g. under ``max_concurrency``). This module is stub-free so
+type checkers read its inline annotations directly.
+
+The transport returns a lightweight response object exposing ``status``,
+``headers`` (a dict), and ``body`` (bytes) — the only fields the client reads.
+"""
+
+from __future__ import annotations
+
+import http.client
+import threading
+from dataclasses import dataclass
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+from urllib.request import Request
+
+
+def _title_case(name: str) -> str:
+    return "-".join(part.capitalize() for part in name.split("-"))
+
+
+@dataclass(frozen=True)
+class _PooledResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+class KeepAliveTransport:
+    """Connection-pooling transport. Drop-in for the urlopen transport: callable
+    as ``transport(request, timeout) -> response``."""
+
+    def __init__(self, max_per_host: int = 8) -> None:
+        self._lock = threading.Lock()
+        self._pools: dict[tuple, list[http.client.HTTPConnection]] = {}
+        self._max_per_host = max_per_host
+
+    def __call__(self, request: Request, timeout: float) -> _PooledResponse:
+        parts = urlsplit(request.full_url)
+        key = (parts.scheme, parts.hostname, parts.port)
+        path = parts.path or "/"
+        if parts.query:
+            path = f"{path}?{parts.query}"
+        method = request.get_method()
+        # Send canonical HTTP title-case header names (matching the urlopen
+        # transport's behavior), so receivers see e.g. "X-Api-Key".
+        headers = {_title_case(name): value for name, value in request.header_items()}
+        body = request.data
+
+        last_exc: Exception | None = None
+        for attempt in range(2):
+            conn = self._checkout(key, parts, timeout)
+            try:
+                conn.request(method, path, body=body, headers=headers)
+                response = conn.getresponse()
+                data = response.read()
+                result = _PooledResponse(response.status, dict(response.getheaders()), data)
+            except (http.client.HTTPException, ConnectionError, OSError) as exc:
+                # Likely a stale pooled connection the server already closed;
+                # discard it and retry once on a fresh connection.
+                last_exc = exc
+                self._close(conn)
+                if attempt == 1:
+                    raise
+                continue
+            if response.will_close:
+                self._close(conn)
+            else:
+                self._checkin(key, conn)
+            return result
+        raise last_exc if last_exc else RuntimeError("keep-alive transport failed")
+
+    def close(self) -> None:
+        with self._lock:
+            pools = list(self._pools.values())
+            self._pools.clear()
+        for pool in pools:
+            for conn in pool:
+                self._close(conn)
+
+    def _checkout(self, key: tuple, parts: Any, timeout: float) -> http.client.HTTPConnection:
+        with self._lock:
+            pool = self._pools.get(key)
+            if pool:
+                conn = pool.pop()
+                conn.timeout = timeout
+                return conn
+        return self._new(parts, timeout)
+
+    def _checkin(self, key: tuple, conn: http.client.HTTPConnection) -> None:
+        with self._lock:
+            pool = self._pools.setdefault(key, [])
+            if len(pool) < self._max_per_host:
+                pool.append(conn)
+                return
+        self._close(conn)
+
+    @staticmethod
+    def _new(parts: Any, timeout: float) -> http.client.HTTPConnection:
+        if parts.scheme == "https":
+            return http.client.HTTPSConnection(parts.hostname, parts.port or 443, timeout=timeout)
+        return http.client.HTTPConnection(parts.hostname, parts.port or 80, timeout=timeout)
+
+    @staticmethod
+    def _close(conn: http.client.HTTPConnection) -> None:
+        try:
+            conn.close()
+        except Exception:
+            pass