peep-sdk 0.1.0__tar.gz

peep_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

peep_sdk-0.1.0/LICENSE

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

peep_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: peep-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Peep web scraping API — scrape, crawl, map, search, extract, and agent.
+Project-URL: Homepage, https://peep.shownomore.com
+Project-URL: Documentation, https://peep.shownomore.com/docs
+License: MIT
+License-File: LICENSE
+Keywords: api,crawler,peep,scraper,sdk,web-scraping
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# peep-sdk (Python)
+
+Official Python SDK for the [Peep](https://peep.shownomore.com) web scraping
+API. Scrape, crawl, map, search, extract, and run autonomous agents. Every call
+draws from your shared **Peep Card** credit balance.
+
+## Install
+
+From PyPI with pip, Poetry, or uv:
+
+```bash
+pip install peep-sdk
+poetry add peep-sdk
+uv add peep-sdk
+```
+
+## Usage
+
+```python
+import os
+from peep import Peep
+
+peep = Peep(api_key=os.environ["PEEP_API_KEY"])
+
+# Scrape a page to markdown
+res = peep.scrape("https://example.com", formats=["markdown"])
+print(res["data"]["markdown"])
+print(peep.last_credits)  # {"used": 1, "remaining": 499}
+
+# Crawl a site and wait for completion
+crawl = peep.crawl_and_wait("https://example.com", limit=50)
+
+# Search the web
+hits = peep.search("best web scraping api", limit=10)
+
+# AI structured extraction
+data = peep.extract_and_wait(
+    ["https://example.com"],
+    prompt="Extract the company name and pricing tiers.",
+)
+
+# Autonomous harvesting
+leads = peep.agent_and_wait(
+    "Find flats for rent in Vivek Vihar with phone numbers and photos",
+    maxSources=10,
+)
+
+# Check your balance
+print(peep.credits()["balance"])
+```
+
+> Option keyword arguments are passed through verbatim — use the API's
+> camelCase names, e.g. `peep.scrape(url, onlyMainContent=True)`.
+
+## Methods
+
+| Method | Endpoint | Notes |
+|--------|----------|-------|
+| `scrape(url, **options)` | `POST /scrape` | Sync. Pass a YouTube URL for video intelligence. |
+| `youtube(url)` | `POST /scrape` | Sugar for YouTube videos. |
+| `map(url, **options)` | `POST /map` | Sync URL discovery. |
+| `search(query, **options)` | `POST /search` | Sync. |
+| `crawl(...)` / `crawl_and_wait(...)` | `POST /crawl` | Async; `*_and_wait` polls to completion. |
+| `batch_scrape(...)` / `batch_scrape_and_wait(...)` | `POST /batch/scrape` | Async. |
+| `extract(...)` / `extract_and_wait(...)` | `POST /extract` | Async. |
+| `agent(...)` / `agent_and_wait(...)` | `POST /agent` | Async. |
+| `credits()` | `GET /credits` | Free. Balance + ledger. |
+
+Non-2xx responses raise `PeepError` with `.status` and `.code`. After every
+call, `peep.last_credits` holds `{"used", "remaining"}` from the response
+headers.
+
+## License
+
+MIT

peep_sdk-0.1.0/README.md

@@ -0,0 +1,75 @@
+# peep-sdk (Python)
+
+Official Python SDK for the [Peep](https://peep.shownomore.com) web scraping
+API. Scrape, crawl, map, search, extract, and run autonomous agents. Every call
+draws from your shared **Peep Card** credit balance.
+
+## Install
+
+From PyPI with pip, Poetry, or uv:
+
+```bash
+pip install peep-sdk
+poetry add peep-sdk
+uv add peep-sdk
+```
+
+## Usage
+
+```python
+import os
+from peep import Peep
+
+peep = Peep(api_key=os.environ["PEEP_API_KEY"])
+
+# Scrape a page to markdown
+res = peep.scrape("https://example.com", formats=["markdown"])
+print(res["data"]["markdown"])
+print(peep.last_credits)  # {"used": 1, "remaining": 499}
+
+# Crawl a site and wait for completion
+crawl = peep.crawl_and_wait("https://example.com", limit=50)
+
+# Search the web
+hits = peep.search("best web scraping api", limit=10)
+
+# AI structured extraction
+data = peep.extract_and_wait(
+    ["https://example.com"],
+    prompt="Extract the company name and pricing tiers.",
+)
+
+# Autonomous harvesting
+leads = peep.agent_and_wait(
+    "Find flats for rent in Vivek Vihar with phone numbers and photos",
+    maxSources=10,
+)
+
+# Check your balance
+print(peep.credits()["balance"])
+```
+
+> Option keyword arguments are passed through verbatim — use the API's
+> camelCase names, e.g. `peep.scrape(url, onlyMainContent=True)`.
+
+## Methods
+
+| Method | Endpoint | Notes |
+|--------|----------|-------|
+| `scrape(url, **options)` | `POST /scrape` | Sync. Pass a YouTube URL for video intelligence. |
+| `youtube(url)` | `POST /scrape` | Sugar for YouTube videos. |
+| `map(url, **options)` | `POST /map` | Sync URL discovery. |
+| `search(query, **options)` | `POST /search` | Sync. |
+| `crawl(...)` / `crawl_and_wait(...)` | `POST /crawl` | Async; `*_and_wait` polls to completion. |
+| `batch_scrape(...)` / `batch_scrape_and_wait(...)` | `POST /batch/scrape` | Async. |
+| `extract(...)` / `extract_and_wait(...)` | `POST /extract` | Async. |
+| `agent(...)` / `agent_and_wait(...)` | `POST /agent` | Async. |
+| `credits()` | `GET /credits` | Free. Balance + ledger. |
+
+Non-2xx responses raise `PeepError` with `.status` and `.code`. After every
+call, `peep.last_credits` holds `{"used", "remaining"}` from the response
+headers.
+
+## License
+
+MIT

peep_sdk-0.1.0/peep/__init__.py

@@ -0,0 +1,9 @@
+"""Official Python SDK for the Peep web scraping API.
+
+https://peep.shownomore.com/docs
+"""
+
+from .client import Peep, PeepError
+
+__all__ = ["Peep", "PeepError"]
+__version__ = "0.1.0"

peep_sdk-0.1.0/peep/client.py

@@ -0,0 +1,188 @@
+"""Peep API client."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+import requests
+
+_TERMINAL = ("completed", "failed", "cancelled", "canceled", "error")
+
+
+class PeepError(Exception):
+    """Raised on any non-2xx response from the Peep API."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class Peep:
+    """Client for the Peep web scraping API.
+
+    Args:
+        api_key: Your ``peep_live_*`` API key.
+        base_url: Override the API base URL.
+
+    Option keyword arguments are passed through verbatim, so use the API's
+    camelCase names — e.g. ``peep.scrape(url, onlyMainContent=True)``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://peep.shownomore.com",
+    ) -> None:
+        if not api_key:
+            raise ValueError("Peep: api_key is required.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.last_credits: Dict[str, Optional[int]] = {"used": None, "remaining": None}
+        self._session = requests.Session()
+
+    # ── Internals ───────────────────────────────────────────────
+    def _request(
+        self, method: str, path: str, body: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        res = self._session.request(
+            method,
+            f"{self.base_url}{path}",
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            json=body,
+        )
+
+        used = res.headers.get("x-peep-credits-used")
+        remaining = res.headers.get("x-peep-credits-remaining")
+        self.last_credits = {
+            "used": int(used) if used is not None else None,
+            "remaining": int(remaining) if remaining is not None else None,
+        }
+
+        data = res.json() if res.text else {}
+        if not res.ok:
+            err = data.get("error", {}) if isinstance(data, dict) else {}
+            raise PeepError(
+                res.status_code,
+                err.get("code", "UNKNOWN"),
+                err.get("message", f"Request failed with status {res.status_code}"),
+            )
+        return data
+
+    def _start_and_wait(
+        self,
+        start: Callable[[], Dict[str, Any]],
+        get_status: Callable[[str], Dict[str, Any]],
+        poll_interval: float,
+        timeout: float,
+    ) -> Dict[str, Any]:
+        job = start()
+        job_id = job.get("jobId")
+        if not job_id:
+            return job
+        deadline = time.time() + timeout
+        last = get_status(job_id)
+        while time.time() < deadline:
+            if str(last.get("status", "")).lower() in _TERMINAL:
+                return last
+            time.sleep(poll_interval)
+            last = get_status(job_id)
+        return last  # timed out — return the latest snapshot
+
+    # ── Sync endpoints ──────────────────────────────────────────
+    def scrape(self, url: str, **options: Any) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/scrape", {"url": url, **options})
+
+    def youtube(self, url: str) -> Dict[str, Any]:
+        return self.scrape(url, formats=["markdown"])
+
+    def map(self, url: str, **options: Any) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/map", {"url": url, **options})
+
+    def search(self, query: str, **options: Any) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/search", {"query": query, **options})
+
+    # ── Async endpoints ─────────────────────────────────────────
+    def crawl(self, url: str, **options: Any) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/crawl", {"url": url, **options})
+
+    def get_crawl(self, job_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/crawl/{job_id}")
+
+    def crawl_and_wait(
+        self, url: str, poll_interval: float = 2.5, timeout: float = 300, **options: Any
+    ) -> Dict[str, Any]:
+        return self._start_and_wait(
+            lambda: self.crawl(url, **options), self.get_crawl, poll_interval, timeout
+        )
+
+    def batch_scrape(
+        self, urls: List[str], scrape_options: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        return self._request(
+            "POST",
+            "/api/v1/batch/scrape",
+            {"urls": urls, "scrapeOptions": scrape_options or {}},
+        )
+
+    def get_batch(self, job_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/batch/scrape/{job_id}")
+
+    def batch_scrape_and_wait(
+        self,
+        urls: List[str],
+        scrape_options: Optional[Dict[str, Any]] = None,
+        poll_interval: float = 2.5,
+        timeout: float = 300,
+    ) -> Dict[str, Any]:
+        return self._start_and_wait(
+            lambda: self.batch_scrape(urls, scrape_options),
+            self.get_batch,
+            poll_interval,
+            timeout,
+        )
+
+    def extract(self, urls: List[str], **options: Any) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/extract", {"urls": urls, **options})
+
+    def get_extract(self, job_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/extract/{job_id}")
+
+    def extract_and_wait(
+        self,
+        urls: List[str],
+        poll_interval: float = 2.5,
+        timeout: float = 300,
+        **options: Any,
+    ) -> Dict[str, Any]:
+        return self._start_and_wait(
+            lambda: self.extract(urls, **options),
+            self.get_extract,
+            poll_interval,
+            timeout,
+        )
+
+    def agent(self, prompt: str, **options: Any) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/agent", {"prompt": prompt, **options})
+
+    def get_agent(self, job_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/agent/{job_id}")
+
+    def agent_and_wait(
+        self,
+        prompt: str,
+        poll_interval: float = 2.5,
+        timeout: float = 300,
+        **options: Any,
+    ) -> Dict[str, Any]:
+        return self._start_and_wait(
+            lambda: self.agent(prompt, **options),
+            self.get_agent,
+            poll_interval,
+            timeout,
+        )
+
+    # ── Credits ─────────────────────────────────────────────────
+    def credits(self) -> Dict[str, Any]:
+        return self._request("GET", "/api/v1/credits")

peep_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "peep-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Peep web scraping API — scrape, crawl, map, search, extract, and agent."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["peep", "web-scraping", "crawler", "scraper", "api", "sdk"]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://peep.shownomore.com"
+Documentation = "https://peep.shownomore.com/docs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["peep"]