scrapeunblocker 0.1.0__py3-none-any.whl

scrapeunblocker/__init__.py

@@ -0,0 +1,47 @@
+"""Official Python client for the ScrapeUnblocker web scraping API.
+
+Basic usage::
+
+    from scrapeunblocker import Client
+
+    su = Client(api_key="su_live_...")          # or set SCRAPEUNBLOCKER_KEY
+    html = su.get_page_source("https://example.com")
+    product = su.get_parsed("https://www.amazon.com/dp/B08N5WRWNW")
+
+See https://developers.scrapeunblocker.com for the full API reference.
+"""
+
+from ._async_client import AsyncClient
+from ._client import Client
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BlockedError,
+    ConnectionError,
+    InvalidRequestError,
+    RateLimitError,
+    ScrapeTimeoutError,
+    ScrapeUnblockerError,
+    ServerError,
+    UpstreamOutageError,
+)
+from .models import PageResult, ParsedPage
+from .version import __version__
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "ParsedPage",
+    "PageResult",
+    "ScrapeUnblockerError",
+    "APIError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "BlockedError",
+    "RateLimitError",
+    "UpstreamOutageError",
+    "ServerError",
+    "ScrapeTimeoutError",
+    "ConnectionError",
+    "__version__",
+]

scrapeunblocker/_async_client.py

