sharptoolz 0.2.0__tar.gz

sharptoolz-0.2.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: sharptoolz
+Version: 0.2.0
+Summary: Official Python client for the SharpToolz API
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websockets<16,>=12
+
+# SharpToolz Python SDK
+
+```bash
+# Available after the first PyPI release
+pip install sharptoolz
+```
+
+```python
+import os
+from sharptoolz import SharpToolz
+
+with SharpToolz(api_key=os.environ["SHARPTOOLZ_API_KEY"]) as sharp:
+    session = sharp.hosted_forms.create(
+        template_id=template_id,
+        external_user_id=current_user_id,
+        origin="https://app.example.com",
+        mode="test",
+        preview_mode="protected",
+    )
+
+    # Return session["embed_url"] to your frontend.
+```
+
+Only browser JavaScript mounts the returned URL with `@sharp-toolz/sdk/browser`.
+Python keeps the API key on your backend and can create or edit hosted sessions,
+list documents, and wait for PNG/PDF renders over a job-scoped WebSocket.

sharptoolz-0.2.0/README.md

@@ -0,0 +1,26 @@
+# SharpToolz Python SDK
+
+```bash
+# Available after the first PyPI release
+pip install sharptoolz
+```
+
+```python
+import os
+from sharptoolz import SharpToolz
+
+with SharpToolz(api_key=os.environ["SHARPTOOLZ_API_KEY"]) as sharp:
+    session = sharp.hosted_forms.create(
+        template_id=template_id,
+        external_user_id=current_user_id,
+        origin="https://app.example.com",
+        mode="test",
+        preview_mode="protected",
+    )
+
+    # Return session["embed_url"] to your frontend.
+```
+
+Only browser JavaScript mounts the returned URL with `@sharp-toolz/sdk/browser`.
+Python keeps the API key on your backend and can create or edit hosted sessions,
+list documents, and wait for PNG/PDF renders over a job-scoped WebSocket.

sharptoolz-0.2.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sharptoolz"
+version = "0.2.0"
+description = "Official Python client for the SharpToolz API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+  "httpx>=0.27,<1",
+  "websockets>=12,<16",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sharptoolz = ["py.typed"]

sharptoolz-0.2.0/setup.cfg

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

sharptoolz-0.2.0/src/sharptoolz/__init__.py

@@ -0,0 +1,4 @@
+from .client import SharpToolz, SharpToolzError
+
+__all__ = ["SharpToolz", "SharpToolzError"]
+__version__ = "0.1.0"

