formepdf 0.7.9__tar.gz

formepdf-0.7.9/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+forme/forme.wasm

formepdf-0.7.9/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: formepdf
+Version: 0.7.9
+Summary: Python SDK for the Forme hosted PDF API
+Project-URL: Homepage, https://formepdf.com
+Project-URL: Documentation, https://docs.formepdf.com
+Project-URL: Repository, https://github.com/formepdf/forme
+Author-email: Dan Molitor <danmolitor91@gmail.com>
+License-Expression: MIT
+Keywords: api,forme,pdf,sdk
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: local
+Requires-Dist: wasmtime>=20.0; extra == 'local'
+Description-Content-Type: text/markdown
+
+# forme
+
+Python SDK for the [Forme](https://formepdf.com) hosted PDF API.
+
+## Installation
+
+```bash
+pip install forme
+```
+
+## Quick Start
+
+```python
+from forme import Forme
+
+client = Forme("forme_sk_...")
+
+# Render a template to PDF bytes
+pdf = client.render("invoice", {"customer": "Acme", "total": 100})
+
+with open("invoice.pdf", "wb") as f:
+    f.write(pdf)
+```
+
+## API Reference
+
+### `Forme(api_key, base_url="https://api.formepdf.com")`
+
+Create a client instance.
+
+### `client.render(slug, data=None, *, s3=None)`
+
+Render a template synchronously. Returns `bytes` (PDF), or a `dict` with `{"url": "..."}` when `s3` is provided.
+
+```python
+# Direct PDF bytes
+pdf = client.render("invoice", {"customer": "Acme"})
+
+# Upload to S3
+result = client.render("invoice", {"customer": "Acme"}, s3={
+    "bucket": "my-bucket",
+    "key": "invoices/001.pdf",
+    "accessKeyId": "AK...",
+    "secretAccessKey": "SK...",
+})
+print(result["url"])
+```
+
+### `client.render_async(slug, data=None, *, webhook_url=None)`
+
+Start an asynchronous render job. Returns `{"jobId": "...", "status": "pending"}`.
+
+```python
+job = client.render_async("report", data, webhook_url="https://example.com/hook")
+print(job["jobId"])
+```
+
+### `client.get_job(job_id)`
+
+Poll the status of an async job.
+
+```python
+result = client.get_job("job-123")
+if result["status"] == "complete":
+    pdf_b64 = result["pdfBase64"]
+```
+
+### `client.extract(pdf_bytes)`
+
+Extract embedded data from a PDF. Returns the data dict, or `None` if none is embedded.
+
+```python
+data = client.extract(pdf_bytes)
+```
+
+## Error Handling
+
+All methods raise `FormeError` on non-2xx responses:
+
+```python
+from forme import Forme, FormeError
+
+try:
+    pdf = client.render("invoice", data)
+except FormeError as e:
+    print(f"Error {e.status}: {e.message}")
+```
+
+## Requirements
+
+- Python 3.8+
+- No dependencies (stdlib only)

formepdf-0.7.9/README.md

@@ -0,0 +1,92 @@
+# forme
+
+Python SDK for the [Forme](https://formepdf.com) hosted PDF API.
+
+## Installation
+
+```bash
+pip install forme
+```
+
+## Quick Start
+
+```python
+from forme import Forme
+
+client = Forme("forme_sk_...")
+
+# Render a template to PDF bytes
+pdf = client.render("invoice", {"customer": "Acme", "total": 100})
+
+with open("invoice.pdf", "wb") as f:
+    f.write(pdf)
+```
+
+## API Reference
+
+### `Forme(api_key, base_url="https://api.formepdf.com")`
+
+Create a client instance.
+
+### `client.render(slug, data=None, *, s3=None)`
+
+Render a template synchronously. Returns `bytes` (PDF), or a `dict` with `{"url": "..."}` when `s3` is provided.
+
+```python
+# Direct PDF bytes
+pdf = client.render("invoice", {"customer": "Acme"})
+
+# Upload to S3
+result = client.render("invoice", {"customer": "Acme"}, s3={
+    "bucket": "my-bucket",
+    "key": "invoices/001.pdf",
+    "accessKeyId": "AK...",
+    "secretAccessKey": "SK...",
+})
+print(result["url"])
+```
+
+### `client.render_async(slug, data=None, *, webhook_url=None)`
+
+Start an asynchronous render job. Returns `{"jobId": "...", "status": "pending"}`.
+
+```python
+job = client.render_async("report", data, webhook_url="https://example.com/hook")
+print(job["jobId"])
+```
+
+### `client.get_job(job_id)`
+
+Poll the status of an async job.
+
+```python
+result = client.get_job("job-123")
+if result["status"] == "complete":
+    pdf_b64 = result["pdfBase64"]
+```
+
+### `client.extract(pdf_bytes)`
+
+Extract embedded data from a PDF. Returns the data dict, or `None` if none is embedded.
+
+```python
+data = client.extract(pdf_bytes)
+```
+
+## Error Handling
+
+All methods raise `FormeError` on non-2xx responses:
+
+```python
+from forme import Forme, FormeError
+
+try:
+    pdf = client.render("invoice", data)
+except FormeError as e:
+    print(f"Error {e.status}: {e.message}")
+```
+
+## Requirements
+
+- Python 3.8+
+- No dependencies (stdlib only)

formepdf-0.7.9/build_wasm.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Build the Forme engine as a WASI WASM module for use with Python wasmtime.
+# Output: forme/forme.wasm
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ENGINE_DIR="$SCRIPT_DIR/../../engine"
+
+echo "Building Forme WASM (wasm32-wasip1, release)..."
+cargo build \
+  --manifest-path "$ENGINE_DIR/Cargo.toml" \
+  --lib \
+  --target wasm32-wasip1 \
+  --release \
+  --features wasm-raw
+
+WASM_SRC="$ENGINE_DIR/target/wasm32-wasip1/release/forme.wasm"
+WASM_DST="$SCRIPT_DIR/forme/forme.wasm"
+
+cp "$WASM_SRC" "$WASM_DST"
+echo "Copied to $WASM_DST ($(du -h "$WASM_DST" | cut -f1))"

formepdf-0.7.9/forme/__init__.py

@@ -0,0 +1,40 @@
+"""Forme Python SDK — client for the Forme hosted PDF API and local rendering."""
+
+from .client import Forme, FormeError
+from .templates import (
+    Document,
+    Page,
+    View,
+    Text,
+    Image,
+    Table,
+    Row,
+    Cell,
+    Svg,
+    QrCode,
+    Barcode,
+    PageBreak,
+    Fixed,
+    Watermark,
+)
+
+__all__ = [
+    # API client
+    "Forme",
+    "FormeError",
+    # Template components
+    "Document",
+    "Page",
+    "View",
+    "Text",
+    "Image",
+    "Table",
+    "Row",
+    "Cell",
+    "Svg",
+    "QrCode",
+    "Barcode",
+    "PageBreak",
+    "Fixed",
+    "Watermark",
+]

formepdf-0.7.9/forme/client.py

@@ -0,0 +1,151 @@
+"""Forme API client. Zero dependencies — uses stdlib urllib + json."""
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional, Union
+
+
+class FormeError(Exception):
+    """Raised on non-2xx responses from the Forme API."""
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        self.message = message
+        super().__init__(message)
+
+
+class Forme:
+    """Client for the Forme hosted PDF API.
+
+    Args:
+        api_key: API key (e.g. ``"forme_sk_..."``).
+        base_url: Base URL of the API. Defaults to ``https://api.formepdf.com``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.formepdf.com",
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def render(
+        self,
+        slug: str,
+        data: Any = None,
+        *,
+        s3: Optional[Dict[str, Any]] = None,
+    ) -> Union[bytes, Dict[str, Any]]:
+        """Render a template to PDF (synchronous).
+
+        Returns raw PDF bytes, or a dict with ``{"url": "..."}`` when *s3*
+        is provided.
+        """
+        body: Dict[str, Any] = dict(data) if data is not None else {}
+        if s3 is not None:
+            body["s3"] = s3
+
+        resp_body, content_type = self._request(
+            "POST",
+            "/v1/render/{}".format(slug),
+            body=body,
+        )
+
+        if content_type is not None and "application/json" in content_type:
+            return json.loads(resp_body)  # type: ignore[no-any-return]
+        return resp_body
+
+    def render_async(
+        self,
+        slug: str,
+        data: Any = None,
+        *,
+        webhook_url: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Start an asynchronous render job.
+
+        Returns ``{"jobId": "...", "status": "pending"}``.
+        """
+        body: Dict[str, Any] = dict(data) if data is not None else {}
+        if webhook_url is not None:
+            body["webhookUrl"] = webhook_url
+
+        resp_body, _ = self._request(
+            "POST",
+            "/v1/render/{}/async".format(slug),
+            body=body,
+        )
+        return json.loads(resp_body)  # type: ignore[no-any-return]
+
+    def get_job(self, job_id: str) -> Dict[str, Any]:
+        """Poll the status of an async render job."""
+        resp_body, _ = self._request("GET", "/v1/jobs/{}".format(job_id))
+        return json.loads(resp_body)  # type: ignore[no-any-return]
+
+    def extract(self, pdf_bytes: bytes) -> Any:
+        """Extract embedded data from a PDF.
+
+        Returns the embedded data dict, or ``None`` if the PDF has no
+        embedded data.
+        """
+        try:
+            resp_body, _ = self._request(
+                "POST",
+                "/v1/extract",
+                body=pdf_bytes,
+                content_type="application/pdf",
+            )
+            result = json.loads(resp_body)
+            return result.get("data")
+        except FormeError as exc:
+            if exc.status == 404 and "no embedded data" in exc.message.lower():
+                return None
+            raise
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        content_type: str = "application/json",
+    ) -> tuple:
+        """Send an HTTP request and return ``(response_bytes, content_type)``."""
+        url = self._base_url + path
+
+        if isinstance(body, bytes):
+            data = body
+        elif body is not None:
+            data = json.dumps(body).encode("utf-8")
+        else:
+            data = None
+
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", "Bearer {}".format(self._api_key))
+        if data is not None:
+            req.add_header("Content-Type", content_type)
+
+        try:
+            resp = urllib.request.urlopen(req)
+            resp_content_type = resp.headers.get("Content-Type")
+            return resp.read(), resp_content_type
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            message = "Request failed with status {}".format(status)
+            try:
+                err_body = json.loads(exc.read())
+                if isinstance(err_body, dict):
+                    message = err_body.get("error") or err_body.get("message") or message
+            except (ValueError, TypeError):
+                pass
+            raise FormeError(status, message) from None