capture-sdk 1.0.0__tar.gz

capture_sdk-1.0.0/.gitignore

@@ -0,0 +1,54 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+*.so
+
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+.ruff_cache
+
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+.DS_Store

capture_sdk-1.0.0/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.

capture_sdk-1.0.0/PKG-INFO

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

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

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "capture-sdk"
+version = "1.0.0"
+description = "Python SDK for Capture - Screenshot and content extraction API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Capture Team", email = "support@capture.page"}
+]
+keywords = ["capture", "screenshot", "pdf", "web scraping", "content extraction"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+]
+dependencies = [
+    "aiohttp>=3.8.0",
+    "yarl>=1.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://capture.page"
+Documentation = "https://docs.capture.page"
+Repository = "https://github.com/techulus/capture-py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/capture"]
+
+[tool.black]
+line-length = 88
+target-version = ["py38"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

capture_sdk-1.0.0/pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*

capture_sdk-1.0.0/src/capture/__init__.py

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

capture_sdk-1.0.0/src/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()