sharptoolz-0.2.0/src/sharptoolz/client.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Callable
+from urllib.parse import parse_qs, urlsplit
+from uuid import uuid4
+
+import httpx
+from websockets.sync.client import connect as websocket_connect_default
+
+
+DEFAULT_BASE_URL = "https://api.sharptoolz.com/api/v1"
+TERMINAL_RENDER_STATUSES = {"completed", "failed"}
+
+
+def _normalize_cursor(cursor: str | None) -> str | None:
+    if not cursor:
+        return None
+    parsed = urlsplit(cursor)
+    if parsed.scheme and parsed.netloc:
+        return parse_qs(parsed.query).get("cursor", [cursor])[0]
+    return cursor
+
+
+class SharpToolzError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int = 0, data: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.data = data
+
+
+class TemplatesResource:
+    def __init__(self, client: "SharpToolz"):
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client._request("GET", "/templates")
+
+class HostedFormsResource:
+    def __init__(self, client: "SharpToolz"):
+        self._client = client
+
+    def create(self, **payload: Any) -> dict[str, Any]:
+        return self._client._request("POST", "/embed-sessions", json=payload)
+
+    def edit(self, document_id: str, **payload: Any) -> dict[str, Any]:
+        return self._client._request("POST", f"/documents/{document_id}/session", json=payload)
+
+    def revoke(self, session_id: str) -> None:
+        self._client._request("DELETE", f"/embed-sessions/{session_id}")
+
+
+class DocumentsResource:
+    def __init__(self, client: "SharpToolz"):
+        self._client = client
+
+    def get(self, document_id: str) -> dict[str, Any]:
+        return self._client._request("GET", f"/documents/{document_id}")
+
+    def list(self, *, external_user_id: str | None = None, cursor: str | None = None) -> dict[str, Any]:
+        params = {key: value for key, value in {
+            "external_user_id": external_user_id,
+            "cursor": _normalize_cursor(cursor),
+        }.items() if value}
+        return self._client._request("GET", "/documents", params=params)
+
+    def delete(self, document_id: str) -> None:
+        self._client._request("DELETE", f"/documents/{document_id}")
+
+    def upgrade(self, document_id: str, *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            f"/documents/{document_id}/upgrade",
+            idempotency_key=idempotency_key or str(uuid4()),
+        )
+
+    def render(
+        self,
+        document_id: str,
+        *,
+        format: str = "pdf",
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        return self._client._request(
+            "POST",
+            f"/documents/{document_id}/render",
+            json={"format": format},
+            idempotency_key=idempotency_key or str(uuid4()),
+        )
+
+    def render_and_wait(
+        self,
+        document_id: str,
+        *,
+        format: str = "pdf",
+        idempotency_key: str | None = None,
+        timeout: float = 120,
+        poll_fallback: bool = True,
+    ) -> dict[str, Any]:
+        job = self.render(document_id, format=format, idempotency_key=idempotency_key)
+        return self._client.renders.wait(
+            job,
+            timeout=timeout,
+            poll_fallback=poll_fallback,
+        )
+
+
+class RendersResource:
+    def __init__(self, client: "SharpToolz"):
+        self._client = client
+
+    def get(self, job_id: str) -> dict[str, Any]:
+        return self._client._request("GET", f"/renders/{job_id}")
+
+    def wait(
+        self,
+        job_or_id: dict[str, Any] | str,
+        *,
+        timeout: float = 120,
+        poll_fallback: bool = True,
+    ) -> dict[str, Any]:
+        job = self.get(job_or_id) if isinstance(job_or_id, str) else job_or_id
+        if not job.get("id"):
+            raise TypeError("A render job or job ID is required.")
+        if job.get("status") in TERMINAL_RENDER_STATUSES:
+            return self._finish(job)
+
+        watch = self._client._request("POST", f"/renders/{job['id']}/watch")
+        try:
+            terminal = self._wait_on_websocket(watch["websocket_url"], timeout=timeout)
+            return self._finish(self.get(terminal["id"]))
+        except Exception:
+            if not poll_fallback:
+                raise
+            return self._wait_by_polling(job["id"], timeout=timeout)
+
+    def _wait_on_websocket(self, url: str, *, timeout: float) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        with self._client._websocket_connect(url, open_timeout=min(10, timeout)) as socket:
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise SharpToolzError("Render wait timed out.")
+                raw = socket.recv(timeout=remaining)
+                message = json.loads(raw)
+                data = message.get("data") if message.get("type") == "render.updated" else None
+                if data and data.get("status") in TERMINAL_RENDER_STATUSES:
+                    return data
+
+    def _wait_by_polling(self, job_id: str, *, timeout: float) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        interval = 0.75
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            job = self.get(job_id)
+            if job.get("status") in TERMINAL_RENDER_STATUSES:
+                return self._finish(job)
+            interval = min(interval * 1.5, 4)
+        raise SharpToolzError("Render wait timed out.")
+
+    @staticmethod
+    def _finish(job: dict[str, Any]) -> dict[str, Any]:
+        if job.get("status") == "failed":
+            code = job.get("error_code")
+            raise SharpToolzError(f"Render failed{f': {code}' if code else '.'}", data=job)
+        return job
+
+
+class SharpToolz:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30,
+        transport: httpx.BaseTransport | None = None,
+        websocket_connect: Callable[..., Any] = websocket_connect_default,
+    ):
+        if not isinstance(api_key, str) or not api_key.startswith("stz_live_"):
+            raise TypeError("A SharpToolz server API key is required.")
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "User-Agent": "sharptoolz-python/0.2.0",
+            },
+        )
+        self._websocket_connect = websocket_connect
+        self.templates = TemplatesResource(self)
+        self.hosted_forms = HostedFormsResource(self)
+        self.documents = DocumentsResource(self)
+        self.renders = RendersResource(self)
+
+    def __enter__(self) -> "SharpToolz":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        response = self._http.request(method, path, json=json, params=params, headers=headers)
+        if response.status_code == 204:
+            return None
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        if response.is_error:
+            message = (
+                data.get("detail") if isinstance(data, dict) else None
+            ) or f"SharpToolz request failed with HTTP {response.status_code}."
+            raise SharpToolzError(message, status_code=response.status_code, data=data)
+        return data

sharptoolz-0.2.0/src/sharptoolz/py.typed

@@ -0,0 +1 @@
+

