pdfik 0.1.0__py3-none-any.whl

pdfik/__init__.py

@@ -0,0 +1,34 @@
+from .client import PdfikClient, AsyncPdfikClient
+from .exceptions import PdfikError
+from .models import (
+    PaperFormat,
+    WaitUntilEvent,
+    JobStatus,
+    MarginOptions,
+    WatermarkOptions,
+    CompressionOptions,
+    PdfOptions,
+    RenderOptions,
+    JobCreatedResponse,
+    JobMetrics,
+    JobStatusResponse,
+    JobFileResponse,
+)
+
+__all__ = [
+    "PdfikClient",
+    "AsyncPdfikClient",
+    "PdfikError",
+    "PaperFormat",
+    "WaitUntilEvent",
+    "JobStatus",
+    "MarginOptions",
+    "WatermarkOptions",
+    "CompressionOptions",
+    "PdfOptions",
+    "RenderOptions",
+    "JobCreatedResponse",
+    "JobMetrics",
+    "JobStatusResponse",
+    "JobFileResponse",
+]

pdfik/client.py

@@ -0,0 +1,265 @@
+import time
+import asyncio
+from typing import Optional
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception
+
+from .exceptions import PdfikError
+from .models import (
+    JobCreatedResponse,
+    JobStatusResponse,
+    JobFileResponse,
+    PdfOptions,
+    RenderOptions,
+    _to_dict
+)
+
+def _is_retryable_exception(exception: BaseException) -> bool:
+    return isinstance(exception, PdfikError) and (exception.status_code >= 500 or exception.status_code == 429)
+
+class PdfikClient:
+    def __init__(self, api_key: str, base_url: str = "https://api.pdfik.net"):
+        if not api_key:
+            raise ValueError("API key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.client = httpx.Client()
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=4),
+        retry=retry_if_exception(_is_retryable_exception),
+        reraise=True
+    )
+    def _request(self, method: str, path: str, json_data: Optional[dict] = None) -> httpx.Response:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "X-API-Key": self.api_key,
+        }
+        
+        try:
+            response = self.client.request(method, url, headers=headers, json=json_data)
+        except httpx.RequestError as exc:
+            raise PdfikError(f"Connection failed: {exc}", 503)
+
+        if response.is_error:
+            error_code = None
+            message = f"API request failed with status {response.status_code}"
+            response_body = response.text
+            try:
+                data = response.json()
+                if isinstance(data, dict):
+                    message = data.get("detail", message)
+                    error_code = data.get("error_code")
+            except Exception:
+                pass
+            raise PdfikError(message, response.status_code, error_code, response_body)
+            
+        return response
+
+    def url_to_pdf(
+        self,
+        url: str,
+        *,
+        webhook_url: Optional[str] = None,
+        options: Optional[PdfOptions] = None,
+        render: Optional[RenderOptions] = None
+    ) -> JobCreatedResponse:
+        body = {"url": url}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if options:
+            body["options"] = _to_dict(options)
+        if render:
+            body["render"] = _to_dict(render)
+
+        res = self._request("POST", "/url-to-pdf", json_data=body)
+        return JobCreatedResponse.from_dict(res.json())
+
+    def html_to_pdf(
+        self,
+        html: str,
+        *,
+        webhook_url: Optional[str] = None,
+        options: Optional[PdfOptions] = None,
+        render: Optional[RenderOptions] = None
+    ) -> JobCreatedResponse:
+        body = {"html": html}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if options:
+            body["options"] = _to_dict(options)
+        if render:
+            body["render"] = _to_dict(render)
+
+        res = self._request("POST", "/html-to-pdf", json_data=body)
+        return JobCreatedResponse.from_dict(res.json())
+
+    def get_job(self, job_id: str) -> JobStatusResponse:
+        res = self._request("GET", f"/jobs/{job_id}")
+        return JobStatusResponse.from_dict(res.json())
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        timeout: int = 120,
+        poll_interval: int = 2
+    ) -> JobStatusResponse:
+        start_time = time.time()
+        while True:
+            job = self.get_job(job_id)
+            if job.status in ("done", "failed"):
+                if job.status == "failed":
+                    raise PdfikError(
+                        f"Job {job_id} failed",
+                        400,
+                        job.error_code or "JOB_FAILED"
+                    )
+                return job
+                
+            if time.time() - start_time >= timeout:
+                raise PdfikError(f"Job {job_id} timed out", 408, "TIMEOUT")
+                
+            time.sleep(poll_interval)
+
+    def get_file_url(self, job_id: str) -> JobFileResponse:
+        res = self._request("GET", f"/jobs/{job_id}/file")
+        return JobFileResponse.from_dict(res.json())
+
+    def download_pdf(self, job_id: str) -> bytes:
+        res = self._request("GET", f"/jobs/{job_id}/download")
+        return res.content
+
+    def close(self):
+        self.client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+class AsyncPdfikClient:
+    def __init__(self, api_key: str, base_url: str = "https://api.pdfik.net"):
+        if not api_key:
+            raise ValueError("API key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.client = httpx.AsyncClient()
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=4),
+        retry=retry_if_exception(_is_retryable_exception),
+        reraise=True
+    )
+    async def _request(self, method: str, path: str, json_data: Optional[dict] = None) -> httpx.Response:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "X-API-Key": self.api_key,
+        }
+        
+        try:
+            response = await self.client.request(method, url, headers=headers, json=json_data)
+        except httpx.RequestError as exc:
+            raise PdfikError(f"Connection failed: {exc}", 503)
+
+        if response.is_error:
+            error_code = None
+            message = f"API request failed with status {response.status_code}"
+            response_body = response.text
+            try:
+                data = response.json()
+                if isinstance(data, dict):
+                    message = data.get("detail", message)
+                    error_code = data.get("error_code")
+            except Exception:
+                pass
+            raise PdfikError(message, response.status_code, error_code, response_body)
+            
+        return response
+
+    async def url_to_pdf(
+        self,
+        url: str,
+        *,
+        webhook_url: Optional[str] = None,
+        options: Optional[PdfOptions] = None,
+        render: Optional[RenderOptions] = None
+    ) -> JobCreatedResponse:
+        body = {"url": url}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if options:
+            body["options"] = _to_dict(options)
+        if render:
+            body["render"] = _to_dict(render)
+
+        res = await self._request("POST", "/url-to-pdf", json_data=body)
+        return JobCreatedResponse.from_dict(res.json())
+
+    async def html_to_pdf(
+        self,
+        html: str,
+        *,
+        webhook_url: Optional[str] = None,
+        options: Optional[PdfOptions] = None,
+        render: Optional[RenderOptions] = None
+    ) -> JobCreatedResponse:
+        body = {"html": html}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if options:
+            body["options"] = _to_dict(options)
+        if render:
+            body["render"] = _to_dict(render)
+
+        res = await self._request("POST", "/html-to-pdf", json_data=body)
+        return JobCreatedResponse.from_dict(res.json())
+
+    async def get_job(self, job_id: str) -> JobStatusResponse:
+        res = await self._request("GET", f"/jobs/{job_id}")
+        return JobStatusResponse.from_dict(res.json())
+
+    async def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        timeout: int = 120,
+        poll_interval: int = 2
+    ) -> JobStatusResponse:
+        start_time = time.time()
+        while True:
+            job = await self.get_job(job_id)
+            if job.status in ("done", "failed"):
+                if job.status == "failed":
+                    raise PdfikError(
+                        f"Job {job_id} failed",
+                        400,
+                        job.error_code or "JOB_FAILED"
+                    )
+                return job
+                
+            if time.time() - start_time >= timeout:
+                raise PdfikError(f"Job {job_id} timed out", 408, "TIMEOUT")
+                
+            await asyncio.sleep(poll_interval)
+
+    async def get_file_url(self, job_id: str) -> JobFileResponse:
+        res = await self._request("GET", f"/jobs/{job_id}/file")
+        return JobFileResponse.from_dict(res.json())
+
+    async def download_pdf(self, job_id: str) -> bytes:
+        res = await self._request("GET", f"/jobs/{job_id}/download")
+        return res.content
+
+    async def close(self):
+        await self.client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