@@ -0,0 +1,201 @@
+"""Asynchronous ScrapeUnblocker client (mirror of the sync client)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import _base
+from .exceptions import ConnectionError as SUConnectionError
+from .exceptions import ScrapeTimeoutError
+from .models import PageResult, ParsedPage
+from .version import __version__
+
+
+class _AsyncSkyscannerNamespace:
+    """Skyscanner plugin endpoints (flights, hotels, car hire)."""
+
+    def __init__(self, client: "AsyncClient"):
+        self._c = client
+
+    async def flight_locations(self, q: str, **params: Any) -> Any:
+        return await self._c._post_json("/flights/skyscanner-locations", q=q, **params)
+
+    async def flights(self, **params: Any) -> Any:
+        return await self._c._post_json("/flights/skyscanner-quotes", **params)
+
+    async def hotel_locations(self, q: str, **params: Any) -> Any:
+        return await self._c._post_json("/hotels/skyscanner-locations", q=q, **params)
+
+    async def hotels(self, **params: Any) -> Any:
+        return await self._c._post_json("/hotels/skyscanner-quotes", **params)
+
+    async def carhire_locations(self, q: str, **params: Any) -> Any:
+        return await self._c._post_json("/carhire/skyscanner-locations", q=q, **params)
+
+    async def carhire(self, **params: Any) -> Any:
+        return await self._c._post_json("/carhire/skyscanner-quotes", **params)
+
+
+class AsyncClient:
+    """Async client for the ScrapeUnblocker API.
+
+    Mirrors :class:`~scrapeunblocker.Client`; every method is a coroutine.
+
+    Example:
+        >>> import asyncio
+        >>> from scrapeunblocker import AsyncClient
+        >>> async def main():
+        ...     async with AsyncClient(api_key="su_live_...") as su:
+        ...         html = await su.get_page_source("https://example.com")
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = _base.DEFAULT_BASE_URL,
+        timeout: float = _base.DEFAULT_TIMEOUT,
+        max_retries: int = _base.DEFAULT_MAX_RETRIES,
+    ):
+        self._api_key = _base.resolve_api_key(api_key)
+        self._max_retries = max_retries
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                _base.API_KEY_HEADER: self._api_key,
+                "User-Agent": _base.user_agent(__version__),
+                "Accept": "*/*",
+            },
+        )
+        self.skyscanner = _AsyncSkyscannerNamespace(self)
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, path: str, params: Dict[str, Any]) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.post(path, params=params)
+            except httpx.TimeoutException as exc:
+                raise ScrapeTimeoutError(str(exc)) from exc
+            except httpx.TransportError as exc:
+                if attempt < self._max_retries:
+                    await self._sleep(attempt)
+                    attempt += 1
+                    continue
+                raise SUConnectionError(str(exc)) from exc
+
+            if _base.is_retryable(response.status_code) and attempt < self._max_retries:
+                await self._sleep(attempt)
+                attempt += 1
+                continue
+
+            _base.raise_for_status(response)
+            return response
+
+    @staticmethod
+    async def _sleep(attempt: int) -> None:
+        await asyncio.sleep(min(0.5 * (2 ** attempt), 8.0))
+
+    async def _post_json(self, path: str, **params: Any) -> Any:
+        response = await self._request(path, _base.build_params(**params))
+        return response.json()
+
+    async def get_page_source(
+        self,
+        url: str,
+        *,
+        proxy_country: Optional[str] = None,
+        time_sleep: Optional[int] = None,
+        method: Optional[str] = None,
+        value: Optional[str] = None,
+        method_timeout: Optional[int] = None,
+    ) -> str:
+        """Fetch a URL and return the fully rendered HTML."""
+        params = _base.build_params(
+            url=url,
+            proxy_country=proxy_country,
+            time_sleep=time_sleep,
+            method=method,
+            value=value,
+            method_timeout=method_timeout,
+        )
+        response = await self._request("/getPageSource", params)
+        return response.text
+
+    async def get_parsed(
+        self,
+        url: str,
+        *,
+        refresh_rules: bool = False,
+        rules_hint: Optional[str] = None,
+        proxy_country: Optional[str] = None,
+        time_sleep: Optional[int] = None,
+    ) -> ParsedPage:
+        """Fetch a URL and return structured JSON instead of HTML."""
+        params = _base.build_params(
+            url=url,
+            parsed_data=True,
+            refresh_rules=refresh_rules or None,
+            rules_hint=rules_hint,
+            proxy_country=proxy_country,
+            time_sleep=time_sleep,
+        )
+        response = await self._request("/getPageSource", params)
+        return ParsedPage.from_response(response.json())
+
+    async def get_page_with_cookies(
+        self,
+        url: str,
+        *,
+        proxy_country: Optional[str] = None,
+        time_sleep: Optional[int] = None,
+    ) -> PageResult:
+        """Fetch a URL and also return the cookies and proxy that served it."""
+        params = _base.build_params(
+            url=url,
+            get_cookies=True,
+            proxy_country=proxy_country,
+            time_sleep=time_sleep,
+        )
+        response = await self._request("/getPageSource", params)
+        return PageResult.from_response(response.json())
+
+    async def serp(
+        self,
+        keyword: str,
+        *,
+        proxy_country: Optional[str] = None,
+        pages_to_check: int = 1,
+        wait_after_load: int = 0,
+        captcha_pause: int = 0,
+    ) -> Any:
+        """Run a Google search and return the parsed SERP as JSON."""
+        return await self._post_json(
+            "/serp",
+            keyword=keyword,
+            proxy_country=proxy_country,
+            pages_to_check=pages_to_check,
+            wait_after_load=wait_after_load or None,
+            captcha_pause=captcha_pause or None,
+        )
+
+    async def get_image(
+        self, url: str, *, proxy_country: Optional[str] = None
+    ) -> bytes:
+        """Fetch an image URL through the bypass chain and return its bytes."""
+        params = _base.build_params(url=url, proxy_country=proxy_country)
+        response = await self._request("/getImage", params)
+        return response.content

scrapeunblocker/_base.py

