search1api 0.1.0__py3-none-any.whl

search1api/__init__.py

@@ -0,0 +1,38 @@
+from .client import AsyncSearch1API, Search1API
+from .errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    DeepcrawlFailedError,
+    DeepcrawlTimeoutError,
+    InternalServerError,
+    NotFoundError,
+    PaymentRequiredError,
+    RateLimitError,
+    Search1APIConfigurationError,
+    Search1APIError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncSearch1API",
+    "AuthenticationError",
+    "BadRequestError",
+    "DeepcrawlFailedError",
+    "DeepcrawlTimeoutError",
+    "InternalServerError",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "RateLimitError",
+    "Search1API",
+    "Search1APIConfigurationError",
+    "Search1APIError",
+    "UnprocessableEntityError",
+]
+
+__version__ = "0.1.0"

search1api/client.py

@@ -0,0 +1,686 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, List, Mapping, Optional, cast
+from urllib.parse import quote
+
+import httpx
+
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    DeepcrawlFailedError,
+    DeepcrawlTimeoutError,
+    Search1APIConfigurationError,
+    Search1APIError,
+    api_status_error,
+)
+from .types import (
+    BatchResponse,
+    CrawlRequest,
+    CrawlResponse,
+    CrawlType,
+    DeepcrawlAcceptedResponse,
+    DeepcrawlStatusResponse,
+    ExtractResponse,
+    HealthResponse,
+    NewsEngine,
+    NewsRequest,
+    NewsResponse,
+    SearchEngine,
+    SearchRequest,
+    SearchResponse,
+    SitemapResponse,
+    TimeRange,
+    TrendingResponse,
+    UsageResponse,
+)
+
+DEFAULT_BASE_URL = "https://api.search1api.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_RETRY_DELAY = 0.5
+DEFAULT_DEEPCRAWL_POLL_INTERVAL = 2.0
+DEFAULT_DEEPCRAWL_TIMEOUT = 300.0
+
+
+def _compact(payload: Mapping[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def _search_payload(
+    query: str,
+    *,
+    search_service: Optional[str] = None,
+    max_results: Optional[int] = None,
+    crawl_results: Optional[int] = None,
+    image: Optional[bool] = None,
+    include_sites: Optional[List[str]] = None,
+    exclude_sites: Optional[List[str]] = None,
+    language: Optional[str] = None,
+    time_range: Optional[TimeRange] = None,
+) -> Dict[str, Any]:
+    return _compact(
+        {
+            "query": query,
+            "search_service": search_service,
+            "max_results": max_results,
+            "crawl_results": crawl_results,
+            "image": image,
+            "include_sites": include_sites,
+            "exclude_sites": exclude_sites,
+            "language": language,
+            "time_range": time_range,
+        }
+    )
+
+
+def _retry_after(response: httpx.Response) -> Optional[float]:
+    value = response.headers.get("retry-after")
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        try:
+            return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+        except (TypeError, ValueError, OverflowError):
+            return None
+
+
+def _should_retry(status_code: int) -> bool:
+    return status_code == 429 or status_code >= 500
+
+
+def _error_body(response: httpx.Response) -> Mapping[str, Any]:
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, ValueError):
+        return {"message": response.text}
+    return body if isinstance(body, dict) else {"message": response.text}
+
+
+class _ClientConfig:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        *,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        retry_delay: float,
+        headers: Optional[Mapping[str, str]],
+    ) -> None:
+        resolved_key = api_key or os.getenv("SEARCH1API_API_KEY")
+        if not resolved_key:
+            raise Search1APIConfigurationError(
+                "Missing API key. Pass api_key or set SEARCH1API_API_KEY."
+            )
+        if max_retries < 0:
+            raise Search1APIConfigurationError("max_retries cannot be negative")
+        if timeout <= 0:
+            raise Search1APIConfigurationError("timeout must be positive")
+        if retry_delay < 0:
+            raise Search1APIConfigurationError("retry_delay cannot be negative")
+
+        self.api_key: str = resolved_key
+        self.base_url: str = base_url.rstrip("/")
+        self.timeout: float = timeout
+        self.max_retries: int = max_retries
+        self.retry_delay: float = retry_delay
+        self.headers: Dict[str, str] = dict(headers or {})
+
+    def _request_headers(self) -> Dict[str, str]:
+        return {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Search1API-Client": "python/0.1.0",
+            **self.headers,
+        }
+
+    def _retry_sleep(self, attempt: int) -> float:
+        base = self.retry_delay * (2**attempt)
+        return float(base + random.random() * base * 0.25)
+
+
+class Search1API(_ClientConfig):
+    """Synchronous Search1API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+        headers: Optional[Mapping[str, str]] = None,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            headers=headers,
+        )
+        self._client = client or httpx.Client()
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Search1API":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def search(
+        self,
+        query: str,
+        *,
+        search_service: Optional[SearchEngine] = None,
+        max_results: Optional[int] = None,
+        crawl_results: Optional[int] = None,
+        image: Optional[bool] = None,
+        include_sites: Optional[List[str]] = None,
+        exclude_sites: Optional[List[str]] = None,
+        language: Optional[str] = None,
+        time_range: Optional[TimeRange] = None,
+    ) -> SearchResponse:
+        payload = _search_payload(
+            query,
+            search_service=search_service,
+            max_results=max_results,
+            crawl_results=crawl_results,
+            image=image,
+            include_sites=include_sites,
+            exclude_sites=exclude_sites,
+            language=language,
+            time_range=time_range,
+        )
+        return cast(SearchResponse, self._request_json("POST", "/search", json=payload))
+
+    def search_batch(self, requests: List[SearchRequest]) -> BatchResponse:
+        return cast(BatchResponse, self._request_json("POST", "/search", json=requests))
+
+    def news(
+        self,
+        query: str,
+        *,
+        search_service: Optional[NewsEngine] = None,
+        max_results: Optional[int] = None,
+        crawl_results: Optional[int] = None,
+        image: Optional[bool] = None,
+        include_sites: Optional[List[str]] = None,
+        exclude_sites: Optional[List[str]] = None,
+        language: Optional[str] = None,
+        time_range: Optional[TimeRange] = None,
+    ) -> NewsResponse:
+        payload = _search_payload(
+            query,
+            search_service=search_service,
+            max_results=max_results,
+            crawl_results=crawl_results,
+            image=image,
+            include_sites=include_sites,
+            exclude_sites=exclude_sites,
+            language=language,
+            time_range=time_range,
+        )
+        return cast(NewsResponse, self._request_json("POST", "/news", json=payload))
+
+    def news_batch(self, requests: List[NewsRequest]) -> BatchResponse:
+        return cast(BatchResponse, self._request_json("POST", "/news", json=requests))
+
+    def crawl(
+        self, url: str, *, enable_fallback: Optional[bool] = None
+    ) -> CrawlResponse:
+        payload = _compact({"url": url, "enableFallback": enable_fallback})
+        return cast(CrawlResponse, self._request_json("POST", "/crawl", json=payload))
+
+    def crawl_batch(self, requests: List[CrawlRequest]) -> List[CrawlResponse]:
+        return cast(
+            List[CrawlResponse], self._request_json("POST", "/crawl", json=requests)
+        )
+
+    def sitemap(self, url: str, *, type: Optional[CrawlType] = None) -> SitemapResponse:
+        return cast(
+            SitemapResponse,
+            self._request_json(
+                "POST", "/sitemap", json=_compact({"url": url, "type": type})
+            ),
+        )
+
+    def trending(
+        self, search_service: str, *, max_results: Optional[int] = None
+    ) -> TrendingResponse:
+        return cast(
+            TrendingResponse,
+            self._request_json(
+                "POST",
+                "/trending",
+                json=_compact(
+                    {"search_service": search_service, "max_results": max_results}
+                ),
+            ),
+        )
+
+    def extract(
+        self,
+        url: str,
+        *,
+        prompt: Optional[str] = None,
+        response_format: Optional[Mapping[str, Any]] = None,
+    ) -> ExtractResponse:
+        return cast(
+            ExtractResponse,
+            self._request_json(
+                "POST",
+                "/extract",
+                json=_compact(
+                    {"url": url, "prompt": prompt, "response_format": response_format}
+                ),
+            ),
+        )
+
+    def start_deepcrawl(
+        self, url: str, *, type: Optional[CrawlType] = None
+    ) -> DeepcrawlAcceptedResponse:
+        return cast(
+            DeepcrawlAcceptedResponse,
+            self._request_json(
+                "POST",
+                "/deepcrawl",
+                json=_compact({"url": url, "type": type}),
+                retryable=False,
+            ),
+        )
+
+    def get_deepcrawl_status(self, task_id: str) -> DeepcrawlStatusResponse:
+        return cast(
+            DeepcrawlStatusResponse,
+            self._request_json("GET", f"/deepcrawl/status/{quote(task_id, safe='')}"),
+        )
+
+    def wait_for_deepcrawl(
+        self,
+        task_id: str,
+        *,
+        poll_interval: float = DEFAULT_DEEPCRAWL_POLL_INTERVAL,
+        timeout: float = DEFAULT_DEEPCRAWL_TIMEOUT,
+    ) -> DeepcrawlStatusResponse:
+        deadline = time.monotonic() + timeout
+        while True:
+            response = self.get_deepcrawl_status(task_id)
+            if response.get("success") is True or response.get("status") == "completed":
+                return response
+            if response.get("success") is False or response.get("status") in {
+                "failed",
+                "not_found",
+            }:
+                raise DeepcrawlFailedError(response)
+            if time.monotonic() + poll_interval > deadline:
+                raise DeepcrawlTimeoutError(task_id, timeout)
+            time.sleep(poll_interval)
+
+    def deepcrawl(
+        self,
+        url: str,
+        *,
+        type: Optional[CrawlType] = None,
+        poll_interval: float = DEFAULT_DEEPCRAWL_POLL_INTERVAL,
+        timeout: float = DEFAULT_DEEPCRAWL_TIMEOUT,
+    ) -> DeepcrawlStatusResponse:
+        task = self.start_deepcrawl(url, type=type)
+        return self.wait_for_deepcrawl(
+            task["taskId"], poll_interval=poll_interval, timeout=timeout
+        )
+
+    def usage(self, period: Optional[TimeRange] = None) -> UsageResponse:
+        return cast(
+            UsageResponse,
+            self._request_json("GET", "/usage", params=_compact({"period": period})),
+        )
+
+    def health(self) -> HealthResponse:
+        return cast(HealthResponse, self._request_json("GET", "/health"))
+
+    def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = self._request(method, path, **kwargs)
+        try:
+            return response.json()
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise Search1APIError(
+                f"Search1API returned invalid JSON for {path}"
+            ) from exc
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        retryable = bool(kwargs.pop("retryable", True))
+        max_retries = self.max_retries if retryable else 0
+        for attempt in range(max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    headers=self._request_headers(),
+                    timeout=self.timeout,
+                    **kwargs,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt < max_retries:
+                    time.sleep(self._retry_sleep(attempt))
+                    continue
+                raise APITimeoutError(
+                    f"Search1API request timed out after {self.timeout:g}s"
+                ) from exc
+            except httpx.RequestError as exc:
+                if attempt < max_retries:
+                    time.sleep(self._retry_sleep(attempt))
+                    continue
+                raise APIConnectionError("Unable to connect to Search1API") from exc
+
+            if response.is_success:
+                return response
+            if attempt < max_retries and _should_retry(response.status_code):
+                delay = _retry_after(response)
+                time.sleep(delay if delay is not None else self._retry_sleep(attempt))
+                continue
+            raise api_status_error(
+                response.status_code, _error_body(response), response.headers
+            )
+        raise Search1APIError("Search1API request exhausted its retry budget")
+
+
+class AsyncSearch1API(_ClientConfig):
+    """Asynchronous Search1API client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+        headers: Optional[Mapping[str, str]] = None,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+            headers=headers,
+        )
+        self._client = client or httpx.AsyncClient()
+        self._owns_client = client is None
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncSearch1API":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def search(
+        self,
+        query: str,
+        *,
+        search_service: Optional[SearchEngine] = None,
+        max_results: Optional[int] = None,
+        crawl_results: Optional[int] = None,
+        image: Optional[bool] = None,
+        include_sites: Optional[List[str]] = None,
+        exclude_sites: Optional[List[str]] = None,
+        language: Optional[str] = None,
+        time_range: Optional[TimeRange] = None,
+    ) -> SearchResponse:
+        return cast(
+            SearchResponse,
+            await self._request_json(
+                "POST",
+                "/search",
+                json=_search_payload(
+                    query,
+                    search_service=search_service,
+                    max_results=max_results,
+                    crawl_results=crawl_results,
+                    image=image,
+                    include_sites=include_sites,
+                    exclude_sites=exclude_sites,
+                    language=language,
+                    time_range=time_range,
+                ),
+            ),
+        )
+
+    async def search_batch(self, requests: List[SearchRequest]) -> BatchResponse:
+        return cast(
+            BatchResponse,
+            await self._request_json("POST", "/search", json=requests),
+        )
+
+    async def news(
+        self,
+        query: str,
+        *,
+        search_service: Optional[NewsEngine] = None,
+        max_results: Optional[int] = None,
+        crawl_results: Optional[int] = None,
+        image: Optional[bool] = None,
+        include_sites: Optional[List[str]] = None,
+        exclude_sites: Optional[List[str]] = None,
+        language: Optional[str] = None,
+        time_range: Optional[TimeRange] = None,
+    ) -> NewsResponse:
+        return cast(
+            NewsResponse,
+            await self._request_json(
+                "POST",
+                "/news",
+                json=_search_payload(
+                    query,
+                    search_service=search_service,
+                    max_results=max_results,
+                    crawl_results=crawl_results,
+                    image=image,
+                    include_sites=include_sites,
+                    exclude_sites=exclude_sites,
+                    language=language,
+                    time_range=time_range,
+                ),
+            ),
+        )
+
+    async def news_batch(self, requests: List[NewsRequest]) -> BatchResponse:
+        return cast(
+            BatchResponse,
+            await self._request_json("POST", "/news", json=requests),
+        )
+
+    async def crawl(
+        self, url: str, *, enable_fallback: Optional[bool] = None
+    ) -> CrawlResponse:
+        return cast(
+            CrawlResponse,
+            await self._request_json(
+                "POST",
+                "/crawl",
+                json=_compact({"url": url, "enableFallback": enable_fallback}),
+            ),
+        )
+
+    async def crawl_batch(self, requests: List[CrawlRequest]) -> List[CrawlResponse]:
+        return cast(
+            List[CrawlResponse],
+            await self._request_json("POST", "/crawl", json=requests),
+        )
+
+    async def sitemap(
+        self, url: str, *, type: Optional[CrawlType] = None
+    ) -> SitemapResponse:
+        return cast(
+            SitemapResponse,
+            await self._request_json(
+                "POST", "/sitemap", json=_compact({"url": url, "type": type})
+            ),
+        )
+
+    async def trending(
+        self, search_service: str, *, max_results: Optional[int] = None
+    ) -> TrendingResponse:
+        return cast(
+            TrendingResponse,
+            await self._request_json(
+                "POST",
+                "/trending",
+                json=_compact(
+                    {"search_service": search_service, "max_results": max_results}
+                ),
+            ),
+        )
+
+    async def extract(
+        self,
+        url: str,
+        *,
+        prompt: Optional[str] = None,
+        response_format: Optional[Mapping[str, Any]] = None,
+    ) -> ExtractResponse:
+        return cast(
+            ExtractResponse,
+            await self._request_json(
+                "POST",
+                "/extract",
+                json=_compact(
+                    {"url": url, "prompt": prompt, "response_format": response_format}
+                ),
+            ),
+        )
+
+    async def start_deepcrawl(
+        self, url: str, *, type: Optional[CrawlType] = None
+    ) -> DeepcrawlAcceptedResponse:
+        return cast(
+            DeepcrawlAcceptedResponse,
+            await self._request_json(
+                "POST",
+                "/deepcrawl",
+                json=_compact({"url": url, "type": type}),
+                retryable=False,
+            ),
+        )
+
+    async def get_deepcrawl_status(self, task_id: str) -> DeepcrawlStatusResponse:
+        return cast(
+            DeepcrawlStatusResponse,
+            await self._request_json(
+                "GET", f"/deepcrawl/status/{quote(task_id, safe='')}"
+            ),
+        )
+
+    async def wait_for_deepcrawl(
+        self,
+        task_id: str,
+        *,
+        poll_interval: float = DEFAULT_DEEPCRAWL_POLL_INTERVAL,
+        timeout: float = DEFAULT_DEEPCRAWL_TIMEOUT,
+    ) -> DeepcrawlStatusResponse:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while True:
+            response = await self.get_deepcrawl_status(task_id)
+            if response.get("success") is True or response.get("status") == "completed":
+                return response
+            if response.get("success") is False or response.get("status") in {
+                "failed",
+                "not_found",
+            }:
+                raise DeepcrawlFailedError(response)
+            if loop.time() + poll_interval > deadline:
+                raise DeepcrawlTimeoutError(task_id, timeout)
+            await asyncio.sleep(poll_interval)
+
+    async def deepcrawl(
+        self,
+        url: str,
+        *,
+        type: Optional[CrawlType] = None,
+        poll_interval: float = DEFAULT_DEEPCRAWL_POLL_INTERVAL,
+        timeout: float = DEFAULT_DEEPCRAWL_TIMEOUT,
+    ) -> DeepcrawlStatusResponse:
+        task = await self.start_deepcrawl(url, type=type)
+        return await self.wait_for_deepcrawl(
+            task["taskId"], poll_interval=poll_interval, timeout=timeout
+        )
+
+    async def usage(self, period: Optional[TimeRange] = None) -> UsageResponse:
+        return cast(
+            UsageResponse,
+            await self._request_json(
+                "GET", "/usage", params=_compact({"period": period})
+            ),
+        )
+
+    async def health(self) -> HealthResponse:
+        return cast(HealthResponse, await self._request_json("GET", "/health"))
+
+    async def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        response = await self._request(method, path, **kwargs)
+        try:
+            return response.json()
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise Search1APIError(
+                f"Search1API returned invalid JSON for {path}"
+            ) from exc
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        retryable = bool(kwargs.pop("retryable", True))
+        max_retries = self.max_retries if retryable else 0
+        for attempt in range(max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    f"{self.base_url}{path}",
+                    headers=self._request_headers(),
+                    timeout=self.timeout,
+                    **kwargs,
+                )
+            except httpx.TimeoutException as exc:
+                if attempt < max_retries:
+                    await asyncio.sleep(self._retry_sleep(attempt))
+                    continue
+                raise APITimeoutError(
+                    f"Search1API request timed out after {self.timeout:g}s"
+                ) from exc
+            except httpx.RequestError as exc:
+                if attempt < max_retries:
+                    await asyncio.sleep(self._retry_sleep(attempt))
+                    continue
+                raise APIConnectionError("Unable to connect to Search1API") from exc
+
+            if response.is_success:
+                return response
+            if attempt < max_retries and _should_retry(response.status_code):
+                delay = _retry_after(response)
+                await asyncio.sleep(
+                    delay if delay is not None else self._retry_sleep(attempt)
+                )
+                continue
+            raise api_status_error(
+                response.status_code, _error_body(response), response.headers
+            )
+        raise Search1APIError("Search1API request exhausted its retry budget")

