mrscraper-sdk 0.1.0__tar.gz

mrscraper_sdk-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.manifest
+*.spec
+debug_dir/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Distribution / packaging
+.eggs/
+*.tar.gz
+
+# Unit test / coverage
+.coverage
+.coverage.*
+htmlcov/
+.cache
+.pytest_cache/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Environment files
+.env
+.env.*
+!.env.example

mrscraper_sdk-0.1.0/LICENSE

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

mrscraper_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: mrscraper-sdk
+Version: 0.1.0
+Summary: Python SDK for the MrScraper web-scraping API
+Project-URL: Homepage, https://mrscraper.com
+Project-URL: Documentation, https://docs.mrscraper.com
+Project-URL: Repository, https://github.com/mrscraper/mrscraper-python
+Project-URL: Bug Tracker, https://github.com/mrscraper/mrscraper-python/issues
+Author: MrScraper
+License: MIT
+License-File: LICENSE
+Keywords: api,mrscraper,scraping,sdk,web scraping
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MrScraper Python SDK
+
+A clean, typed Python client for the [MrScraper](https://mrscraper.com) web-scraping API.
+Supports **async/await** usage.
+
+---
+
+## Installation
+
+```bash
+pip install mrscraper-sdk
+```
+
+Requires Python 3.9+.
+
+---
+
+## Authentication
+
+Every client is initialised with your MrScraper API token.
+Get yours at <https://app.mrscraper.com>.
+
+```python
+from mrscraper import MrScraper
+
+client = MrScraper(token="atk_your_token_here")
+```
+
+---
+
+## Quick Start
+
+### Fetch raw HTML (stealth browser)
+
+```python
+import asyncio
+from mrscraper import MrScraper
+
+async def main():
+    client = MrScraper(token="atk_your_token_here")
+
+    result = await client.fetch_html(
+        "https://stockx.com/air-jordan-1-retro-low-og-chicago-2025",
+        geo_code="US",
+        timeout=120,
+        block_resources=False,
+    )
+    print(result["data"])   # raw HTML string
+
+asyncio.run(main())
+```
+
+### Create an AI scraper
+
+```python
+result = await client.create_scraper(
+    url="https://example.com/products",
+    message="Extract all product names, prices, and ratings",
+    agent="listing",          # "general" | "listing" | "map"
+    proxy_country="US",
+)
+scraper_id = result["data"]["data"]["id"]
+print("Scraper ID:", scraper_id)
+```
+
+### Rerun a scraper on a new URL
+
+```python
+result = await client.rerun_scraper(
+    scraper_id=scraper_id,
+    url="https://example.com/products?page=2",
+)
+```
+
+### Bulk rerun on multiple URLs (AI scraper)
+
+```python
+result = await client.bulk_rerun_scraper(
+    scraper_id=scraper_id,
+    urls=[
+        "https://example.com/products/item1",
+        "https://example.com/products/item2",
+        "https://example.com/products/item3",
+    ],
+)
+```
+
+### Rerun a manually configured scraper
+
+```python
+result = await client.rerun_manual_scraper(
+    scraper_id="manual_scraper_67890",
+    url="https://example.com/products/new-item",
+)
+```
+
+### Bulk rerun manual scraper on multiple URLs
+
+```python
+result = await client.bulk_rerun_manual_scraper(
+    scraper_id="scraper_12345",
+    urls=[
+        "https://www.example.com/products/item1",
+        "https://www.example.com/products/item2",
+        "https://www.example.com/products/item3",
+    ],
+)
+```
+
+### Retrieve results
+
+```python
+# All results (paginated)
+page = await client.get_all_results(
+    sort_field="updatedAt",
+    sort_order="DESC",
+    page_size=20,
+    page=1,
+    search="product",
+    date_range_column="updatedAt",
+    start_at="2024-01-01",
+    end_at="2024-01-31",
+)
+print(page["data"])
+
+# A specific result by ID
+result = await client.get_result_by_id("result_12345")
+print(result["data"])
+```
+
+---
+
+## API Reference
+
+### `MrScraper`
+
+All methods are coroutines and must be awaited.
+
+| Method | Description |
+|--------|-------------|
+| `fetch_html(url, *, timeout, geo_code, block_resources)` | Fetch rendered HTML via the MrScraper stealth browser |
+| `create_scraper(url, message, *, agent, proxy_country, ...)` | Create & run an AI-powered scraper |
+| `rerun_scraper(scraper_id, url, *, max_depth, max_pages, limit, ...)` | Rerun an AI scraper on a new URL |
+| `bulk_rerun_scraper(scraper_id, urls)` | Rerun an AI scraper on multiple URLs in one batch |
+| `rerun_manual_scraper(scraper_id, url)` | Rerun a manually configured scraper on a single URL |
+| `bulk_rerun_manual_scraper(scraper_id, urls)` | Rerun a manual scraper on multiple URLs in one batch |
+| `get_all_results(*, sort_field, sort_order, page_size, page, search, ...)` | List all results with filtering & pagination |
+| `get_result_by_id(result_id)` | Fetch a single result by its ID |
+
+All methods return a `dict` with the following keys:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `status_code` | `int` | HTTP status code |
+| `data` | `Any` | Parsed JSON body or raw text |
+| `headers` | `dict` | Response headers |
+
+### `bulk_rerun_manual_scraper`
+
+Reruns a manually configured scraper on multiple URLs simultaneously in a single batch operation. This is more efficient than calling `rerun_manual_scraper` multiple times, as it processes all URLs in parallel and returns consolidated results. Ideal for scraping multiple pages, products, or articles with the same extraction logic.
+
+| Argument | Description |
+|----------|-------------|
+| `scraper_id` | The ID of the manual scraper to rerun (obtained from the MrScraper dashboard). Must be a scraper created manually through the web interface, not an AI scraper. Find it at https://app.mrscraper.com |
+| `urls` | A list of target URLs to scrape (required, must contain at least one URL). Each URL will be processed independently using the scraper's extraction logic. Example: `["https://example.com/page1", "https://example.com/page2"]` |
+
+**Returns:** A dict with `status_code`, `data` (bulk job info including job ID, status, metadata; use `get_all_results` or `get_result_by_id` to fetch per-URL results), and `headers`.
+
+**Example:**
+
+```python
+result = await client.bulk_rerun_manual_scraper(
+    scraper_id="scraper_12345",
+    urls=[
+        "https://www.example.com/products/item1",
+        "https://www.example.com/products/item2",
+        "https://www.example.com/products/item3",
+    ],
+)
+```
+
+### `create_scraper` — agent types
+
+| Agent | Best used for |
+|-------|---------------|
+| `"general"` | Default; handles almost any page |
+| `"listing"` | Product listings, job boards, search results |
+| `"map"` | Crawling all sub-pages / sitemaps of a site |
+
+The `max_depth`, `max_pages`, `limit`, `include_patterns`, and `exclude_patterns`
+parameters are only meaningful when `agent="map"`.
+
+---
+
+## Exceptions
+
+| Exception | Raised when |
+|-----------|-------------|
+| `MrScraperError` | Base class for all SDK errors |
+| `AuthenticationError` | API token is invalid or missing (HTTP 401) |
+| `APIError` | API returned a non-2xx error; has `.status_code` attribute |
+| `NetworkError` | Connection timeout or network-level failure |
+
+```python
+from mrscraper.exceptions import AuthenticationError, APIError, NetworkError
+
+try:
+    result = await client.fetch_html("https://example.com")
+except AuthenticationError:
+    print("Check your API token at https://app.mrscraper.com")
+except APIError as e:
+    print(f"API error {e.status_code}: {e}")
+except NetworkError as e:
+    print(f"Network problem: {e}")
+```
+
+---
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint & format
+ruff check .
+ruff format .
+
+# Type check
+mypy src/mrscraper
+```
+
+---
+
+## License
+
+MIT © MrScraper

mrscraper_sdk-0.1.0/README.md

@@ -0,0 +1,240 @@
+# MrScraper Python SDK
+
+A clean, typed Python client for the [MrScraper](https://mrscraper.com) web-scraping API.
+Supports **async/await** usage.
+
+---
+
+## Installation
+
+```bash
+pip install mrscraper-sdk
+```
+
+Requires Python 3.9+.
+
+---
+
+## Authentication
+
+Every client is initialised with your MrScraper API token.
+Get yours at <https://app.mrscraper.com>.
+
+```python
+from mrscraper import MrScraper
+
+client = MrScraper(token="atk_your_token_here")
+```
+
+---
+
+## Quick Start
+
+### Fetch raw HTML (stealth browser)
+
+```python
+import asyncio
+from mrscraper import MrScraper
+
+async def main():
+    client = MrScraper(token="atk_your_token_here")
+
+    result = await client.fetch_html(
+        "https://stockx.com/air-jordan-1-retro-low-og-chicago-2025",
+        geo_code="US",
+        timeout=120,
+        block_resources=False,
+    )
+    print(result["data"])   # raw HTML string
+
+asyncio.run(main())
+```
+
+### Create an AI scraper
+
+```python
+result = await client.create_scraper(
+    url="https://example.com/products",
+    message="Extract all product names, prices, and ratings",
+    agent="listing",          # "general" | "listing" | "map"
+    proxy_country="US",
+)
+scraper_id = result["data"]["data"]["id"]
+print("Scraper ID:", scraper_id)
+```
+
+### Rerun a scraper on a new URL
+
+```python
+result = await client.rerun_scraper(
+    scraper_id=scraper_id,
+    url="https://example.com/products?page=2",
+)
+```
+
+### Bulk rerun on multiple URLs (AI scraper)
+
+```python
+result = await client.bulk_rerun_scraper(
+    scraper_id=scraper_id,
+    urls=[
+        "https://example.com/products/item1",
+        "https://example.com/products/item2",
+        "https://example.com/products/item3",
+    ],
+)
+```
+
+### Rerun a manually configured scraper
+
+```python
+result = await client.rerun_manual_scraper(
+    scraper_id="manual_scraper_67890",
+    url="https://example.com/products/new-item",
+)
+```
+
+### Bulk rerun manual scraper on multiple URLs
+
+```python
+result = await client.bulk_rerun_manual_scraper(
+    scraper_id="scraper_12345",
+    urls=[
+        "https://www.example.com/products/item1",
+        "https://www.example.com/products/item2",
+        "https://www.example.com/products/item3",
+    ],
+)
+```
+
+### Retrieve results
+
+```python
+# All results (paginated)
+page = await client.get_all_results(
+    sort_field="updatedAt",
+    sort_order="DESC",
+    page_size=20,
+    page=1,
+    search="product",
+    date_range_column="updatedAt",
+    start_at="2024-01-01",
+    end_at="2024-01-31",
+)
+print(page["data"])
+
+# A specific result by ID
+result = await client.get_result_by_id("result_12345")
+print(result["data"])
+```
+
+---
+
+## API Reference
+
+### `MrScraper`
+
+All methods are coroutines and must be awaited.
+
+| Method | Description |
+|--------|-------------|
+| `fetch_html(url, *, timeout, geo_code, block_resources)` | Fetch rendered HTML via the MrScraper stealth browser |
+| `create_scraper(url, message, *, agent, proxy_country, ...)` | Create & run an AI-powered scraper |
+| `rerun_scraper(scraper_id, url, *, max_depth, max_pages, limit, ...)` | Rerun an AI scraper on a new URL |
+| `bulk_rerun_scraper(scraper_id, urls)` | Rerun an AI scraper on multiple URLs in one batch |
+| `rerun_manual_scraper(scraper_id, url)` | Rerun a manually configured scraper on a single URL |
+| `bulk_rerun_manual_scraper(scraper_id, urls)` | Rerun a manual scraper on multiple URLs in one batch |
+| `get_all_results(*, sort_field, sort_order, page_size, page, search, ...)` | List all results with filtering & pagination |
+| `get_result_by_id(result_id)` | Fetch a single result by its ID |
+
+All methods return a `dict` with the following keys:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `status_code` | `int` | HTTP status code |
+| `data` | `Any` | Parsed JSON body or raw text |
+| `headers` | `dict` | Response headers |
+
+### `bulk_rerun_manual_scraper`
+
+Reruns a manually configured scraper on multiple URLs simultaneously in a single batch operation. This is more efficient than calling `rerun_manual_scraper` multiple times, as it processes all URLs in parallel and returns consolidated results. Ideal for scraping multiple pages, products, or articles with the same extraction logic.
+
+| Argument | Description |
+|----------|-------------|
+| `scraper_id` | The ID of the manual scraper to rerun (obtained from the MrScraper dashboard). Must be a scraper created manually through the web interface, not an AI scraper. Find it at https://app.mrscraper.com |
+| `urls` | A list of target URLs to scrape (required, must contain at least one URL). Each URL will be processed independently using the scraper's extraction logic. Example: `["https://example.com/page1", "https://example.com/page2"]` |
+
+**Returns:** A dict with `status_code`, `data` (bulk job info including job ID, status, metadata; use `get_all_results` or `get_result_by_id` to fetch per-URL results), and `headers`.
+
+**Example:**
+
+```python
+result = await client.bulk_rerun_manual_scraper(
+    scraper_id="scraper_12345",
+    urls=[
+        "https://www.example.com/products/item1",
+        "https://www.example.com/products/item2",
+        "https://www.example.com/products/item3",
+    ],
+)
+```
+
+### `create_scraper` — agent types
+
+| Agent | Best used for |
+|-------|---------------|
+| `"general"` | Default; handles almost any page |
+| `"listing"` | Product listings, job boards, search results |
+| `"map"` | Crawling all sub-pages / sitemaps of a site |
+
+The `max_depth`, `max_pages`, `limit`, `include_patterns`, and `exclude_patterns`
+parameters are only meaningful when `agent="map"`.
+
+---
+
+## Exceptions
+
+| Exception | Raised when |
+|-----------|-------------|
+| `MrScraperError` | Base class for all SDK errors |
+| `AuthenticationError` | API token is invalid or missing (HTTP 401) |
+| `APIError` | API returned a non-2xx error; has `.status_code` attribute |
+| `NetworkError` | Connection timeout or network-level failure |
+
+```python
+from mrscraper.exceptions import AuthenticationError, APIError, NetworkError
+
+try:
+    result = await client.fetch_html("https://example.com")
+except AuthenticationError:
+    print("Check your API token at https://app.mrscraper.com")
+except APIError as e:
+    print(f"API error {e.status_code}: {e}")
+except NetworkError as e:
+    print(f"Network problem: {e}")
+```
+
+---
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint & format
+ruff check .
+ruff format .
+
+# Type check
+mypy src/mrscraper
+```
+
+---
+
+## License
+
+MIT © MrScraper

mrscraper_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mrscraper-sdk"
+version = "0.1.0"
+description = "Python SDK for the MrScraper web-scraping API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "MrScraper", url = "https://mrscraper.com" },
+]
+keywords = ["scraping", "web scraping", "mrscraper", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "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.27",
+]
+
+[project.urls]
+Homepage = "https://mrscraper.com"
+Documentation = "https://docs.mrscraper.com"
+Repository = "https://github.com/mrscraper/mrscraper-python"
+"Bug Tracker" = "https://github.com/mrscraper/mrscraper-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mrscraper"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+files = ["src/mrscraper"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "integration: marks tests as integration tests (hit real API)",
+]

mrscraper_sdk-0.1.0/src/mrscraper/__init__.py

@@ -0,0 +1,31 @@
+"""
+MrScraper Python SDK
+
+A clean Python client for the `MrScraper <https://mrscraper.com>`_ API.
+Supports async/await usage.
+
+Quickstart::
+
+    import asyncio
+    from mrscraper import MrScraper
+
+    async def main():
+        client = MrScraper(token="atk_your_token_here")
+        result = await client.fetch_html("https://example.com")
+        print(result["data"])
+
+    asyncio.run(main())
+"""
+
+from .mrscraper import MrScraper
+from .exceptions import APIError, AuthenticationError, MrScraperError, NetworkError
+
+__all__ = [
+    "MrScraper",
+    "MrScraperError",
+    "AuthenticationError",
+    "APIError",
+    "NetworkError",
+]
+
+__version__ = "0.1.0"