@@ -0,0 +1,109 @@
+"""Shared logic between the sync and async clients.
+
+Keeps request construction, response decoding, error mapping and retry
+decisions in one place so the two client classes stay thin and cannot drift
+apart.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BlockedError,
+    InvalidRequestError,
+    RateLimitError,
+    ScrapeUnblockerError,
+    ServerError,
+    UpstreamOutageError,
+)
+
+DEFAULT_BASE_URL = "https://api.scrapeunblocker.com"
+DEFAULT_TIMEOUT = 180.0
+DEFAULT_MAX_RETRIES = 2
+API_KEY_HEADER = "x-scrapeunblocker-key"
+
+# Status codes worth retrying: transient upstream outage, rate limiting, and
+# generic 5xx. A 400/403 is deterministic - retrying only wastes time.
+_RETRYABLE_STATUS = frozenset({429, 502, 503, 504})
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    """Return the API key, falling back to the SCRAPEUNBLOCKER_KEY env var."""
+    key = api_key or os.environ.get("SCRAPEUNBLOCKER_KEY")
+    if not key:
+        raise ScrapeUnblockerError(
+            "No API key provided. Pass api_key=... or set the "
+            "SCRAPEUNBLOCKER_KEY environment variable. Get your key at "
+            "https://app.scrapeunblocker.com"
+        )
+    return key
+
+
+def build_params(**kwargs: Any) -> Dict[str, Any]:
+    """Drop None values so optional params are simply omitted from the query."""
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+def user_agent(version: str) -> str:
+    return f"scrapeunblocker-python/{version}"
+
+
+def is_retryable(status_code: int) -> bool:
+    return status_code in _RETRYABLE_STATUS
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Map a non-2xx response to the matching typed exception."""
+    if response.is_success:
+        return
+
+    status = response.status_code
+    try:
+        body = response.text
+    except Exception:  # pragma: no cover - defensive
+        body = None
+
+    message = _message_for(status, body)
+
+    if status == 400:
+        raise InvalidRequestError(message, status_code=status, body=body)
+    if status == 401:
+        raise AuthenticationError(message, status_code=status, body=body)
+    if status == 403:
+        raise BlockedError(message, status_code=status, body=body)
+    if status == 429:
+        raise RateLimitError(message, status_code=status, body=body)
+    if status == 503:
+        raise UpstreamOutageError(message, status_code=status, body=body)
+    if status >= 500:
+        raise ServerError(message, status_code=status, body=body)
+    raise APIError(message, status_code=status, body=body)
+
+
+def _message_for(status: int, body: Optional[str]) -> str:
+    snippet = (body or "").strip().replace("\n", " ")
+    if len(snippet) > 200:
+        snippet = snippet[:200] + "..."
+    base = {
+        400: "Invalid request (bad URL or unsupported scheme)",
+        401: "Authentication failed - check your API key",
+        403: "Target blocked by bot protection on every bypass path",
+        429: "Rate limited - too many requests",
+        503: "Upstream origin returned a server-side outage page",
+    }.get(status, f"API returned HTTP {status}")
+    return f"{base}: {snippet}" if snippet else base
+
+
+def decode_page_response(
+    response: httpx.Response, *, want_json: bool
+) -> Any:
+    """Return parsed JSON when the caller asked for it, else the text body."""
+    if want_json:
+        return response.json()
+    return response.text

scrapeunblocker/_client.py