search1api/errors.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class Search1APIError(Exception):
+    """Base exception for the Search1API SDK."""
+
+
+class Search1APIConfigurationError(Search1APIError):
+    pass
+
+
+class APIConnectionError(Search1APIError):
+    pass
+
+
+class APITimeoutError(APIConnectionError):
+    pass
+
+
+class APIStatusError(Search1APIError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.headers = headers or {}
+        self.request_id = self.headers.get("x-request-id")
+
+
+class BadRequestError(APIStatusError):
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    pass
+
+
+class PaymentRequiredError(APIStatusError):
+    pass
+
+
+class NotFoundError(APIStatusError):
+    pass
+
+
+class UnprocessableEntityError(APIStatusError):
+    pass
+
+
+class RateLimitError(APIStatusError):
+    pass
+
+
+class InternalServerError(APIStatusError):
+    pass
+
+
+class DeepcrawlFailedError(Search1APIError):
+    def __init__(self, response: Mapping[str, Any]) -> None:
+        task_id = response.get("taskId", "unknown")
+        message = (
+            response.get("error")
+            or response.get("message")
+            or f"Deepcrawl task {task_id} failed"
+        )
+        super().__init__(str(message))
+        self.response = response
+
+
+class DeepcrawlTimeoutError(Search1APIError):
+    def __init__(self, task_id: str, timeout: float) -> None:
+        super().__init__(f"Deepcrawl task {task_id} did not finish within {timeout:g}s")
+        self.task_id = task_id
+
+
+def api_status_error(
+    status_code: int,
+    body: Optional[Mapping[str, Any]],
+    headers: Mapping[str, str],
+) -> APIStatusError:
+    body = body or {}
+    message = (
+        body.get("message")
+        or body.get("detail")
+        or body.get("error")
+        or body.get("title")
+        or f"Search1API request failed with status {status_code}"
+    )
+    error_class = {
+        400: BadRequestError,
+        401: AuthenticationError,
+        402: PaymentRequiredError,
+        404: NotFoundError,
+        422: UnprocessableEntityError,
+        429: RateLimitError,
+    }.get(status_code, InternalServerError if status_code >= 500 else APIStatusError)
+    return error_class(
+        str(message), status_code=status_code, body=body, headers=headers
+    )

search1api/py.typed

@@ -0,0 +1 @@
+

search1api/types.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+JsonPrimitive = Union[bool, float, int, str, None]
+JsonValue = Union[JsonPrimitive, List["JsonValue"], Dict[str, "JsonValue"]]
+TimeRange = Literal["day", "week", "month", "year"]
+SearchEngine = Literal[
+    "google",
+    "bing",
+    "duckduckgo",
+    "yahoo",
+    "youtube",
+    "x",
+    "reddit",
+    "github",
+    "arxiv",
+    "wechat",
+    "bilibili",
+    "imdb",
+    "wikipedia",
+    "sogou",
+    "baidu",
+    "360",
+    "quark",
+]
+NewsEngine = Literal["google", "bing", "duckduckgo", "yahoo", "hackernews", "reuters"]
+CrawlType = Literal["sitemap", "all"]
+
+
+class SearchRequestRequired(TypedDict):
+    query: str
+
+
+class SearchRequest(SearchRequestRequired, total=False):
+    search_service: SearchEngine
+    max_results: int
+    crawl_results: int
+    image: bool
+    include_sites: List[str]
+    exclude_sites: List[str]
+    language: str
+    time_range: TimeRange
+
+
+class SearchResultRequired(TypedDict):
+    title: str
+    link: str
+    snippet: str
+
+
+class SearchResult(SearchResultRequired, total=False):
+    content: str
+
+
+class SearchResponseRequired(TypedDict):
+    searchParameters: SearchRequest
+    results: List[SearchResult]
+
+
+class SearchResponse(SearchResponseRequired, total=False):
+    images: List[str]
+
+
+NewsResponse = SearchResponse
+
+
+class NewsRequestRequired(TypedDict):
+    query: str
+
+
+class NewsRequest(NewsRequestRequired, total=False):
+    search_service: NewsEngine
+    max_results: int
+    crawl_results: int
+    image: bool
+    include_sites: List[str]
+    exclude_sites: List[str]
+    language: str
+    time_range: TimeRange
+
+
+class BatchItemRequired(TypedDict):
+    success: bool
+    cost: int
+
+
+class BatchItem(BatchItemRequired, total=False):
+    data: SearchResponse
+    error: Dict[str, Any]
+
+
+class BatchSummary(TypedDict):
+    total: int
+    successful: int
+    failed: int
+    totalCost: int
+
+
+class BatchResponse(TypedDict):
+    results: List[BatchItem]
+    summary: BatchSummary
+
+
+class CrawlRequestRequired(TypedDict):
+    url: str
+
+
+class CrawlRequest(CrawlRequestRequired, total=False):
+    enableFallback: bool
+
+
+class CrawlResultRequired(TypedDict):
+    title: str
+    link: str
+    content: str
+
+
+class CrawlResult(CrawlResultRequired, total=False):
+    metadata: Dict[str, Any]
+
+
+class CrawlResponse(TypedDict):
+    crawlParameters: Dict[str, str]
+    results: CrawlResult
+
+
+class SitemapResponse(TypedDict):
+    links: List[str]
+
+
+class TrendingResult(TypedDict, total=False):
+    title: str
+    url: str
+    description: Optional[str]
+
+
+class TrendingResponse(TypedDict):
+    trendingParameters: Dict[str, Any]
+    results: List[TrendingResult]
+
+
+class ExtractResponse(TypedDict):
+    success: bool
+    extractParameters: Dict[str, str]
+    results: Any
+
+
+class DeepcrawlAcceptedResponse(TypedDict):
+    taskId: str
+    status: str
+
+
+class DeepcrawlStatusResponseRequired(TypedDict):
+    taskId: str
+
+
+class DeepcrawlStatusResponse(DeepcrawlStatusResponseRequired, total=False):
+    status: str
+    success: bool
+    message: str
+    error: Optional[str]
+    r2Key: str
+    zipUrl: Optional[str]
+
+
+class UsageResponse(TypedDict):
+    usage: int
+    user_id: Optional[str]
+    credential_type: str
+    client_id: Optional[str]
+
+
+class HealthResponseRequired(TypedDict):
+    status: str
+
+
+class HealthResponse(HealthResponseRequired, total=False):
+    timestamp: str
+    version: str

search1api-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: search1api
+Version: 0.1.0
+Summary: Official Python client for Search1API
+Project-URL: Documentation, https://www.search1api.com/docs/integrations/sdks
+Project-URL: Repository, https://github.com/superagents-lab/search1api-python
+Project-URL: Issues, https://github.com/superagents-lab/search1api-python/issues
+Author: Search1API
+License: MIT License
+        
+        Copyright (c) 2026 Search1API
+        
+        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.
+        
+License-File: LICENSE
+Keywords: ai,api,crawl,sdk,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.14; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Search1API Python SDK
+
+Official synchronous and asynchronous Python clients for Search1API.
+
+API documentation: [search1api.com/docs](https://www.search1api.com/docs)
+
+## Install
+
+```bash
+pip install search1api
+```
+
+## Search
+
+```python
+from search1api import Search1API
+
+client = Search1API()  # reads SEARCH1API_API_KEY
+response = client.search(
+    "latest AI agent frameworks",
+    max_results=10,
+    crawl_results=3,
+)
+
+for result in response["results"]:
+    print(result["title"], result["link"])
+```
+
+Use the client as a context manager when it owns the HTTP connection pool:
+
+```python
+with Search1API("your-api-key") as client:
+    print(client.usage())
+```
+
+## Async
+
+```python
+from search1api import AsyncSearch1API
+
+async with AsyncSearch1API() as client:
+    response = await client.search("latest AI agent frameworks")
+```
+
+## Deepcrawl
+
+`deepcrawl` starts a task and waits for it to finish:
+
+```python
+result = client.deepcrawl("https://example.com", type="all")
+print(result["zipUrl"])
+```
+
+Use `start_deepcrawl`, `get_deepcrawl_status`, and `wait_for_deepcrawl` when
+the application needs to control persistence or polling itself.
+
+The clients also support news, crawl, sitemap, trending, extract, usage, and
+batch operations exposed by the Search1API HTTP API. Requests time out after
+30 seconds and retry `429` and transient `5xx` responses twice by default.
+Authentication, payment, and validation errors are never retried. Deepcrawl
+task creation is not retried automatically because it is not idempotent.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+ruff format --check .
+ruff check .
+mypy src/search1api
+pytest
+python -m build
+```
+
+The checked-in OpenAPI snapshot is used to verify that the client covers every
+public operation.
+
+## License
+
+MIT

search1api-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+search1api/__init__.py,sha256=QrwqbTlbyGV3VDjCcCjEHdNJm_sY_n1NTDsUK9EcSrE,857
+search1api/client.py,sha256=LqICwme7-h9uCn8dcPfMTEw4Sc0JQiHnU68Rq1dc5kA,23018
+search1api/errors.py,sha256=pkrzglctP5nS5xi1WVPoCD2XfJ383p1Voae817Wm-QI,2532
+search1api/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+search1api/types.py,sha256=xHCnykgpuejv33bwrw-h9AooC_NdGAjD4cdo_RbPcdY,3447
+search1api-0.1.0.dist-info/METADATA,sha256=e98Fq5KRJH0Ffi_2SVAbfylQWwGDfhvzfsDO8HRnf54,4196
+search1api-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+search1api-0.1.0.dist-info/licenses/LICENSE,sha256=fOUw4rbziXxGWo6j89XSpLgYuXQPAQw3WjZpG1ezHyc,1068
+search1api-0.1.0.dist-info/RECORD,,

search1api-0.1.0.dist-info/WHEEL

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

search1api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Search1API
+
+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.
+