sharptoolz-0.2.0/src/sharptoolz.egg-info/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: sharptoolz
+Version: 0.2.0
+Summary: Official Python client for the SharpToolz API
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websockets<16,>=12
+
+# SharpToolz Python SDK
+
+```bash
+# Available after the first PyPI release
+pip install sharptoolz
+```
+
+```python
+import os
+from sharptoolz import SharpToolz
+
+with SharpToolz(api_key=os.environ["SHARPTOOLZ_API_KEY"]) as sharp:
+    session = sharp.hosted_forms.create(
+        template_id=template_id,
+        external_user_id=current_user_id,
+        origin="https://app.example.com",
+        mode="test",
+        preview_mode="protected",
+    )
+
+    # Return session["embed_url"] to your frontend.
+```
+
+Only browser JavaScript mounts the returned URL with `@sharp-toolz/sdk/browser`.
+Python keeps the API key on your backend and can create or edit hosted sessions,
+list documents, and wait for PNG/PDF renders over a job-scoped WebSocket.

sharptoolz-0.2.0/src/sharptoolz.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/sharptoolz/__init__.py
+src/sharptoolz/client.py
+src/sharptoolz/py.typed
+src/sharptoolz.egg-info/PKG-INFO
+src/sharptoolz.egg-info/SOURCES.txt
+src/sharptoolz.egg-info/dependency_links.txt
+src/sharptoolz.egg-info/requires.txt
+src/sharptoolz.egg-info/top_level.txt
+tests/test_client.py

sharptoolz-0.2.0/src/sharptoolz.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sharptoolz-0.2.0/src/sharptoolz.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx<1,>=0.27
+websockets<16,>=12

sharptoolz-0.2.0/src/sharptoolz.egg-info/top_level.txt

@@ -0,0 +1 @@
+sharptoolz

sharptoolz-0.2.0/tests/test_client.py

@@ -0,0 +1,111 @@
+import json
+import unittest
+
+import httpx
+
+from sharptoolz import SharpToolz
+
+
+class FakeSocket:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        return None
+
+    def recv(self, timeout=None):
+        return json.dumps({
+            "type": "render.updated",
+            "data": {"id": "job-1", "status": "completed"},
+        })
+
+
+class SharpToolzClientTests(unittest.TestCase):
+    def test_api_key_stays_in_authorization_header(self):
+        captured = {}
+
+        def handler(request):
+            captured["request"] = request
+            return httpx.Response(200, json={"results": []})
+
+        with SharpToolz(
+            api_key="stz_live_test.key",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            client.templates.list()
+
+        request = captured["request"]
+        self.assertEqual(request.headers["Authorization"], "Bearer stz_live_test.key")
+        self.assertNotIn("stz_live_test.key", str(request.url))
+
+    def test_render_wait_uses_websocket_then_fetches_final_job_once(self):
+        calls = []
+
+        def handler(request):
+            calls.append((request.method, request.url.path))
+            if request.url.path.endswith("/watch"):
+                return httpx.Response(200, json={"websocket_url": "wss://api.sharptoolz.com/ws/job"})
+            return httpx.Response(200, json={
+                "id": "job-1",
+                "status": "completed",
+                "download_url": "https://signed.example/file",
+            })
+
+        with SharpToolz(
+            api_key="stz_live_test.key",
+            transport=httpx.MockTransport(handler),
+            websocket_connect=lambda *args, **kwargs: FakeSocket(),
+        ) as client:
+            result = client.renders.wait({"id": "job-1", "status": "queued"})
+
+        self.assertEqual(result["download_url"], "https://signed.example/file")
+        self.assertEqual(calls, [
+            ("POST", "/api/v1/renders/job-1/watch"),
+            ("GET", "/api/v1/renders/job-1"),
+        ])
+
+    def test_creation_and_editing_are_hosted_session_only(self):
+        calls = []
+
+        def handler(request):
+            calls.append((request.method, request.url.path))
+            return httpx.Response(201, json={"id": "session-1"})
+
+        with SharpToolz(
+            api_key="stz_live_test.key",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            client.hosted_forms.create(
+                template_id="template-1",
+                external_user_id="user-1",
+                origin="https://app.example",
+            )
+            client.hosted_forms.edit("document-1", origin="https://app.example")
+            self.assertFalse(hasattr(client.templates, "schema"))
+            self.assertFalse(hasattr(client.documents, "create"))
+
+        self.assertEqual(calls, [
+            ("POST", "/api/v1/embed-sessions"),
+            ("POST", "/api/v1/documents/document-1/session"),
+        ])
+
+    def test_document_list_accepts_api_next_url_as_cursor(self):
+        captured = {}
+
+        def handler(request):
+            captured["query"] = request.url.query.decode()
+            return httpx.Response(200, json={"results": [], "next": None, "previous": None})
+
+        with SharpToolz(
+            api_key="stz_live_test.key",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            client.documents.list(
+                cursor="https://api.sharptoolz.com/api/v1/documents?cursor=cD0yMDI2"
+            )
+
+        self.assertEqual(captured["query"], "cursor=cD0yMDI2")
+
+
+if __name__ == "__main__":
+    unittest.main()