@@ -0,0 +1,248 @@
+"""Synchronous ScrapeUnblocker client."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import _base
+from .exceptions import ConnectionError as SUConnectionError
+from .exceptions import ScrapeTimeoutError
+from .models import PageResult, ParsedPage
+from .version import __version__
+
+
+class _SkyscannerNamespace:
+    """Skyscanner plugin endpoints (flights, hotels, car hire)."""
+
+    def __init__(self, client: "Client"):
+        self._c = client
+
+    def flight_locations(self, q: str, **params: Any) -> Any:
+        return self._c._post_json("/flights/skyscanner-locations", q=q, **params)
+
+    def flights(self, **params: Any) -> Any:
+        return self._c._post_json("/flights/skyscanner-quotes", **params)
+
+    def hotel_locations(self, q: str, **params: Any) -> Any:
+        return self._c._post_json("/hotels/skyscanner-locations", q=q, **params)
+
+    def hotels(self, **params: Any) -> Any:
+        return self._c._post_json("/hotels/skyscanner-quotes", **params)
+
+    def carhire_locations(self, q: str, **params: Any) -> Any:
+        return self._c._post_json("/carhire/skyscanner-locations", q=q, **params)
+
+    def carhire(self, **params: Any) -> Any:
+        return self._c._post_json("/carhire/skyscanner-quotes", **params)
+
+
+class Client:
+    """Client for the ScrapeUnblocker API.
+
+    Args:
+        api_key: Your API key. Falls back to the ``SCRAPEUNBLOCKER_KEY``
+            environment variable when omitted.
+        base_url: Override the API host (rarely needed).
+        timeout: Per-request timeout in seconds. Rendering heavy, protected
+            pages can take a while, so the default is generous (180s).
+        max_retries: How many times to retry transient failures (429/5xx and
+            network errors) with exponential backoff.
+
+    Example:
+        >>> from scrapeunblocker import Client
+        >>> su = Client(api_key="su_live_...")
+        >>> html = su.get_page_source("https://example.com")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = _base.DEFAULT_BASE_URL,
+        timeout: float = _base.DEFAULT_TIMEOUT,
+        max_retries: int = _base.DEFAULT_MAX_RETRIES,
+    ):
+        self._api_key = _base.resolve_api_key(api_key)
+        self._max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                _base.API_KEY_HEADER: self._api_key,
+                "User-Agent": _base.user_agent(__version__),
+                "Accept": "*/*",
+            },
+        )
+        self.skyscanner = _SkyscannerNamespace(self)
+
+    # -- context manager ------------------------------------------------
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # -- low-level request with retry -----------------------------------
+    def _request(self, path: str, params: Dict[str, Any]) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = self._http.post(path, params=params)
+            except httpx.TimeoutException as exc:
+                raise ScrapeTimeoutError(str(exc)) from exc
+            except httpx.TransportError as exc:
+                if attempt < self._max_retries:
+                    self._sleep(attempt)
+                    attempt += 1
+                    continue
+                raise SUConnectionError(str(exc)) from exc
+
+            if _base.is_retryable(response.status_code) and attempt < self._max_retries:
+                self._sleep(attempt)
+                attempt += 1
+                continue
+
+            _base.raise_for_status(response)
+            return response
+
+    @staticmethod
+    def _sleep(attempt: int) -> None:
+        time.sleep(min(0.5 * (2 ** attempt), 8.0))
+
+    def _post_json(self, path: str, **params: Any) -> Any:
+        response = self._request(path, _base.build_params(**params))
+        return response.json()
+
+    # -- public API -----------------------------------------------------
+    def get_page_source(
+        self,
+        url: str,
+        *,
+        proxy_country: Optional[str] = None,
+        time_sleep: Optional[int] = None,
+        method: Optional[str] = None,
+        value: Optional[str] = None,
+        method_timeout: Optional[int] = None,
+    ) -> str:
+        """Fetch a URL and return the fully rendered HTML.
+
+        The page is loaded in a real browser behind the appropriate anti-bot
+        bypass chain, so JavaScript-heavy and protected sites come back
+        rendered.
+
+        Args:
+            url: The page to fetch.
+            proxy_country: ISO country code to route through (e.g. ``"US"``).
+            time_sleep: Extra seconds to wait after load before capture.
+            method: Advanced render-wait method (``"css"``, ``"js"``, ...).
+            value: The selector/expression paired with ``method``.
+            method_timeout: Cap in seconds for the render-wait method.
+
+        Returns:
+            The page HTML as a string.
+        """
+        params = _base.build_params(
+            url=url,
+            proxy_country=proxy_country,
+            time_sleep=time_sleep,
+            method=method,
+            value=value,
+            method_timeout=method_timeout,
+        )
+        response = self._request("/getPageSource", params)
+        return response.text
+
+    def get_parsed(
+        self,
+        url: str,
+        *,
+        refresh_rules: bool = False,
+        rules_hint: Optional[str] = None,
+        proxy_country: Optional[str] = None,
+        time_sleep: Optional[int] = None,
+    ) -> ParsedPage:
+        """Fetch a URL and return structured JSON instead of HTML.
+
+        The API extracts fields using Schema.org, ``__NEXT_DATA__`` or
+        AI-generated rules - no per-site parser to maintain.
+
+        Args:
+            url: The page to parse.
+            refresh_rules: Force-regenerate the cached extraction rules for
+                this domain (use when a parse comes back clearly wrong).
+            rules_hint: Free-text steer for regeneration, e.g. ``"price is
+                missing"``.
+            proxy_country: ISO country code to route through.
+            time_sleep: Extra seconds to wait after load before capture.
+
+        Returns:
+            A :class:`ParsedPage` with ``page_type``, ``source`` and ``data``.
+        """
+        params = _base.build_params(
+            url=url,
+            parsed_data=True,
+            refresh_rules=refresh_rules or None,
+            rules_hint=rules_hint,
+            proxy_country=proxy_country,
+            time_sleep=time_sleep,
+        )
+        response = self._request("/getPageSource", params)
+        return ParsedPage.from_response(response.json())
+
+    def get_page_with_cookies(
+        self,
+        url: str,
+        *,
+        proxy_country: Optional[str] = None,
+        time_sleep: Optional[int] = None,
+    ) -> PageResult:
+        """Fetch a URL and also return the cookies and proxy that served it."""
+        params = _base.build_params(
+            url=url,
+            get_cookies=True,
+            proxy_country=proxy_country,
+            time_sleep=time_sleep,
+        )
+        response = self._request("/getPageSource", params)
+        return PageResult.from_response(response.json())
+
+    def serp(
+        self,
+        keyword: str,
+        *,
+        proxy_country: Optional[str] = None,
+        pages_to_check: int = 1,
+        wait_after_load: int = 0,
+        captcha_pause: int = 0,
+    ) -> Any:
+        """Run a Google search and return the parsed SERP as JSON.
+
+        Args:
+            keyword: The search query.
+            proxy_country: ISO country code to search from.
+            pages_to_check: How many result pages to fetch (1-10).
+            wait_after_load: Seconds to wait after the page loads.
+            captcha_pause: Seconds to pause if a captcha appears.
+        """
+        return self._post_json(
+            "/serp",
+            keyword=keyword,
+            proxy_country=proxy_country,
+            pages_to_check=pages_to_check,
+            wait_after_load=wait_after_load or None,
+            captcha_pause=captcha_pause or None,
+        )
+
+    def get_image(
+        self, url: str, *, proxy_country: Optional[str] = None
+    ) -> bytes:
+        """Fetch an image URL through the bypass chain and return its bytes."""
+        params = _base.build_params(url=url, proxy_country=proxy_country)
+        response = self._request("/getImage", params)
+        return response.content

