docrenders-sdk 0.1.0__tar.gz

docrenders_sdk-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# JS
+js/node_modules/
+js/dist/
+
+# Python
+python/__pycache__/
+python/*.egg-info/
+python/dist/
+python/.venv/
+
+# Go
+go/vendor/

docrenders_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: docrenders-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the DocRenders API
+Project-URL: Repository, https://github.com/JWhist/docrenders-sdks
+License: MIT
+Keywords: docrenders,markdown,pdf,sdk
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# docrenders-sdk (Python)
+
+Official Python SDK for the [DocRenders API](https://www.docrenders.com). No dependencies — uses the standard library only.
+
+## Installation
+
+```bash
+pip install docrenders-sdk
+```
+
+## Usage
+
+```python
+import os
+from docrenders import DocRendersClient, RenderRequest, RenderFileRequest, RenderOptions
+
+client = DocRendersClient(os.environ["PDFGEN_API_KEY"])
+
+# Render to raw bytes
+pdf = client.render(RenderRequest(
+    markdown="# Invoice\n\nDue: **$1,200**",
+    template="invoice",
+    options=RenderOptions(format="A4"),
+))
+
+# Render and get a signed download URL (expires in 15 min)
+result = client.render_signed_url(RenderRequest(markdown="# Report"))
+print(result.url)
+
+# Upload a file
+with open("invoice.md", "rb") as f:
+    pdf = client.render_file(RenderFileRequest(
+        filename="invoice.md",
+        content=f.read(),
+    ))
+
+# Check usage
+usage = client.usage()
+print(f"{usage.renders_used} / {usage.renders_limit} renders used")
+```
+
+## Error handling
+
+```python
+from docrenders import DocRendersClient, DocRendersError, RenderRequest
+
+try:
+    pdf = client.render(RenderRequest(markdown="# Hello"))
+except DocRendersError as e:
+    print(e.code, str(e))  # e.g. "quota_exceeded"
+```

docrenders_sdk-0.1.0/README.md

@@ -0,0 +1,51 @@
+# docrenders-sdk (Python)
+
+Official Python SDK for the [DocRenders API](https://www.docrenders.com). No dependencies — uses the standard library only.
+
+## Installation
+
+```bash
+pip install docrenders-sdk
+```
+
+## Usage
+
+```python
+import os
+from docrenders import DocRendersClient, RenderRequest, RenderFileRequest, RenderOptions
+
+client = DocRendersClient(os.environ["PDFGEN_API_KEY"])
+
+# Render to raw bytes
+pdf = client.render(RenderRequest(
+    markdown="# Invoice\n\nDue: **$1,200**",
+    template="invoice",
+    options=RenderOptions(format="A4"),
+))
+
+# Render and get a signed download URL (expires in 15 min)
+result = client.render_signed_url(RenderRequest(markdown="# Report"))
+print(result.url)
+
+# Upload a file
+with open("invoice.md", "rb") as f:
+    pdf = client.render_file(RenderFileRequest(
+        filename="invoice.md",
+        content=f.read(),
+    ))
+
+# Check usage
+usage = client.usage()
+print(f"{usage.renders_used} / {usage.renders_limit} renders used")
+```
+
+## Error handling
+
+```python
+from docrenders import DocRendersClient, DocRendersError, RenderRequest
+
+try:
+    pdf = client.render(RenderRequest(markdown="# Hello"))
+except DocRendersError as e:
+    print(e.code, str(e))  # e.g. "quota_exceeded"
+```

docrenders_sdk-0.1.0/docrenders/__init__.py

@@ -0,0 +1,15 @@
+"""DocRenders Python SDK — convert Markdown or HTML to PDF via the DocRenders API."""
+
+from .client import DocRendersClient, DocRendersError, RenderOptions, RenderRequest, RenderFileRequest, SignedURLResult, UsageResult, RateLimit, RenderUsage
+
+__all__ = [
+    "DocRendersClient",
+    "DocRendersError",
+    "RenderOptions",
+    "RenderRequest",
+    "RenderFileRequest",
+    "SignedURLResult",
+    "UsageResult",
+    "RateLimit",
+    "RenderUsage",
+]

docrenders_sdk-0.1.0/docrenders/client.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional, Tuple
+import urllib.request
+import urllib.error
+import json
+
+DEFAULT_BASE_URL = "https://www.docrenders.com"
+
+
+class DocRendersError(Exception):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass
+class RenderOptions:
+    format: Optional[str] = None          # "A4", "Letter", "Legal"
+    margin_top: Optional[str] = None
+    margin_right: Optional[str] = None
+    margin_bottom: Optional[str] = None
+    margin_left: Optional[str] = None
+    landscape: bool = False
+
+    def to_dict(self) -> dict:
+        d = {}
+        if self.format:
+            d["format"] = self.format
+        if self.margin_top:
+            d["margin_top"] = self.margin_top
+        if self.margin_right:
+            d["margin_right"] = self.margin_right
+        if self.margin_bottom:
+            d["margin_bottom"] = self.margin_bottom
+        if self.margin_left:
+            d["margin_left"] = self.margin_left
+        if self.landscape:
+            d["landscape"] = True
+        return d
+
+
+@dataclass
+class RenderRequest:
+    markdown: Optional[str] = None
+    html: Optional[str] = None
+    template: Optional[str] = None
+    options: RenderOptions = field(default_factory=RenderOptions)
+
+
+@dataclass
+class RenderFileRequest:
+    filename: str
+    content: bytes
+    options: RenderOptions = field(default_factory=RenderOptions)
+
+
+@dataclass
+class SignedURLResult:
+    url: str
+    expires_at: str
+    render_time_ms: int
+
+
+@dataclass
+class RateLimit:
+    requests_per_minute: int
+
+
+@dataclass
+class RenderUsage:
+    used: int
+    limit: int
+    period: str
+
+
+@dataclass
+class UsageResult:
+    key_prefix: str
+    plan: str
+    rate_limit: RateLimit
+    renders: RenderUsage
+
+
+class DocRendersClient:
+    """Client for the DocRenders API."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def _auth_header(self) -> dict:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _post_json(self, path: str, payload: dict) -> urllib.request.Request:
+        data = json.dumps(payload).encode()
+        req = urllib.request.Request(
+            self.base_url + path,
+            data=data,
+            headers={**self._auth_header(), "Content-Type": "application/json"},
+            method="POST",
+        )
+        return req
+
+    def _raise_for_response(self, e: urllib.error.HTTPError) -> None:
+        try:
+            body = json.loads(e.read())
+            code = body.get("error", {}).get("code", "unknown_error")
+            message = body.get("error", {}).get("message", str(e))
+        except Exception:
+            code, message = "unknown_error", str(e)
+        raise DocRendersError(code, message)
+
+    def _render_payload(self, req: RenderRequest, output: str) -> dict:
+        payload: dict = {"output": output}
+        if req.markdown:
+            payload["markdown"] = req.markdown
+        if req.html:
+            payload["html"] = req.html
+        if req.template:
+            payload["template"] = req.template
+        opts = req.options.to_dict()
+        if opts:
+            payload["options"] = opts
+        return payload
+
+    def render(self, req: RenderRequest) -> bytes:
+        """Render Markdown or HTML to PDF. Returns raw PDF bytes."""
+        http_req = self._post_json("/render", self._render_payload(req, "binary"))
+        try:
+            with urllib.request.urlopen(http_req) as resp:
+                return resp.read()
+        except urllib.error.HTTPError as e:
+            self._raise_for_response(e)
+
+    def render_signed_url(self, req: RenderRequest) -> SignedURLResult:
+        """Render Markdown or HTML to PDF. Returns a signed download URL (expires in 15 min)."""
+        http_req = self._post_json("/render", self._render_payload(req, "url"))
+        try:
+            with urllib.request.urlopen(http_req) as resp:
+                body = json.loads(resp.read())
+                return SignedURLResult(
+                    url=body["url"],
+                    expires_at=body["expires_at"],
+                    render_time_ms=body["render_time_ms"],
+                )
+        except urllib.error.HTTPError as e:
+            self._raise_for_response(e)
+
+    def render_file(self, req: RenderFileRequest) -> bytes:
+        """Upload a Markdown or HTML file and render it to PDF. Returns raw PDF bytes."""
+        data, content_type = _build_multipart(req, "binary")
+        http_req = urllib.request.Request(
+            self.base_url + "/render/file",
+            data=data,
+            headers={**self._auth_header(), "Content-Type": content_type},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(http_req) as resp:
+                return resp.read()
+        except urllib.error.HTTPError as e:
+            self._raise_for_response(e)
+
+    def render_file_signed_url(self, req: RenderFileRequest) -> SignedURLResult:
+        """Upload a Markdown or HTML file and render it to PDF. Returns a signed download URL."""
+        data, content_type = _build_multipart(req, "url")
+        http_req = urllib.request.Request(
+            self.base_url + "/render/file",
+            data=data,
+            headers={**self._auth_header(), "Content-Type": content_type},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(http_req) as resp:
+                body = json.loads(resp.read())
+                return SignedURLResult(
+                    url=body["url"],
+                    expires_at=body["expires_at"],
+                    render_time_ms=body["render_time_ms"],
+                )
+        except urllib.error.HTTPError as e:
+            self._raise_for_response(e)
+
+    def usage(self) -> UsageResult:
+        """Return current period usage for the authenticated account."""
+        http_req = urllib.request.Request(
+            self.base_url + "/usage",
+            headers=self._auth_header(),
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(http_req) as resp:
+                body = json.loads(resp.read())
+                r = body["renders"]
+                rl = body["rate_limit"]
+                return UsageResult(
+                    key_prefix=body["key_prefix"],
+                    plan=body["plan"],
+                    rate_limit=RateLimit(requests_per_minute=rl["requests_per_minute"]),
+                    renders=RenderUsage(used=r["used"], limit=r["limit"], period=r["period"]),
+                )
+        except urllib.error.HTTPError as e:
+            self._raise_for_response(e)
+
+
+def _build_multipart(req: RenderFileRequest, output: str) -> Tuple[bytes, str]:
+    boundary = b"----DocRendersBoundary7MA4YWxkTrZu0gW"
+    lines = []
+
+    def field(name: str, value: str) -> None:
+        lines.append(b"--" + boundary)
+        lines.append(f'Content-Disposition: form-data; name="{name}"'.encode())
+        lines.append(b"")
+        lines.append(value.encode())
+
+    lines.append(b"--" + boundary)
+    lines.append(
+        f'Content-Disposition: form-data; name="file"; filename="{req.filename}"'.encode()
+    )
+    lines.append(b"Content-Type: application/octet-stream")
+    lines.append(b"")
+    lines.append(req.content)
+
+    field("output", output)
+    opts = req.options
+    if opts.format:
+        field("format", opts.format)
+    if opts.margin_top:
+        field("margin_top", opts.margin_top)
+    if opts.margin_right:
+        field("margin_right", opts.margin_right)
+    if opts.margin_bottom:
+        field("margin_bottom", opts.margin_bottom)
+    if opts.margin_left:
+        field("margin_left", opts.margin_left)
+    if opts.landscape:
+        field("landscape", "true")
+
+    lines.append(b"--" + boundary + b"--")
+    body = b"\r\n".join(lines)
+    content_type = f"multipart/form-data; boundary={boundary.decode()}"
+    return body, content_type

docrenders_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "docrenders-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the DocRenders API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+keywords = ["pdf", "markdown", "docrenders", "sdk"]
+
+[project.urls]
+Repository = "https://github.com/JWhist/docrenders-sdks"
+
+[tool.hatch.build.targets.wheel]
+packages = ["docrenders"]

docrenders_sdk-0.1.0/test_client.py

@@ -0,0 +1,149 @@
+"""Tests for the DocRenders Python SDK using a mock HTTP server."""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from docrenders import DocRendersClient, DocRendersError, RenderOptions, RenderRequest, RenderFileRequest
+
+
+def start_mock_server(handler_class):
+    server = HTTPServer(("127.0.0.1", 0), handler_class)
+    thread = threading.Thread(target=server.serve_forever)
+    thread.daemon = True
+    thread.start()
+    return server
+
+
+class TestRenderBinary(unittest.TestCase):
+    def test_render_returns_bytes(self):
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                length = int(self.headers.get("Content-Length", 0))
+                body = json.loads(self.rfile.read(length))
+                assert body["output"] == "binary"
+                assert self.headers.get("Authorization") == "Bearer dcr_test_key"
+                resp = b"%PDF-1.4 fake"
+                self.send_response(200)
+                self.send_header("Content-Type", "application/pdf")
+                self.send_header("Content-Length", str(len(resp)))
+                self.end_headers()
+                self.wfile.write(resp)
+
+            def log_message(self, *args): pass
+
+        server = start_mock_server(Handler)
+        client = DocRendersClient("dcr_test_key", base_url=f"http://127.0.0.1:{server.server_address[1]}")
+        result = client.render(RenderRequest(markdown="# Hello"))
+        self.assertEqual(result, b"%PDF-1.4 fake")
+        server.shutdown()
+
+
+class TestRenderSignedURL(unittest.TestCase):
+    def test_render_signed_url(self):
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                length = int(self.headers.get("Content-Length", 0))
+                body = json.loads(self.rfile.read(length))
+                assert body["output"] == "url"
+                resp = json.dumps({
+                    "url": "https://storage.example.com/abc.pdf",
+                    "expires_at": "2026-05-31T15:00:00Z",
+                    "render_time_ms": 1200,
+                }).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(resp)))
+                self.end_headers()
+                self.wfile.write(resp)
+
+            def log_message(self, *args): pass
+
+        server = start_mock_server(Handler)
+        client = DocRendersClient("dcr_test_key", base_url=f"http://127.0.0.1:{server.server_address[1]}")
+        result = client.render_signed_url(RenderRequest(markdown="# Hello"))
+        self.assertEqual(result.url, "https://storage.example.com/abc.pdf")
+        self.assertEqual(result.render_time_ms, 1200)
+        server.shutdown()
+
+
+class TestRenderFile(unittest.TestCase):
+    def test_render_file_binary(self):
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                # Read the multipart body — just verify it arrives and output=binary
+                length = int(self.headers.get("Content-Length", 0))
+                raw = self.rfile.read(length).decode(errors="replace")
+                assert "output" in raw
+                assert "binary" in raw
+                assert "invoice.md" in raw
+                resp = b"%PDF-1.4 fake"
+                self.send_response(200)
+                self.send_header("Content-Type", "application/pdf")
+                self.send_header("Content-Length", str(len(resp)))
+                self.end_headers()
+                self.wfile.write(resp)
+
+            def log_message(self, *args): pass
+
+        server = start_mock_server(Handler)
+        client = DocRendersClient("dcr_test_key", base_url=f"http://127.0.0.1:{server.server_address[1]}")
+        result = client.render_file(RenderFileRequest(filename="invoice.md", content=b"# Invoice"))
+        self.assertEqual(result, b"%PDF-1.4 fake")
+        server.shutdown()
+
+
+class TestUsage(unittest.TestCase):
+    def test_usage(self):
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self):
+                assert self.path == "/usage"
+                resp = json.dumps({
+                    "key_prefix": "dcr_live_abcd1234",
+                    "plan": "starter",
+                    "rate_limit": {"requests_per_minute": 60},
+                    "renders": {"used": 42, "limit": 5000, "period": "2026-06"},
+                }).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(resp)))
+                self.end_headers()
+                self.wfile.write(resp)
+
+            def log_message(self, *args): pass
+
+        server = start_mock_server(Handler)
+        client = DocRendersClient("dcr_test_key", base_url=f"http://127.0.0.1:{server.server_address[1]}")
+        usage = client.usage()
+        self.assertEqual(usage.plan, "starter")
+        self.assertEqual(usage.renders.used, 42)
+        self.assertEqual(usage.renders.limit, 5000)
+        server.shutdown()
+
+
+class TestAPIError(unittest.TestCase):
+    def test_api_error_raises(self):
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):
+                resp = json.dumps({
+                    "error": {"code": "quota_exceeded", "message": "monthly render limit reached"}
+                }).encode()
+                self.send_response(429)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(resp)))
+                self.end_headers()
+                self.wfile.write(resp)
+
+            def log_message(self, *args): pass
+
+        server = start_mock_server(Handler)
+        client = DocRendersClient("dcr_test_key", base_url=f"http://127.0.0.1:{server.server_address[1]}")
+        with self.assertRaises(DocRendersError) as cm:
+            client.render(RenderRequest(markdown="# Hello"))
+        self.assertEqual(cm.exception.code, "quota_exceeded")
+        server.shutdown()
+
+
+if __name__ == "__main__":
+    unittest.main()