scrapeunblocker 0.1.0__tar.gz

scrapeunblocker-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

scrapeunblocker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+# Publishes on every GitHub Release. Uses PyPI Trusted Publishing (OIDC) -
+# no API tokens stored anywhere. Configure the trusted publisher once at
+# https://pypi.org/manage/account/publishing/ pointing at this repo +
+# workflow (publish.yml) and environment "pypi".
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

scrapeunblocker-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

scrapeunblocker-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Sync `Client` and async `AsyncClient`.
+- `get_page_source`, `get_parsed`, `get_page_with_cookies`, `serp`, `get_image`.
+- Skyscanner plugins: flights, hotels, car hire (quotes + locations).
+- Typed exception hierarchy and automatic retry on transient failures.

scrapeunblocker-0.1.0/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.

scrapeunblocker-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,173 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scrapeunblocker"
+version = "0.1.0"
+description = "Official Python client for the ScrapeUnblocker web scraping API - JavaScript-rendered pages that bypass Cloudflare, DataDome, PerimeterX, Akamai and more."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{ name = "ScrapeUnblocker", email = "support@scrapeunblocker.com" }]
+keywords = [
+    "web scraping",
+    "scraping api",
+    "anti-bot",
+    "proxy",
+    "cloudflare",
+    "datadome",
+    "captcha",
+    "crawler",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.23"]
+
+[project.urls]
+Homepage = "https://scrapeunblocker.com"
+Documentation = "https://developers.scrapeunblocker.com"
+Source = "https://github.com/ScrapeUnblocker/scrapeunblocker-python"
+Changelog = "https://github.com/ScrapeUnblocker/scrapeunblocker-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21", "respx>=0.20", "mypy>=1.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scrapeunblocker"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

scrapeunblocker-0.1.0/src/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__",
+]