scrapeunblocker/exceptions.py

@@ -0,0 +1,70 @@
+"""Exception hierarchy for the ScrapeUnblocker client.
+
+Every error raised by the client derives from :class:`ScrapeUnblockerError`,
+so ``except ScrapeUnblockerError`` catches everything. API responses map to
+typed subclasses by status code, letting callers react to a hard block
+differently than a transient upstream outage without parsing status codes by
+hand.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ScrapeUnblockerError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class APIError(ScrapeUnblockerError):
+    """An error response returned by the ScrapeUnblocker API.
+
+    Attributes:
+        status_code: The HTTP status code of the response.
+        body: The raw response body (text), useful for debugging.
+    """
+
+    def __init__(self, message: str, *, status_code: int, body: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class AuthenticationError(APIError):
+    """The API key is missing, malformed, or not recognised (HTTP 401)."""
+
+
+class InvalidRequestError(APIError):
+    """The request was rejected as invalid, e.g. a malformed URL (HTTP 400)."""
+
+
+class BlockedError(APIError):
+    """The target site blocked every available bypass path (HTTP 403).
+
+    This is the target's anti-bot protection winning, not a problem with your
+    request. Blocked calls are not billed.
+    """
+
+
+class RateLimitError(APIError):
+    """Too many requests against your account in a short window (HTTP 429)."""
+
+
+class UpstreamOutageError(APIError):
+    """The origin site returned a server-side outage page (HTTP 503).
+
+    This means the *target* is down, not ScrapeUnblocker. Retrying later
+    usually succeeds.
+    """
+
+
+class ServerError(APIError):
+    """ScrapeUnblocker returned an unexpected 5xx error."""
+
+
+class ScrapeTimeoutError(ScrapeUnblockerError):
+    """The request did not complete within the configured timeout."""
+
+
+class ConnectionError(ScrapeUnblockerError):
+    """The client could not reach the ScrapeUnblocker API."""

scrapeunblocker/models.py

@@ -0,0 +1,52 @@
+"""Lightweight return types for structured responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ParsedPage:
+    """Structured data extracted from a page (``parsed_data=True``).
+
+    Attributes:
+        page_type: What the API classified the page as, e.g. ``"product"``.
+        source: How the data was extracted (Schema.org, __NEXT_DATA__, AI rules).
+        data: The extracted fields as a plain dict.
+        raw: The full JSON payload as returned by the API.
+    """
+
+    page_type: Optional[str]
+    source: Optional[str]
+    data: Any
+    raw: Dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: Dict[str, Any]) -> "ParsedPage":
+        inner = payload.get("data", payload) or {}
+        return cls(
+            page_type=inner.get("page_type"),
+            source=inner.get("source"),
+            data=inner.get("data"),
+            raw=payload,
+        )
+
+
+@dataclass
+class PageResult:
+    """HTML plus the cookies and proxy that served it (``get_cookies=True``)."""
+
+    html: Optional[str]
+    cookies: Any
+    proxy: Optional[str]
+    raw: Dict[str, Any]
+
+    @classmethod
+    def from_response(cls, payload: Dict[str, Any]) -> "PageResult":
+        return cls(
+            html=payload.get("html") or payload.get("page_source") or payload.get("content"),
+            cookies=payload.get("cookies"),
+            proxy=payload.get("proxy") or payload.get("proxy_address"),
+            raw=payload,
+        )

