pdfops 0.1.0__tar.gz

pdfops-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+.venv/
+__pycache__/
+*.egg-info/

pdfops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PDFops (pdfops.dev)
+
+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.

pdfops-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: pdfops
+Version: 0.1.0
+Summary: Python client for the PDFops API: fill AcroForm PDFs, merge PDFs, inspect form fields, generate invoices. One HTTP call, no native deps, no headless browser.
+Project-URL: Homepage, https://pdfops.dev
+Project-URL: Documentation, https://pdfops.dev/docs
+Project-URL: Fill a PDF in Python, https://pdfops.dev/fill-pdf-in-python
+Project-URL: Source, https://github.com/pdfops/pdfops-python
+Project-URL: Issues, https://github.com/pdfops/pdfops-python/issues
+Author-email: PDFops <hello@pdfops.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acroform,fill-pdf,invoice,merge-pdf,pdf,pdf-api,pdf-forms,pypdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pdfops
+
+Python client for the [PDFops API](https://pdfops.dev): **fill** AcroForm PDFs, **merge** PDFs, **inspect** form fields, and **generate invoices** with one HTTP call. No native dependencies, no headless browser, nothing to install but this package.
+
+Built for the moment `pypdf` / `PyPDFForm` stop cooperating — appearance streams that never render, `NeedAppearances` flags, encrypted government blanks, checkboxes that will not tick — and for runtimes where a PDF toolchain does not fit: Lambda, Cloud Functions, Airflow tasks, notebooks.
+
+```bash
+pip install pdfops
+```
+
+Zero dependencies (standard-library `urllib`), Python 3.9+, fully typed.
+
+## Quick start
+
+```python
+from pdfops import PdfOps
+
+client = PdfOps(api_key="pdfops_live_...")   # or PdfOps() for the keyless trial (100 req/IP/month)
+
+# 1. Discover the field names — you cannot fill fields you cannot name.
+info = client.inspect("blank-w9.pdf")
+print(info["count"], "fields")
+fields = info["fillTemplate"]                  # paste-ready {name: ""} dict
+
+# 2. Fill, optionally flattening so the result is no longer editable.
+fields["Name"] = "Ada Lovelace"
+fields["Agree"] = "true"                       # checkboxes take "true" / "false"
+pdf_bytes = client.fill_form("blank-w9.pdf", fields, flatten=True)
+open("w9-filled.pdf", "wb").write(pdf_bytes)
+
+# 3. Merge, in order.
+packet = client.merge(["cover.pdf", pdf_bytes, "terms.pdf"])
+
+# 4. Invoice from data — deterministic, safe to re-render from a webhook.
+invoice = client.invoice({
+    "from": "Acme Ltd",
+    "to": {"name": "Ada Lovelace", "lines": ["12 Analytical Way", "London"]},
+    "items": [{"description": "Consulting", "quantity": 3, "unit_price": 120.0}],
+    "invoice_number": "2026-0042",
+    "date": "2026-09-05",
+    "currency": "GBP",
+})
+```
+
+PDF inputs may be `bytes`, a path (`str` / `pathlib.Path`), or a binary file object. Every PDF-producing call returns `bytes`.
+
+## API
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `inspect(pdf)` | `POST /api/inspect` | `dict` — `count`, `hasXFA`, `fields[]`, `fillTemplate` |
+| `fill_form(pdf, fields, *, flatten=False)` | `POST /api/fill-form` | filled PDF `bytes` |
+| `merge([pdf, pdf, ...])` | `POST /api/merge` | merged PDF `bytes` |
+| `invoice(request)` | `POST /api/invoice` | invoice PDF `bytes` |
+| `usage()` | `GET /api/usage` | `dict` — tier, limit, used, remaining, resets_at |
+| `signup(email)` | `POST /api/signup` | `None` — the key is emailed |
+
+Full request/response schemas: [pdfops.dev/docs](https://pdfops.dev/docs) · [OpenAPI](https://pdfops.dev/openapi.json).
+
+## Errors
+
+Every non-2xx response raises `PdfOpsError` carrying the API's stable error slug:
+
+```python
+from pdfops import PdfOps, PdfOpsError
+
+try:
+    client.fill_form("form.pdf", {"Nmae": "typo"})
+except PdfOpsError as e:
+    print(e.status, e.code, e.details)   # 422 unknown_field No field named Nmae
+```
+
+Common codes: `unknown_field`, `exceeds_max_length`, `invalid_option`, `encrypted_pdf`, `rate_limited`, `invalid_api_key`.
+
+## Configuration
+
+- `PdfOps(api_key=...)` or the `PDFOPS_API_KEY` environment variable. A free key (250 req/month, no card) is one field at [pdfops.dev/pricing](https://pdfops.dev/pricing).
+- `client_tag="..."` sets the `X-Pdfops-Client` header for anonymous usage attribution when you embed this client in another tool. Defaults to `"py"`.
+- `timeout=60.0` seconds per request; `base_url=` overrides the API origin for testing.
+- `transport=` injects a `(method, url, headers, body) -> (status, headers, body)` callable — the test suite uses this; no network needed.
+
+## Why an API instead of a library
+
+`pdf-lib` and `pypdf` are excellent when the PDF is well-behaved. PDFops exists for the other ones: it renders appearance streams server-side so every viewer shows the values, handles the encrypted-with-empty-password blanks governments publish, flattens deterministically, and is byte-for-byte reproducible — the same request yields the same file. The [compatibility registry](https://pdfops.dev/registry) records which public forms fill cleanly with which toolchain.
+
+## Links
+
+[Fill a PDF in Python](https://pdfops.dev/fill-pdf-in-python) · [Docs](https://pdfops.dev/docs) · [MCP server for AI agents](https://www.npmjs.com/package/pdfops-mcp) · [TypeScript SDK](https://www.npmjs.com/package/pdfops-sdk) · [n8n node](https://www.npmjs.com/package/n8n-nodes-pdfops) · hello@pdfops.dev
+
+MIT © PDFops

pdfops-0.1.0/README.md

@@ -0,0 +1,90 @@
+# pdfops
+
+Python client for the [PDFops API](https://pdfops.dev): **fill** AcroForm PDFs, **merge** PDFs, **inspect** form fields, and **generate invoices** with one HTTP call. No native dependencies, no headless browser, nothing to install but this package.
+
+Built for the moment `pypdf` / `PyPDFForm` stop cooperating — appearance streams that never render, `NeedAppearances` flags, encrypted government blanks, checkboxes that will not tick — and for runtimes where a PDF toolchain does not fit: Lambda, Cloud Functions, Airflow tasks, notebooks.
+
+```bash
+pip install pdfops
+```
+
+Zero dependencies (standard-library `urllib`), Python 3.9+, fully typed.
+
+## Quick start
+
+```python
+from pdfops import PdfOps
+
+client = PdfOps(api_key="pdfops_live_...")   # or PdfOps() for the keyless trial (100 req/IP/month)
+
+# 1. Discover the field names — you cannot fill fields you cannot name.
+info = client.inspect("blank-w9.pdf")
+print(info["count"], "fields")
+fields = info["fillTemplate"]                  # paste-ready {name: ""} dict
+
+# 2. Fill, optionally flattening so the result is no longer editable.
+fields["Name"] = "Ada Lovelace"
+fields["Agree"] = "true"                       # checkboxes take "true" / "false"
+pdf_bytes = client.fill_form("blank-w9.pdf", fields, flatten=True)
+open("w9-filled.pdf", "wb").write(pdf_bytes)
+
+# 3. Merge, in order.
+packet = client.merge(["cover.pdf", pdf_bytes, "terms.pdf"])
+
+# 4. Invoice from data — deterministic, safe to re-render from a webhook.
+invoice = client.invoice({
+    "from": "Acme Ltd",
+    "to": {"name": "Ada Lovelace", "lines": ["12 Analytical Way", "London"]},
+    "items": [{"description": "Consulting", "quantity": 3, "unit_price": 120.0}],
+    "invoice_number": "2026-0042",
+    "date": "2026-09-05",
+    "currency": "GBP",
+})
+```
+
+PDF inputs may be `bytes`, a path (`str` / `pathlib.Path`), or a binary file object. Every PDF-producing call returns `bytes`.
+
+## API
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `inspect(pdf)` | `POST /api/inspect` | `dict` — `count`, `hasXFA`, `fields[]`, `fillTemplate` |
+| `fill_form(pdf, fields, *, flatten=False)` | `POST /api/fill-form` | filled PDF `bytes` |
+| `merge([pdf, pdf, ...])` | `POST /api/merge` | merged PDF `bytes` |
+| `invoice(request)` | `POST /api/invoice` | invoice PDF `bytes` |
+| `usage()` | `GET /api/usage` | `dict` — tier, limit, used, remaining, resets_at |
+| `signup(email)` | `POST /api/signup` | `None` — the key is emailed |
+
+Full request/response schemas: [pdfops.dev/docs](https://pdfops.dev/docs) · [OpenAPI](https://pdfops.dev/openapi.json).
+
+## Errors
+
+Every non-2xx response raises `PdfOpsError` carrying the API's stable error slug:
+
+```python
+from pdfops import PdfOps, PdfOpsError
+
+try:
+    client.fill_form("form.pdf", {"Nmae": "typo"})
+except PdfOpsError as e:
+    print(e.status, e.code, e.details)   # 422 unknown_field No field named Nmae
+```
+
+Common codes: `unknown_field`, `exceeds_max_length`, `invalid_option`, `encrypted_pdf`, `rate_limited`, `invalid_api_key`.
+
+## Configuration
+
+- `PdfOps(api_key=...)` or the `PDFOPS_API_KEY` environment variable. A free key (250 req/month, no card) is one field at [pdfops.dev/pricing](https://pdfops.dev/pricing).
+- `client_tag="..."` sets the `X-Pdfops-Client` header for anonymous usage attribution when you embed this client in another tool. Defaults to `"py"`.
+- `timeout=60.0` seconds per request; `base_url=` overrides the API origin for testing.
+- `transport=` injects a `(method, url, headers, body) -> (status, headers, body)` callable — the test suite uses this; no network needed.
+
+## Why an API instead of a library
+
+`pdf-lib` and `pypdf` are excellent when the PDF is well-behaved. PDFops exists for the other ones: it renders appearance streams server-side so every viewer shows the values, handles the encrypted-with-empty-password blanks governments publish, flattens deterministically, and is byte-for-byte reproducible — the same request yields the same file. The [compatibility registry](https://pdfops.dev/registry) records which public forms fill cleanly with which toolchain.
+
+## Links
+
+[Fill a PDF in Python](https://pdfops.dev/fill-pdf-in-python) · [Docs](https://pdfops.dev/docs) · [MCP server for AI agents](https://www.npmjs.com/package/pdfops-mcp) · [TypeScript SDK](https://www.npmjs.com/package/pdfops-sdk) · [n8n node](https://www.npmjs.com/package/n8n-nodes-pdfops) · hello@pdfops.dev
+
+MIT © PDFops

pdfops-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pdfops"
+version = "0.1.0"
+description = "Python client for the PDFops API: fill AcroForm PDFs, merge PDFs, inspect form fields, generate invoices. One HTTP call, no native deps, no headless browser."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "PDFops", email = "hello@pdfops.dev" }]
+keywords = ["pdf", "acroform", "fill-pdf", "merge-pdf", "pdf-forms", "invoice", "pypdf", "pdf-api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "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",
+  "Topic :: Office/Business",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://pdfops.dev"
+Documentation = "https://pdfops.dev/docs"
+"Fill a PDF in Python" = "https://pdfops.dev/fill-pdf-in-python"
+Source = "https://github.com/pdfops/pdfops-python"
+Issues = "https://github.com/pdfops/pdfops-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pdfops"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pdfops", "README.md", "LICENSE", "pyproject.toml", "tests"]

pdfops-0.1.0/src/pdfops/__init__.py

@@ -0,0 +1,207 @@
+"""pdfops — Python client for the PDFops API (https://pdfops.dev).
+
+Zero dependencies: standard-library ``urllib`` only, so it runs anywhere
+Python does — Lambda, Cloud Functions, Airflow tasks, a cron, a notebook.
+Errors carry the API's structured ``{"error", "details"}`` body via
+:class:`PdfOpsError`.
+
+    from pdfops import PdfOps
+
+    client = PdfOps(api_key="pdfops_live_...")      # or PdfOps() for the keyless trial
+    fields = client.inspect("blank.pdf")["fillTemplate"]
+    fields["Name"] = "Ada Lovelace"
+    open("filled.pdf", "wb").write(client.fill_form("blank.pdf", fields, flatten=True))
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from pathlib import PurePath
+from typing import IO, Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+from urllib import error as urlerror
+from urllib import request as urlrequest
+
+__all__ = ["PdfOps", "PdfOpsError", "PdfInput", "__version__"]
+__version__ = "0.1.0"
+
+#: A PDF given as raw bytes, a filesystem path, or a binary file object.
+PdfInput = Union[bytes, bytearray, memoryview, str, "os.PathLike[str]", IO[bytes]]
+
+#: ``transport(method, url, headers, body) -> (status, headers, body)``.
+#: Injected in tests; the default speaks HTTP through urllib.
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes]], Tuple[int, Mapping[str, str], bytes]]
+
+DEFAULT_BASE_URL = "https://pdfops.dev"
+USER_AGENT = f"pdfops-python/{__version__}"
+
+
+class PdfOpsError(Exception):
+    """Structured API error. ``code`` is the API's stable ``error`` slug."""
+
+    def __init__(self, status: int, code: str, details: str) -> None:
+        super().__init__(f"{code}: {details}")
+        self.status = status
+        self.code = code
+        self.details = details
+
+
+def _read_pdf(pdf: PdfInput) -> bytes:
+    if isinstance(pdf, (bytes, bytearray, memoryview)):
+        return bytes(pdf)
+    if isinstance(pdf, (str, PurePath)) or hasattr(pdf, "__fspath__"):
+        with open(os.fspath(pdf), "rb") as fh:  # type: ignore[arg-type]
+            return fh.read()
+    if hasattr(pdf, "read"):
+        data = pdf.read()
+        if isinstance(data, str):
+            raise TypeError("PDF file objects must be opened in binary mode ('rb')")
+        return bytes(data)
+    raise TypeError(f"unsupported PDF input type: {type(pdf).__name__}")
+
+
+def _multipart(parts: Sequence[Tuple[str, Optional[str], bytes, str]]) -> Tuple[str, bytes]:
+    """Encode ``(name, filename, data, content_type)`` parts; returns (content-type, body)."""
+    boundary = f"----pdfops-{uuid.uuid4().hex}"
+    out = bytearray()
+    for name, filename, data, ctype in parts:
+        out += f"--{boundary}\r\n".encode()
+        disp = f'form-data; name="{name}"'
+        if filename is not None:
+            disp += f'; filename="{filename}"'
+        out += f"Content-Disposition: {disp}\r\n".encode()
+        out += f"Content-Type: {ctype}\r\n\r\n".encode()
+        out += data
+        out += b"\r\n"
+    out += f"--{boundary}--\r\n".encode()
+    return f"multipart/form-data; boundary={boundary}", bytes(out)
+
+
+def _urllib_transport(timeout: float) -> Transport:
+    def send(method: str, url: str, headers: Mapping[str, str], body: Optional[bytes]) -> Tuple[int, Mapping[str, str], bytes]:
+        req = urlrequest.Request(url, data=body, method=method, headers=dict(headers))
+        try:
+            with urlrequest.urlopen(req, timeout=timeout) as res:  # noqa: S310 — fixed https origin
+                return res.status, dict(res.headers.items()), res.read()
+        except urlerror.HTTPError as e:
+            return e.code, dict(e.headers.items()), e.read()
+
+    return send
+
+
+class PdfOps:
+    """Client for the PDFops API.
+
+    :param api_key: key from https://pdfops.dev/pricing (free tier: 250 req/mo).
+        Omit for keyless trial calls (100 req/IP/mo).
+    :param base_url: API origin override (testing).
+    :param client_tag: integration identifier sent as ``X-Pdfops-Client`` for
+        anonymous usage attribution. Defaults to ``"py"``; set it when embedding
+        this client inside another tool (e.g. ``"airflow"``).
+    :param timeout: per-request timeout in seconds.
+    :param transport: custom transport (tests / instrumentation).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        client_tag: Optional[str] = "py",
+        timeout: float = 60.0,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("PDFOPS_API_KEY") or None
+        self.base_url = base_url.rstrip("/")
+        self.client_tag = client_tag
+        self._send = transport or _urllib_transport(timeout)
+
+    # ── plumbing ────────────────────────────────────────────────────────────
+
+    def _headers(self, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        h: Dict[str, str] = {"User-Agent": USER_AGENT, "Accept": "application/pdf, application/json"}
+        if self.api_key:
+            h["X-API-Key"] = self.api_key
+        if self.client_tag:
+            h["X-Pdfops-Client"] = self.client_tag
+        if extra:
+            h.update(extra)
+        return h
+
+    def _request(self, method: str, path: str, headers: Mapping[str, str], body: Optional[bytes]) -> bytes:
+        status, _res_headers, data = self._send(method, f"{self.base_url}{path}", headers, body)
+        if 200 <= status < 300:
+            return data
+        code, details = f"http_{status}", (data.decode("utf-8", "replace") or f"HTTP {status}")
+        try:
+            parsed = json.loads(data.decode("utf-8"))
+            if isinstance(parsed, dict):
+                code = str(parsed.get("error") or code)
+                details = str(parsed.get("details") or details)
+        except ValueError:
+            pass  # non-JSON error body — keep the status fallback
+        raise PdfOpsError(status, code, details)
+
+    def _post_pdf(self, path: str, parts: Sequence[Tuple[str, Optional[str], bytes, str]]) -> bytes:
+        ctype, body = _multipart(parts)
+        return self._request("POST", path, self._headers({"Content-Type": ctype}), body)
+
+    # ── API ─────────────────────────────────────────────────────────────────
+
+    def inspect(self, pdf: PdfInput) -> Dict[str, Any]:
+        """List a PDF's AcroForm fields plus a paste-ready ``fillTemplate``.
+
+        Returns ``{"count", "hasXFA", "fields": [...], "fillTemplate": {...}}``.
+        A PDF with no form returns ``count == 0`` — not an error.
+        """
+        data = self._post_pdf("/api/inspect", [("pdf", "input.pdf", _read_pdf(pdf), "application/pdf")])
+        return json.loads(data.decode("utf-8"))
+
+    def fill_form(self, pdf: PdfInput, fields: Mapping[str, str], *, flatten: bool = False) -> bytes:
+        """Fill AcroForm fields; returns the filled PDF bytes.
+
+        Field names must exist in the PDF — use :meth:`inspect` to discover
+        them. Checkbox values are the strings ``"true"``/``"false"``; choice
+        fields take one of their options. ``flatten=True`` bakes values into
+        the page content and drops the form so fields are no longer editable.
+        """
+        parts: List[Tuple[str, Optional[str], bytes, str]] = [
+            ("pdf", "input.pdf", _read_pdf(pdf), "application/pdf"),
+            ("fields", None, json.dumps(dict(fields)).encode("utf-8"), "application/json"),
+        ]
+        if flatten:
+            parts.append(("flatten", None, b"true", "text/plain"))
+        return self._post_pdf("/api/fill-form", parts)
+
+    def merge(self, pdfs: Sequence[PdfInput]) -> bytes:
+        """Merge two or more PDFs, in order; returns the combined PDF bytes."""
+        if len(pdfs) < 2:
+            raise PdfOpsError(400, "too_few_pdfs", "merge needs at least 2 PDFs")
+        parts = [("pdf", f"part-{i}.pdf", _read_pdf(p), "application/pdf") for i, p in enumerate(pdfs)]
+        return self._post_pdf("/api/merge", parts)
+
+    def invoice(self, request: Mapping[str, Any]) -> bytes:
+        """Generate a complete invoice PDF from structured data.
+
+        Deterministic: the same request produces byte-identical output, so it
+        is safe to re-render from webhooks and retries. Keys: ``from``, ``to``
+        (string or ``{"name", "lines"}``), ``items`` (``description``,
+        ``unit_price``, optional ``quantity``), optional ``invoice_number``,
+        ``date``, ``due``, ``currency``, ``tax_rate``, ``notes``.
+        """
+        body = json.dumps(dict(request)).encode("utf-8")
+        return self._request("POST", "/api/invoice", self._headers({"Content-Type": "application/json"}), body)
+
+    def usage(self) -> Dict[str, Any]:
+        """Quota state for the configured key: tier, limit, used, remaining, period, resets_at."""
+        if not self.api_key:
+            raise PdfOpsError(401, "missing_api_key", "usage() requires an api_key")
+        data = self._request("GET", "/api/usage", self._headers(), None)
+        return json.loads(data.decode("utf-8"))
+
+    def signup(self, email: str) -> None:
+        """Request a free API key (250 req/mo). The key is emailed, never returned."""
+        body = json.dumps({"email": email}).encode("utf-8")
+        headers = {"User-Agent": USER_AGENT, "Content-Type": "application/json"}
+        self._request("POST", "/api/signup", headers, body)

pdfops-0.1.0/tests/test_client.py

@@ -0,0 +1,177 @@
+"""Offline tests for the pdfops client — a fake transport records every request.
+
+Run:  python3 -m unittest discover -s python/tests -t python
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import re
+import sys
+import tempfile
+import unittest
+from typing import List, Optional, Tuple
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from pdfops import PdfOps, PdfOpsError, __version__  # noqa: E402
+
+PDF = b"%PDF-1.4\n%fake\n"
+
+
+class FakeTransport:
+    def __init__(self, status: int = 200, body: bytes = b"", headers: Optional[dict] = None) -> None:
+        self.status, self.body, self.headers = status, body, headers or {}
+        self.calls: List[Tuple[str, str, dict, Optional[bytes]]] = []
+
+    def __call__(self, method, url, headers, body):
+        self.calls.append((method, url, dict(headers), body))
+        return self.status, self.headers, self.body
+
+
+def parts_of(body: bytes, content_type: str):
+    """Decode a multipart body into [(name, filename, ctype, data)]."""
+    boundary = re.search(r"boundary=(\S+)", content_type).group(1).encode()
+    out = []
+    for chunk in body.split(b"--" + boundary)[1:]:
+        if chunk.startswith(b"--"):
+            break
+        head, data = chunk.lstrip(b"\r\n").split(b"\r\n\r\n", 1)
+        name = re.search(rb'name="([^"]+)"', head).group(1).decode()
+        fn = re.search(rb'filename="([^"]+)"', head)
+        ctype = re.search(rb"Content-Type: (\S+)", head).group(1).decode()
+        out.append((name, fn.group(1).decode() if fn else None, ctype, data[:-2]))
+    return out
+
+
+class HeadersAndInputs(unittest.TestCase):
+    def test_key_and_client_tag_headers(self):
+        t = FakeTransport(body=PDF)
+        PdfOps("pdfops_live_x", transport=t).fill_form(PDF, {"a": "b"})
+        _, url, headers, _ = t.calls[0]
+        self.assertEqual(url, "https://pdfops.dev/api/fill-form")
+        self.assertEqual(headers["X-API-Key"], "pdfops_live_x")
+        self.assertEqual(headers["X-Pdfops-Client"], "py")
+        self.assertEqual(headers["User-Agent"], f"pdfops-python/{__version__}")
+
+    def test_keyless_and_custom_tag_and_base_url(self):
+        t = FakeTransport(body=b"{}")
+        PdfOps(base_url="http://localhost:3000/", client_tag="airflow", transport=t).inspect(PDF)
+        _, url, headers, _ = t.calls[0]
+        self.assertEqual(url, "http://localhost:3000/api/inspect")
+        self.assertNotIn("X-API-Key", headers)
+        self.assertEqual(headers["X-Pdfops-Client"], "airflow")
+
+    def test_env_key_is_picked_up(self):
+        os.environ["PDFOPS_API_KEY"] = "pdfops_live_env"
+        try:
+            t = FakeTransport(body=b"{}")
+            PdfOps(transport=t).inspect(PDF)
+            self.assertEqual(t.calls[0][2]["X-API-Key"], "pdfops_live_env")
+        finally:
+            del os.environ["PDFOPS_API_KEY"]
+
+    def test_pdf_input_forms(self):
+        t = FakeTransport(body=b"{}")
+        c = PdfOps(transport=t)
+        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as fh:
+            fh.write(PDF)
+            path = fh.name
+        try:
+            c.inspect(PDF)                    # bytes
+            c.inspect(bytearray(PDF))         # bytearray
+            c.inspect(path)                   # str path
+            from pathlib import Path
+            c.inspect(Path(path))             # PathLike
+            c.inspect(io.BytesIO(PDF))        # binary file object
+        finally:
+            os.unlink(path)
+        for _, _, headers, body in t.calls:
+            (name, fn, ctype, data), = parts_of(body, headers["Content-Type"])
+            self.assertEqual((name, fn, ctype, data), ("pdf", "input.pdf", "application/pdf", PDF))
+
+    def test_text_mode_file_rejected(self):
+        with self.assertRaises(TypeError):
+            PdfOps(transport=FakeTransport()).inspect(io.StringIO("%PDF"))
+
+
+class Endpoints(unittest.TestCase):
+    def test_fill_form_parts_and_flatten(self):
+        t = FakeTransport(body=PDF)
+        out = PdfOps(transport=t).fill_form(PDF, {"Name": "Ada", "Agree": "true"}, flatten=True)
+        self.assertEqual(out, PDF)
+        _, _, headers, body = t.calls[0]
+        parts = parts_of(body, headers["Content-Type"])
+        self.assertEqual([p[0] for p in parts], ["pdf", "fields", "flatten"])
+        self.assertEqual(json.loads(parts[1][3]), {"Name": "Ada", "Agree": "true"})
+        self.assertEqual(parts[2][3], b"true")
+
+    def test_fill_form_without_flatten_has_no_flatten_part(self):
+        t = FakeTransport(body=PDF)
+        PdfOps(transport=t).fill_form(PDF, {"a": "b"})
+        _, _, headers, body = t.calls[0]
+        self.assertEqual([p[0] for p in parts_of(body, headers["Content-Type"])], ["pdf", "fields"])
+
+    def test_merge_order_and_minimum(self):
+        t = FakeTransport(body=PDF)
+        PdfOps(transport=t).merge([PDF, b"%PDF-2", b"%PDF-3"])
+        _, url, headers, body = t.calls[0]
+        self.assertTrue(url.endswith("/api/merge"))
+        self.assertEqual([p[1] for p in parts_of(body, headers["Content-Type"])], ["part-0.pdf", "part-1.pdf", "part-2.pdf"])
+        with self.assertRaises(PdfOpsError) as cm:
+            PdfOps(transport=t).merge([PDF])
+        self.assertEqual(cm.exception.code, "too_few_pdfs")
+        self.assertEqual(len(t.calls), 1, "no request is sent for an invalid merge")
+
+    def test_invoice_is_json(self):
+        t = FakeTransport(body=PDF)
+        req = {"from": "PDFops", "to": "Ada", "items": [{"description": "x", "unit_price": 1}], "invoice_number": "1"}
+        self.assertEqual(PdfOps(transport=t).invoice(req), PDF)
+        method, url, headers, body = t.calls[0]
+        self.assertEqual((method, url), ("POST", "https://pdfops.dev/api/invoice"))
+        self.assertEqual(headers["Content-Type"], "application/json")
+        self.assertEqual(json.loads(body), req)
+
+    def test_usage_requires_key_and_parses_json(self):
+        with self.assertRaises(PdfOpsError) as cm:
+            PdfOps(transport=FakeTransport()).usage()
+        self.assertEqual(cm.exception.code, "missing_api_key")
+        t = FakeTransport(body=json.dumps({"tier": "free", "limit": 250, "used": 3, "remaining": 247}).encode())
+        u = PdfOps("k", transport=t).usage()
+        self.assertEqual((t.calls[0][0], u["remaining"]), ("GET", 247))
+
+    def test_signup_sends_email_without_key_headers(self):
+        t = FakeTransport(status=204)
+        PdfOps("k", transport=t).signup("dev@example.com")
+        method, url, headers, body = t.calls[0]
+        self.assertEqual((method, url), ("POST", "https://pdfops.dev/api/signup"))
+        self.assertNotIn("X-API-Key", headers)
+        self.assertEqual(json.loads(body), {"email": "dev@example.com"})
+
+
+class Errors(unittest.TestCase):
+    def test_structured_api_error(self):
+        t = FakeTransport(status=422, body=json.dumps({"error": "unknown_field", "details": "No field named Nmae"}).encode())
+        with self.assertRaises(PdfOpsError) as cm:
+            PdfOps(transport=t).fill_form(PDF, {"Nmae": "x"})
+        e = cm.exception
+        self.assertEqual((e.status, e.code, e.details), (422, "unknown_field", "No field named Nmae"))
+        self.assertEqual(str(e), "unknown_field: No field named Nmae")
+
+    def test_non_json_error_falls_back_to_status(self):
+        t = FakeTransport(status=502, body=b"Bad Gateway")
+        with self.assertRaises(PdfOpsError) as cm:
+            PdfOps(transport=t).inspect(PDF)
+        self.assertEqual((cm.exception.status, cm.exception.code, cm.exception.details), (502, "http_502", "Bad Gateway"))
+
+    def test_rate_limit_error_code_surfaces(self):
+        t = FakeTransport(status=429, body=json.dumps({"error": "rate_limited", "details": "100/IP/mo exceeded"}).encode())
+        with self.assertRaises(PdfOpsError) as cm:
+            PdfOps(transport=t).merge([PDF, PDF])
+        self.assertEqual(cm.exception.code, "rate_limited")
+
+
+if __name__ == "__main__":
+    unittest.main()