pdfik/exceptions.py

@@ -0,0 +1,18 @@
+from typing import Optional
+
+class PdfikError(Exception):
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        error_code: Optional[str] = None,
+        response_body: Optional[str] = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.response_body = response_body
+
+    def __str__(self):
+        code_str = f" [{self.error_code}]" if self.error_code else ""
+        return f"{self.args[0]} (HTTP {self.status_code}){code_str}"

pdfik/models.py

@@ -0,0 +1,155 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Any, Dict, Type, TypeVar, get_type_hints
+
+T = TypeVar('T')
+
+class PaperFormat(str, Enum):
+    A4 = "A4"
+    A3 = "A3"
+    LETTER = "Letter"
+    LEGAL = "Legal"
+    TABLOID = "Tabloid"
+
+class WaitUntilEvent(str, Enum):
+    LOAD = "load"
+    DOM_CONTENT_LOADED = "domcontentloaded"
+    NETWORK_IDLE = "networkidle"
+    COMMIT = "commit"
+
+class JobStatus(str, Enum):
+    QUEUED = "queued"
+    RENDERING = "rendering"
+    UPLOADING = "uploading"
+    DONE = "done"
+    FAILED = "failed"
+
+def _from_dict(cls: Type[T], data: Any) -> Any:
+    if data is None:
+        return None
+    if not isinstance(data, dict):
+        return data
+    
+    # Get class type hints
+    try:
+        type_hints = get_type_hints(cls)
+    except Exception:
+        type_hints = {}
+
+    kwargs = {}
+    for name, field_type in type_hints.items():
+        if name in data:
+            val = data[name]
+            # Handle list of nested models if any (currently none, but good to have)
+            # Handle nested dataclasses
+            if hasattr(field_type, '__dataclass_fields__'):
+                kwargs[name] = _from_dict(field_type, val)
+            # Handle Optional[dataclass]
+            elif hasattr(field_type, '__args__'):
+                # Extract the inner type from Union/Optional
+                args = field_type.__args__
+                inner_type = next((a for a in args if hasattr(a, '__dataclass_fields__')), None)
+                if inner_type and val is not None:
+                    kwargs[name] = _from_dict(inner_type, val)
+                else:
+                    kwargs[name] = val
+            else:
+                kwargs[name] = val
+    
+    return cls(**kwargs)
+
+def _to_dict(obj: Any) -> Any:
+    if hasattr(obj, '__dataclass_fields__'):
+        res = {}
+        for name in obj.__dataclass_fields__:
+            val = getattr(obj, name)
+            if val is not None:
+                res[name] = _to_dict(val)
+        return res
+    elif isinstance(obj, Enum):
+        return obj.value
+    elif isinstance(obj, list):
+        return [_to_dict(x) for x in obj]
+    elif isinstance(obj, dict):
+        return {k: _to_dict(v) for k, v in obj.items() if v is not None}
+    return obj
+
+@dataclass
+class MarginOptions:
+    top: Optional[str] = None
+    right: Optional[str] = None
+    bottom: Optional[str] = None
+    left: Optional[str] = None
+
+@dataclass
+class WatermarkOptions:
+    text: str
+    color: Optional[str] = None
+    font_size: Optional[str] = None
+    rotation_degrees: Optional[int] = None
+
+@dataclass
+class CompressionOptions:
+    level: Optional[int] = None
+    image_quality: Optional[int] = None
+
+@dataclass
+class PdfOptions:
+    format: Optional[PaperFormat] = None
+    landscape: Optional[bool] = None
+    margin: Optional[MarginOptions] = None
+    print_background: Optional[bool] = None
+    display_header_footer: Optional[bool] = None
+    header_template: Optional[str] = None
+    footer_template: Optional[str] = None
+    watermark: Optional[WatermarkOptions] = None
+    user_password: Optional[str] = None
+    compression: Optional[CompressionOptions] = None
+
+@dataclass
+class RenderOptions:
+    page_load_timeout_ms: Optional[int] = None
+    wait_until: Optional[WaitUntilEvent] = None
+    wait_for_selector: Optional[str] = None
+    wait_after_load_ms: Optional[int] = None
+
+@dataclass
+class JobCreatedResponse:
+    job_id: str
+    status: str
+    detail: str
+
+    @classmethod
+    def from_dict(cls: Type[T], data: dict) -> T:
+        return _from_dict(cls, data)
+
+@dataclass
+class JobMetrics:
+    file_size_bytes: Optional[int] = None
+    file_size_human: Optional[str] = None
+    page_load_ms: Optional[int] = None
+    total_duration_ms: Optional[int] = None
+    page_count: Optional[int] = None
+
+@dataclass
+class JobStatusResponse:
+    status: JobStatus
+    created_at: Optional[str] = None
+    finished_at: Optional[str] = None
+    pages_count: Optional[int] = None
+    error_code: Optional[str] = None
+    metrics: Optional[JobMetrics] = None
+
+    @classmethod
+    def from_dict(cls: Type[T], data: dict) -> T:
+        return _from_dict(cls, data)
+
+@dataclass
+class JobFileResponse:
+    job_id: str
+    download_url: str
+    expires_in_seconds: int
+
+    @classmethod
+    def from_dict(cls: Type[T], data: dict) -> T:
+        return _from_dict(cls, data)