scrapeunblocker/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

scrapeunblocker-0.1.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: scrapeunblocker
+Version: 0.1.0
+Summary: Official Python client for the ScrapeUnblocker web scraping API - JavaScript-rendered pages that bypass Cloudflare, DataDome, PerimeterX, Akamai and more.
+Project-URL: Homepage, https://scrapeunblocker.com
+Project-URL: Documentation, https://developers.scrapeunblocker.com
+Project-URL: Source, https://github.com/ScrapeUnblocker/scrapeunblocker-python
+Project-URL: Changelog, https://github.com/ScrapeUnblocker/scrapeunblocker-python/blob/main/CHANGELOG.md
+Author-email: ScrapeUnblocker <support@scrapeunblocker.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anti-bot,captcha,cloudflare,crawler,datadome,proxy,scraping api,web scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.23
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ScrapeUnblocker Python client
+
+Official Python client for the [ScrapeUnblocker](https://scrapeunblocker.com) web scraping API.
+
+Every request is fully JavaScript-rendered in a real browser and routed through premium proxies, so it bypasses Cloudflare, DataDome, PerimeterX, Akamai, Kasada and similar anti-bot systems - from one simple call. You are only billed for successful requests.
+
+- **Highest success rate on the market** (95%+ on live production traffic)
+- **Rendered HTML or parsed JSON** - no per-site parsers to maintain
+- Sync **and** async clients, fully type-hinted
+
+## Install
+
+```bash
+pip install scrapeunblocker
+```
+
+Requires Python 3.8+.
+
+## Quickstart
+
+```python
+from scrapeunblocker import Client
+
+su = Client(api_key="su_live_...")   # or set the SCRAPEUNBLOCKER_KEY env var
+
+# Rendered HTML for any URL
+html = su.get_page_source("https://example.com")
+
+# Structured JSON instead of HTML (products, listings, search results, ...)
+product = su.get_parsed("https://www.amazon.com/dp/B08N5WRWNW")
+print(product.page_type)   # "product"
+print(product.data)        # {...}
+```
+
+Get your API key at [app.scrapeunblocker.com](https://app.scrapeunblocker.com). The free trial does not require a credit card.
+
+## Authentication
+
+Pass the key directly, or set an environment variable and omit it:
+
+```bash
+export SCRAPEUNBLOCKER_KEY="su_live_..."
+```
+
+```python
+from scrapeunblocker import Client
+su = Client()   # reads SCRAPEUNBLOCKER_KEY
+```
+
+## Fetch rendered HTML
+
+```python
+html = su.get_page_source(
+    "https://www.nordstrom.com/browse/women/clothing/dresses",
+    proxy_country="US",     # route through a specific country
+    time_sleep=3,           # wait extra seconds after load
+)
+```
+
+## Get parsed JSON
+
+Pass a URL and get back structured data extracted via Schema.org, `__NEXT_DATA__` or AI-generated rules:
+
+```python
+result = su.get_parsed("https://www.walmart.com/ip/12345")
+print(result.page_type)    # e.g. "product"
+print(result.source)       # how it was extracted
+print(result.data)         # the fields
+
+# If a parse ever comes back wrong, force a fresh set of rules:
+result = su.get_parsed(url, refresh_rules=True, rules_hint="price is missing")
+```
+
+## Google search (SERP)
+
+```python
+serp = su.serp("web scraping api", pages_to_check=2, proxy_country="US")
+```
+
+## Cookies and the serving proxy
+
+```python
+page = su.get_page_with_cookies("https://example.com")
+print(page.html, page.cookies, page.proxy)
+```
+
+## Images
+
+```python
+data = su.get_image("https://example.com/photo.jpg")
+open("photo.jpg", "wb").write(data)
+```
+
+## Skyscanner plugins
+
+```python
+# Resolve a place name to entity IDs, then search
+locs = su.skyscanner.flight_locations("London")
+flights = su.skyscanner.flights(
+    origin="London", dest="New York",
+    depart_date="2026-09-01", adults=1, currency="USD",
+)
+
+hotels = su.skyscanner.hotels(destination="Madrid", checkin="2026-09-01", checkout="2026-09-03")
+cars = su.skyscanner.carhire(pickup="Madrid", pickup_datetime="2026-09-01T10:00", dropoff_datetime="2026-09-03T10:00")
+```
+
+## Async
+
+Every method has an async twin on `AsyncClient`:
+
+```python
+import asyncio
+from scrapeunblocker import AsyncClient
+
+async def main():
+    async with AsyncClient(api_key="su_live_...") as su:
+        html = await su.get_page_source("https://example.com")
+
+asyncio.run(main())
+```
+
+## Error handling
+
+Non-2xx responses raise typed exceptions, all subclasses of `ScrapeUnblockerError`:
+
+```python
+from scrapeunblocker import Client, BlockedError, RateLimitError, UpstreamOutageError
+
+su = Client()
+try:
+    html = su.get_page_source("https://example.com")
+except BlockedError:
+    ...   # 403: the target blocked every bypass path (not billed)
+except RateLimitError:
+    ...   # 429: slow down
+except UpstreamOutageError:
+    ...   # 503: the target site itself is down - retry later
+```
+
+| Exception | Status | Meaning |
+|---|---|---|
+| `InvalidRequestError` | 400 | Bad URL or unsupported scheme |
+| `AuthenticationError` | 401 | Missing or invalid API key |
+| `BlockedError` | 403 | Blocked by bot protection on every path |
+| `RateLimitError` | 429 | Too many requests |
+| `UpstreamOutageError` | 503 | The target origin is down |
+| `ServerError` | 5xx | Unexpected server error |
+| `ScrapeTimeoutError` | - | Request exceeded the timeout |
+| `ConnectionError` | - | Could not reach the API |
+
+Transient failures (429, 502, 503, 504 and network errors) are retried automatically with exponential backoff; tune with `Client(max_retries=...)`.
+
+## Configuration
+
+```python
+Client(
+    api_key=None,          # or SCRAPEUNBLOCKER_KEY env var
+    base_url="https://api.scrapeunblocker.com",
+    timeout=180.0,         # seconds; protected pages can be slow
+    max_retries=2,
+)
+```
+
+## Links
+
+- Documentation: https://developers.scrapeunblocker.com
+- Website: https://scrapeunblocker.com
+- Dashboard: https://app.scrapeunblocker.com
+
+## License
+
+MIT

scrapeunblocker-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+scrapeunblocker/__init__.py,sha256=JicnXv9l6hOuXPyyhDOIcPw9q1iIEILS3t5X99B7Smk,1123
+scrapeunblocker/_async_client.py,sha256=jbT5bn6vYgRSXQ0PwHK-YD_ro8mH6bOzX3ledBjCaSU,6824
+scrapeunblocker/_base.py,sha256=hs8c06Wynf_48kiXKeyJbZZy0IpG02KtqziYZ7sSkic,3496
+scrapeunblocker/_client.py,sha256=HC-lNzwytLnI_Xl9uAkB5IDW0QCEddCQVWnWt-A0iz8,8670
+scrapeunblocker/exceptions.py,sha256=bDVgiVxtAWQNt3hmkt9_WCN_iucbVxPI1eyYMPB4cjE,2084
+scrapeunblocker/models.py,sha256=DZqdwHs6llqd0kTVue9wWqSiL5-m_4LXm4Jlx8ffV4c,1531
+scrapeunblocker/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scrapeunblocker/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+scrapeunblocker-0.1.0.dist-info/METADATA,sha256=VESjtiBYUhpcDdgJk6Wr0U4rq6kor0LI1gmh6niwISU,6591
+scrapeunblocker-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+scrapeunblocker-0.1.0.dist-info/licenses/LICENSE,sha256=-Qs4w8IjJt3RWr3it4xjyous5qjVyQKBbmaxNP4Mlmo,1072
+scrapeunblocker-0.1.0.dist-info/RECORD,,

scrapeunblocker-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

scrapeunblocker-0.1.0.dist-info/licenses/LICENSE

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