capture-sdk 1.0.0__py3-none-any.whl

capture/__init__.py

@@ -0,0 +1,4 @@
+from .client import Capture, RequestOptions, RequestType
+
+__version__ = "1.0.0"
+__all__ = ["Capture", "RequestOptions", "RequestType"]

capture/client.py

@@ -0,0 +1,112 @@
+import hashlib
+from typing import Any, Dict, Literal, Optional, Union
+from urllib.parse import urlencode
+
+import aiohttp
+from yarl import URL
+
+RequestType = Literal["image", "pdf", "content", "metadata", "animated"]
+RequestOptions = Dict[str, Union[str, int, bool]]
+
+class Capture:
+    API_URL = "https://cdn.capture.page"
+    EDGE_URL = "https://edge.capture.page"
+
+    def __init__(
+        self, key: str, secret: str, options: Optional[Dict[str, bool]] = None
+    ) -> None:
+        self.key = key
+        self.secret = secret
+        self.options = options or {}
+
+    def _generate_token(self, secret: str, url: str) -> str:
+        token_string = f"{secret}{url}"
+        return hashlib.md5(token_string.encode()).hexdigest()
+
+    def _encode_query_string(self, params: Dict[str, Any]) -> str:
+        filtered_params = {}
+        for k, v in params.items():
+            if v is None:
+                continue
+            if isinstance(v, bool):
+                filtered_params[k] = str(v).lower()
+            else:
+                filtered_params[k] = v
+
+        return urlencode(filtered_params, safe="")
+
+    def _build_url(
+        self, url: str, request_type: RequestType, options: Optional[RequestOptions] = None
+    ) -> str:
+        if not self.key or not self.secret:
+            raise ValueError("Key and Secret is required")
+
+        if url is None:
+            raise ValueError("url is required")
+
+        if not isinstance(url, str):
+            raise TypeError("url should be of type string (something like www.google.com)")
+
+        params = options.copy() if options else {}
+        params["url"] = url
+
+        query_string = self._encode_query_string(params)
+        token = self._generate_token(self.secret, query_string)
+
+        base_url = self.EDGE_URL if self.options.get("useEdge") else self.API_URL
+
+        return f"{base_url}/{self.key}/{token}/{request_type}?{query_string}"
+
+    def build_image_url(self, url: str, options: Optional[RequestOptions] = None) -> str:
+        return self._build_url(url, "image", options)
+
+    def build_pdf_url(self, url: str, options: Optional[RequestOptions] = None) -> str:
+        return self._build_url(url, "pdf", options)
+
+    def build_content_url(self, url: str, options: Optional[RequestOptions] = None) -> str:
+        return self._build_url(url, "content", options)
+
+    def build_metadata_url(self, url: str, options: Optional[RequestOptions] = None) -> str:
+        return self._build_url(url, "metadata", options)
+
+    def build_animated_url(self, url: str, options: Optional[RequestOptions] = None) -> str:
+        return self._build_url(url, "animated", options)
+
+    async def fetch_image(self, url: str, options: Optional[RequestOptions] = None) -> bytes:
+        fetch_url = self.build_image_url(url, options)
+        async with aiohttp.ClientSession() as session:
+            async with session.get(URL(fetch_url, encoded=True)) as response:
+                response.raise_for_status()
+                return await response.read()
+
+    async def fetch_pdf(self, url: str, options: Optional[RequestOptions] = None) -> bytes:
+        fetch_url = self.build_pdf_url(url, options)
+        async with aiohttp.ClientSession() as session:
+            async with session.get(URL(fetch_url, encoded=True)) as response:
+                response.raise_for_status()
+                return await response.read()
+
+    async def fetch_content(
+        self, url: str, options: Optional[RequestOptions] = None
+    ) -> Dict[str, Union[bool, str]]:
+        fetch_url = self.build_content_url(url, options)
+        async with aiohttp.ClientSession() as session:
+            async with session.get(URL(fetch_url, encoded=True)) as response:
+                response.raise_for_status()
+                return await response.json()
+
+    async def fetch_metadata(
+        self, url: str, options: Optional[RequestOptions] = None
+    ) -> Dict[str, Union[bool, Dict[str, Union[str, int]]]]:
+        fetch_url = self.build_metadata_url(url, options)
+        async with aiohttp.ClientSession() as session:
+            async with session.get(URL(fetch_url, encoded=True)) as response:
+                response.raise_for_status()
+                return await response.json()
+
+    async def fetch_animated(self, url: str, options: Optional[RequestOptions] = None) -> bytes:
+        fetch_url = self.build_animated_url(url, options)
+        async with aiohttp.ClientSession() as session:
+            async with session.get(URL(fetch_url, encoded=True)) as response:
+                response.raise_for_status()
+                return await response.read()

