snapapi-python 1.3.0__tar.gz

snapapi_python-1.3.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: snapapi-python
+Version: 1.3.0
+Summary: Official Python SDK for SnapAPI — screenshot, metadata extraction, and HTML rendering
+License: MIT
+Keywords: screenshot,api,webpage-capture,snapapi
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.20.0
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

snapapi_python-1.3.0/README.md

@@ -0,0 +1,137 @@
+# SnapAPI Python SDK
+
+Official Python SDK for [SnapAPI](https://snapapi.tech) — capture any website as an image.
+
+## Install
+
+```bash
+pip install snapapi-python
+```
+
+Or install from source:
+
+```bash
+pip install .
+```
+
+## Quick Start
+
+```python
+from snapapi import SnapAPI
+
+snap = SnapAPI("snap_your_key_here")
+
+# Basic screenshot — returns PNG bytes
+image = snap.screenshot("example.com")
+with open("screenshot.png", "wb") as f:
+    f.write(image)
+```
+
+## Options
+
+```python
+# WebP format with dark mode and full-page capture
+webp = snap.screenshot("example.com", format="webp", dark_mode=True, full_page=True)
+
+# Mobile screenshot (iPhone 14)
+mobile = snap.screenshot("example.com", device="iphone14")
+
+# Custom viewport
+image = snap.screenshot("example.com", width=1920, height=1080)
+
+# Capture a specific element
+header = snap.screenshot("example.com", selector="header")
+
+# Add a delay before capture (milliseconds)
+image = snap.screenshot("example.com", delay=2000)
+```
+
+## Metadata Mode
+
+```python
+meta = snap.screenshot("example.com", meta=True)
+print(meta["title"], meta["description"])
+print(meta["headings"])  # [{"level": 1, "text": "..."}, ...]
+print(meta["links"])     # [{"text": "...", "href": "..."}, ...]
+print(meta["text"])      # Extracted visible text (first 2000 chars)
+```
+
+## Account & Usage
+
+```python
+# Check usage
+usage = snap.usage()
+print(f"Used {usage['usage']} of {usage['limit']}")
+
+# Account info
+account = snap.account()
+
+# Update settings
+snap.update_settings(name="My App", allowed_domains=["example.com"])
+```
+
+## Scheduled Monitors
+
+```python
+# Create a monitor — captures every 15 minutes
+monitor = snap.create_monitor(
+    url="https://example.com",
+    interval_minutes=15,
+    name="Homepage",
+    params={"format": "webp", "full_page": True},
+    webhook_url="https://your-app.com/webhook",
+)
+
+# List all monitors
+monitors = snap.list_monitors()
+
+# Pause / resume
+snap.update_monitor(monitor["id"], status="paused")
+snap.update_monitor(monitor["id"], status="active")
+
+# Browse snapshots
+result = snap.list_snapshots(monitor["id"], limit=10)
+for s in result["snapshots"]:
+    print(s["taken_at"], s["file_size"])
+
+# Download a snapshot
+image = snap.get_snapshot(monitor["id"], result["snapshots"][0]["id"])
+with open("snapshot.webp", "wb") as f:
+    f.write(image)
+
+# Delete a monitor (cascades to snapshots)
+snap.delete_monitor(monitor["id"])
+```
+
+> Monitors require **Starter** tier or above. See [pricing](https://snapapi.tech/#pricing) for limits.
+
+## Sign Up
+
+```python
+from snapapi import SnapAPI
+
+result = SnapAPI.signup("you@example.com")
+print(f"Your API key: {result['key']}")
+```
+
+## Error Handling
+
+```python
+from snapapi import SnapAPI, SnapAPIError
+
+snap = SnapAPI("snap_your_key_here")
+
+try:
+    image = snap.screenshot("example.com")
+except SnapAPIError as e:
+    print(f"Status: {e.status}, Message: {e.message}")
+```
+
+## Requirements
+
+- Python 3.7+
+- `requests` >= 2.20.0
+
+## License
+
+MIT

snapapi_python-1.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snapapi_python-1.3.0/setup.py

@@ -0,0 +1,12 @@
+from setuptools import setup
+
+setup(
+    name="snapapi-python",
+    version="1.3.0",
+    description="Official Python SDK for SnapAPI — screenshot, metadata extraction, and HTML rendering",
+    py_modules=["snapapi"],
+    python_requires=">=3.7",
+    install_requires=["requests>=2.20.0"],
+    license="MIT",
+    keywords=["screenshot", "api", "webpage-capture", "snapapi"],
+)

snapapi_python-1.3.0/snapapi.py

@@ -0,0 +1,269 @@
+"""
+SnapAPI Python SDK — capture any website as an image.
+
+Usage:
+    from snapapi import SnapAPI
+
+    snap = SnapAPI("snap_your_key_here")
+    image = snap.screenshot("example.com")
+"""
+
+import requests
+
+
+class SnapAPIError(Exception):
+    """Raised when the SnapAPI returns a non-2xx response."""
+
+    def __init__(self, status, message, body=None):
+        self.status = status
+        self.message = message
+        self.body = body
+        super().__init__(f"SnapAPI Error {status}: {message}")
+
+
+class SnapAPI:
+    """Client for the SnapAPI screenshot service."""
+
+    def __init__(self, api_key, base_url="https://snapapi.tech"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+        self._session.headers.update({"X-Api-Key": self.api_key})
+
+    def _request(self, method, path, params=None, json=None):
+        """Send a request and return the response, raising on errors."""
+        url = f"{self.base_url}{path}"
+        resp = self._session.request(method, url, params=params, json=json)
+
+        if not resp.ok:
+            try:
+                body = resp.json()
+                message = body.get("error", body.get("message", resp.reason))
+            except ValueError:
+                body = None
+                message = resp.reason or resp.text
+            raise SnapAPIError(resp.status_code, message, body)
+
+        return resp
+
+    @staticmethod
+    def _bool_param(value):
+        """Convert a Python bool to a query-string friendly string."""
+        return "true" if value else "false"
+
+    def screenshot(self, url, width=1280, height=800, format="png", quality=80,
+                   full_page=False, delay=0, dark_mode=False, block_ads=False,
+                   cache=True, selector=None, meta=False, device=None):
+        """Capture a screenshot of the given URL.
+
+        Returns bytes (raw image data) by default.
+        When meta=True, returns a dict with page metadata instead.
+        """
+        params = {
+            "url": url,
+            "width": width,
+            "height": height,
+            "format": format,
+            "quality": quality,
+            "full_page": self._bool_param(full_page),
+            "delay": delay,
+            "dark_mode": self._bool_param(dark_mode),
+            "block_ads": self._bool_param(block_ads),
+            "cache": self._bool_param(cache),
+            "meta": self._bool_param(meta),
+        }
+
+        if selector is not None:
+            params["selector"] = selector
+        if device is not None:
+            params["device"] = device
+
+        resp = self._request("GET", "/v1/screenshot", params=params)
+
+        content_type = resp.headers.get("Content-Type", "")
+        if "application/json" in content_type:
+            return resp.json()
+
+        return resp.content
+
+    def metadata(self, url):
+        """Extract metadata from a URL without taking a screenshot.
+
+        Returns title, description, OG tags, favicon, headings, links, and more.
+        Available on all plans.
+
+        Args:
+            url: The webpage URL to extract metadata from.
+
+        Returns:
+            dict with metadata fields.
+        """
+        resp = self._request("GET", "/v1/metadata", params={"url": url})
+        return resp.json()
+
+    def render(self, html, width=1200, height=630, format="png", quality=90):
+        """Render raw HTML to an image (PNG, JPEG, or WebP).
+
+        Perfect for OG cards, email previews, and dashboard exports.
+        Requires Starter tier or above.
+
+        Args:
+            html: Full HTML string to render (max 2MB).
+            width: Viewport width in pixels (default 1200).
+            height: Viewport height in pixels (default 630).
+            format: Output format — 'png', 'jpeg', or 'webp' (default 'png').
+            quality: Image quality 1-100 for jpeg/webp (default 90).
+
+        Returns:
+            bytes (raw image data).
+        """
+        resp = self._request("POST", "/v1/render", json={
+            "html": html,
+            "width": width,
+            "height": height,
+            "format": format,
+            "quality": quality,
+        })
+        return resp.content
+
+    def usage(self):
+        """Return current usage statistics (tier, usage count, limits)."""
+        resp = self._request("GET", "/v1/usage")
+        return resp.json()
+
+    def account(self):
+        """Return full account information."""
+        resp = self._request("GET", "/v1/account")
+        return resp.json()
+
+    def update_settings(self, name=None, allowed_domains=None):
+        """Update account settings.
+
+        Args:
+            name: Display name to set.
+            allowed_domains: List of allowed domains for the API key.
+
+        Returns:
+            dict with updated settings.
+        """
+        payload = {}
+        if name is not None:
+            payload["name"] = name
+        if allowed_domains is not None:
+            payload["allowed_domains"] = allowed_domains
+
+        resp = self._request("POST", "/v1/account/settings", json=payload)
+        return resp.json()
+
+    # ─── Monitors (Scheduled Screenshots) ───
+
+    def create_monitor(self, url, interval_minutes, name=None, params=None, webhook_url=None):
+        """Create a new scheduled monitor.
+
+        Args:
+            url: URL to monitor.
+            interval_minutes: Capture interval in minutes.
+            name: Optional display name.
+            params: Optional screenshot options dict (width, height, format, etc.).
+            webhook_url: Optional webhook URL for notifications.
+
+        Returns:
+            dict with monitor details.
+        """
+        payload = {"url": url, "interval_minutes": interval_minutes}
+        if name is not None:
+            payload["name"] = name
+        if params is not None:
+            payload["params"] = params
+        if webhook_url is not None:
+            payload["webhook_url"] = webhook_url
+
+        resp = self._request("POST", "/v1/monitors", json=payload)
+        return resp.json()
+
+    def list_monitors(self):
+        """List all monitors for this API key.
+
+        Returns:
+            list of monitor dicts.
+        """
+        resp = self._request("GET", "/v1/monitors")
+        return resp.json()
+
+    def get_monitor(self, monitor_id):
+        """Get a single monitor by ID.
+
+        Returns:
+            dict with monitor details.
+        """
+        resp = self._request("GET", f"/v1/monitors/{monitor_id}")
+        return resp.json()
+
+    def update_monitor(self, monitor_id, **kwargs):
+        """Update a monitor.
+
+        Keyword Args:
+            name: New display name.
+            interval_minutes: New interval.
+            status: 'active' or 'paused'.
+            params: New screenshot options dict.
+            webhook_url: New webhook URL.
+
+        Returns:
+            dict with updated monitor.
+        """
+        resp = self._request("PATCH", f"/v1/monitors/{monitor_id}", json=kwargs)
+        return resp.json()
+
+    def delete_monitor(self, monitor_id):
+        """Delete a monitor and all its snapshots."""
+        self._request("DELETE", f"/v1/monitors/{monitor_id}")
+
+    def list_snapshots(self, monitor_id, limit=50, offset=0):
+        """List snapshots for a monitor.
+
+        Args:
+            monitor_id: Monitor ID.
+            limit: Max results (default 50).
+            offset: Pagination offset.
+
+        Returns:
+            dict with snapshots list, total, limit, offset.
+        """
+        resp = self._request("GET", f"/v1/monitors/{monitor_id}/snapshots",
+                             params={"limit": limit, "offset": offset})
+        return resp.json()
+
+    def get_snapshot(self, monitor_id, snapshot_id):
+        """Download a specific snapshot image.
+
+        Returns:
+            bytes (raw image data).
+        """
+        resp = self._request("GET", f"/v1/monitors/{monitor_id}/snapshots/{snapshot_id}")
+        return resp.content
+
+    @staticmethod
+    def signup(email, base_url="https://snapapi.tech"):
+        """Create a new SnapAPI account. No API key required.
+
+        Args:
+            email: Email address for the new account.
+            base_url: API base URL.
+
+        Returns:
+            dict with key, tier, and limit.
+        """
+        url = f"{base_url.rstrip('/')}/v1/signup"
+        resp = requests.post(url, json={"email": email})
+
+        if not resp.ok:
+            try:
+                body = resp.json()
+                message = body.get("error", body.get("message", resp.reason))
+            except ValueError:
+                body = None
+                message = resp.reason or resp.text
+            raise SnapAPIError(resp.status_code, message, body)
+
+        return resp.json()

snapapi_python-1.3.0/snapapi_python.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: snapapi-python
+Version: 1.3.0
+Summary: Official Python SDK for SnapAPI — screenshot, metadata extraction, and HTML rendering
+License: MIT
+Keywords: screenshot,api,webpage-capture,snapapi
+Requires-Python: >=3.7
+Requires-Dist: requests>=2.20.0
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

snapapi_python-1.3.0/snapapi_python.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+setup.py
+snapapi.py
+snapapi_python.egg-info/PKG-INFO
+snapapi_python.egg-info/SOURCES.txt
+snapapi_python.egg-info/dependency_links.txt
+snapapi_python.egg-info/requires.txt
+snapapi_python.egg-info/top_level.txt

snapapi_python-1.3.0/snapapi_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

snapapi_python-1.3.0/snapapi_python.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.20.0

snapapi_python-1.3.0/snapapi_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+snapapi