pdfops 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+pdfops/__init__.py,sha256=AddfR4yziYcEel-w-t-sXbJVGMAR06dpvWuNjhYzTYY,9592
+pdfops/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdfops-0.1.0.dist-info/METADATA,sha256=-8osmGUC78NtU9b8Kbmef1aaR-b0hseXI8xlyYMOTgg,5859
+pdfops-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pdfops-0.1.0.dist-info/licenses/LICENSE,sha256=XGtTUurHEstLRQPCVmw_mBkQsMx8lvABFO0l6aNHWXM,1076
+pdfops-0.1.0.dist-info/RECORD,,

pdfops-0.1.0.dist-info/WHEEL

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

pdfops-0.1.0.dist-info/licenses/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.