capture_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: capture-sdk
+Version: 1.0.0
+Summary: Python SDK for Capture - Screenshot and content extraction API
+Project-URL: Homepage, https://capture.page
+Project-URL: Documentation, https://docs.capture.page
+Project-URL: Repository, https://github.com/techulus/capture-py
+Author-email: Capture Team <support@capture.page>
+License: MIT
+License-File: LICENSE
+Keywords: capture,content extraction,pdf,screenshot,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.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
+Requires-Python: >=3.8
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: yarl>=1.9.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Capture Python SDK
+
+Official Python SDK for [Capture](https://capture.page) - Screenshot and content extraction API.
+
+## Installation
+
+```bash
+pip install capture-sdk
+```
+
+## Quick Start
+
+```python
+from capture import Capture
+
+client = Capture("your-api-key", "your-api-secret")
+
+image_url = client.build_image_url("https://example.com")
+print(image_url)
+```
+
+## Features
+
+- **Screenshot Capture**: Capture full-page or viewport screenshots as PNG/JPG
+- **PDF Generation**: Convert web pages to PDF documents
+- **Content Extraction**: Extract HTML and text content from web pages
+- **Metadata Extraction**: Get page metadata (title, description, og tags, etc.)
+- **Animated GIFs**: Create animated GIFs of page interactions
+- **Async Support**: Built-in async/await support for all fetch methods
+- **Type Hints**: Full type hint support for better IDE integration
+
+## Usage
+
+### Initialize the Client
+
+```python
+from capture import Capture
+
+client = Capture("your-api-key", "your-api-secret")
+
+client_with_edge = Capture("your-api-key", "your-api-secret", {"useEdge": True})
+```
+
+### Building URLs
+
+The SDK provides URL builders for each capture type:
+
+#### Image Capture
+
+```python
+image_url = client.build_image_url("https://example.com")
+
+image_url_with_options = client.build_image_url(
+    "https://example.com",
+    {
+        "full": True,
+        "delay": 2,
+        "width": 1920,
+        "height": 1080,
+        "quality": 90
+    }
+)
+```
+
+#### PDF Capture
+
+```python
+pdf_url = client.build_pdf_url("https://example.com")
+
+pdf_url_with_options = client.build_pdf_url(
+    "https://example.com",
+    {
+        "full": True,
+        "delay": 1
+    }
+)
+```
+
+#### Content Extraction
+
+```python
+content_url = client.build_content_url("https://example.com")
+```
+
+#### Metadata Extraction
+
+```python
+metadata_url = client.build_metadata_url("https://example.com")
+```
+
+#### Animated GIF
+
+```python
+animated_url = client.build_animated_url("https://example.com")
+```
+
+### Fetching Data (Async)
+
+The SDK provides async methods to fetch data directly:
+
+#### Fetch Image
+
+```python
+import asyncio
+
+async def main():
+    image_data = await client.fetch_image("https://example.com")
+    with open("screenshot.png", "wb") as f:
+        f.write(image_data)
+
+asyncio.run(main())
+```
+
+#### Fetch PDF
+
+```python
+async def main():
+    pdf_data = await client.fetch_pdf("https://example.com", {"full": True})
+    with open("page.pdf", "wb") as f:
+        f.write(pdf_data)
+
+asyncio.run(main())
+```
+
+#### Fetch Content
+
+```python
+async def main():
+    content = await client.fetch_content("https://example.com")
+    print(content["html"])
+    print(content["textContent"])
+
+asyncio.run(main())
+```
+
+#### Fetch Metadata
+
+```python
+async def main():
+    metadata = await client.fetch_metadata("https://example.com")
+    print(metadata["metadata"])
+
+asyncio.run(main())
+```
+
+#### Fetch Animated GIF
+
+```python
+async def main():
+    gif_data = await client.fetch_animated("https://example.com")
+    with open("animation.gif", "wb") as f:
+        f.write(gif_data)
+
+asyncio.run(main())
+```
+
+## Configuration Options
+
+### Constructor Options
+
+- `useEdge` (bool): Use edge.capture.page instead of cdn.capture.page for faster response times
+
+## API Endpoints
+
+The SDK supports two base URLs:
+
+- **CDN**: `https://cdn.capture.page` (default)
+- **Edge**: `https://edge.capture.page` (when `useEdge: True`)
+
+## Type Hints
+
+The SDK includes full type hint support:
+
+```python
+from capture import Capture, RequestOptions
+
+options: RequestOptions = {
+    "full": True,
+    "delay": 2,
+    "width": 1920
+}
+
+client = Capture("key", "secret")
+url: str = client.build_image_url("https://example.com", options)
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Website](https://capture.page)
+- [Documentation](https://docs.capture.page)
+- [API Reference](https://docs.capture.page/api)
+- [GitHub](https://github.com/techulus/capture-py)
+
+## Support
+
+For support, please visit [capture.page](https://capture.page) or open an issue on GitHub.

capture_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+capture/__init__.py,sha256=3RpAQG7CO8xHURLGCra60xZer5NAW7tXfQr-MEAZWJs,135
+capture/client.py,sha256=0rP8PSPp8fGFk6zWgTq5Z6HoaQoHpUcsfQZOp7CFeTc,4614
+capture_sdk-1.0.0.dist-info/METADATA,sha256=At4FktGn1V0Nik0_y1DbPIvE-QIJA5PM9HyOkYCwTUM,5296
+capture_sdk-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+capture_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=qz-tHQmZDgzuwpEY4svMP2ZdakvId2QPv-VYoU-zybA,1069
+capture_sdk-1.0.0.dist-info/RECORD,,

capture_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

capture_sdk-1.0.0.dist-info/licenses/LICENSE

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