pdfik-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: pdfik
+Version: 0.1.0
+Summary: Official Python SDK for the PDFik PDF generation API
+Author-email: PDFik <support@pdfik.net>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: tenacity>=8.0.0
+Provides-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: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pdfik
+
+Official Python SDK for [PDFik](https://pdfik.net) — the premium, fast, and reliable PDF generation API.
+
+Convert HTML markup or any public URL into pixel-perfect PDF documents in seconds, powered by scalable browser rendering.
+
+## Features
+
+- **Type Safety**: Type hints for all options and response objects.
+- **Sync & Async**: Exposes both `PdfikClient` and `AsyncPdfikClient` using the modern `httpx` engine.
+- **Auto Retry**: Automatic exponential backoff for `5xx` and `429` (Rate Limit) errors powered by `tenacity`.
+- **DX Affordances**: Built-in polling logic (`wait_for_job`) and file download helpers.
+
+## Installation
+
+```bash
+pip install pdfik
+```
+
+## Quick Start
+
+### Convert public URL to PDF (Sync)
+
+```python
+from pdfik import PdfikClient, PdfOptions, MarginOptions
+
+# Initialize the client
+client = PdfikClient(api_key="sk_live_...")
+
+# 1. Submit the URL to be rendered
+job = client.url_to_pdf(
+    "https://example.com",
+    options=PdfOptions(
+        format="A4",
+        landscape=False,
+        print_background=True,
+        margin=MarginOptions(top="10mm", bottom="10mm")
+    )
+)
+
+print(f"Job created: {job.job_id}. Waiting for rendering...")
+
+# 2. Poll until the job completes
+result = client.wait_for_job(job.job_id)
+print(f"Job finished! Pages: {result.pages_count}")
+
+# 3. Download the PDF bytes
+pdf_bytes = client.download_pdf(job.job_id)
+
+with open("output.pdf", "wb") as f:
+    f.write(pdf_bytes)
+print("PDF saved to output.pdf")
+
+# Close connection pool
+client.close()
+```
+
+### Convert raw HTML to PDF (Async)
+
+```python
+import asyncio
+from pdfik import AsyncPdfikClient, PdfOptions
+
+async def main():
+    async with AsyncPdfikClient(api_key="sk_live_...") as client:
+        job = await client.html_to_pdf(
+            "<h1>Hello World</h1><p>Sent from PDFik Python SDK</p>",
+            options=PdfOptions(format="Letter")
+        )
+        
+        result = await client.wait_for_job(job.job_id)
+        print(f"Job finished! Status: {result.status}")
+        
+        pdf_bytes = await client.download_pdf(job.job_id)
+
+asyncio.run(main())
+```
+
+### Get a temporary, pre-signed download URL
+
+If you prefer not to download the bytes directly through your application server, you can generate a secure pre-signed URL (expires in 15 minutes) for the user's browser to download:
+
+```python
+file_info = client.get_file_url(job.job_id)
+print(f"Download URL: {file_info.download_url}")
+```
+
+## License
+
+MIT License.

pdfik-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pdfik/__init__.py,sha256=cR3KgwwEMpUbBRb6fnOdYGF4EffdrbkJGvB3xvN8AWc,681
+pdfik/client.py,sha256=mPyA-QZvhZJRbs5net9X3PcuMcM9F0m16GiO-9P8kx0,8758
+pdfik/exceptions.py,sha256=XHvX7xqCkhNk-huNC3nmSEpeHPQrr90TU200hg92H18,547
+pdfik/models.py,sha256=Z0VdIM0KJ9OrMoDsHS2o-d1sRIbU1uvwVwSuwpIJoWQ,4384
+pdfik-0.1.0.dist-info/METADATA,sha256=ZFq7g1n6_Gkcpo4bvBG4LL7Cm5rfsQJKJkZIHzzANwY,3096
+pdfik-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pdfik-0.1.0.dist-info/RECORD,,

pdfik-0.1.0.dist-info/WHEEL

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