pdfcraft-dev 1.4.0__tar.gz

pdfcraft_dev-1.4.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.venv/

pdfcraft_dev-1.4.0/LICENSE

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

pdfcraft_dev-1.4.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: pdfcraft-dev
+Version: 1.4.0
+Summary: HTML to PDF, and PDF to structured JSON, in one call. The official PDFCraft SDK.
+Project-URL: Homepage, https://pdfcraft.dev
+Project-URL: Documentation, https://pdfcraft.dev/sdk/python/
+Project-URL: Source, https://github.com/igaurav-dev/pdfcraft-python
+Project-URL: Issues, https://github.com/igaurav-dev/pdfcraft-python/issues
+Author: PDFCraft
+License: MIT License
+        
+        Copyright (c) 2026 Gaurav Singh
+        
+        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.
+License-File: LICENSE
+Keywords: chromium,extract-tables-from-pdf,headless-chrome,html-to-pdf,html-to-pdf-api,invoice,pdf,pdf-accessibility,pdf-api,pdf-extraction,pdf-generation,pdf-table-extraction,pdf-to-json,url-to-pdf
+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 :: Only
+Classifier: Topic :: Printing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# PDFCraft for Python
+
+HTML to PDF, PDF to structured JSON, and accessibility triage for a whole document estate.
+The official Python client for [PDFCraft](https://pdfcraft.dev).
+
+**Zero dependencies.** The whole client is `urllib.request` plus a retry loop, so it installs
+into a Lambda or a slim container without dragging a transitive tree behind it.
+
+```bash
+pip install pdfcraft-dev
+```
+
+Installs as `pdfcraft-dev`, imports as `pdfcraft` — the same split as
+`python-dateutil`/`dateutil`. The plain name was taken on PyPI by an unrelated
+project, and the npm package is `@pdfcraft-dev/pdf`, so the two registries at
+least agree with each other.
+
+## Render
+
+```python
+from pdfcraft import PDFCraft
+
+client = PDFCraft("sk_live_...")
+
+pdf = client.render(html="<h1>Invoice 1042</h1>")
+open("invoice.pdf", "wb").write(pdf)
+```
+
+A URL instead of HTML, with page options:
+
+```python
+pdf = client.render(
+    url="https://example.com/report",
+    options={
+        "format": "A4",
+        "margin": {"top": "20mm", "bottom": "20mm"},
+        "printBackground": True,
+        "waitFor": {"selector": "#chart-ready", "networkIdle": True},
+    },
+    filename="report.pdf",
+)
+```
+
+Need a link rather than bytes — for an email, or a file too big to hold in memory:
+
+```python
+result = client.render_to_url(html=invoice_html)
+print(result["url"], result["expires_at"], result["pages"])
+```
+
+## Extract
+
+A PDF in, its tables and labelled fields out, each with a bounding box:
+
+```python
+data = client.extract_pdf(open("statement.pdf", "rb").read())
+
+for table in data["tables"]:
+    print(table["header"], len(table["rows"]), table["confidence"])
+```
+
+Ask for specific fields by name and type:
+
+```python
+data = client.extract(
+    file=base64_pdf,
+    schema={"invoice_total": "currency", "due_date": "date", "po_number": "string"},
+)
+print(data["fields"]["invoice_total"]["value"])
+```
+
+There is **no OCR**. A scanned document has no text layer, comes back as `extraction_failed`,
+and is not billed. Nothing is guessed by a model, so the same document always produces the
+same answer — which is the point if you are reconciling numbers.
+
+Extraction is billed per page read, so `options={"pages": "1-3"}` narrows the bill as well as
+the work.
+
+## Async
+
+For documents slow enough that you would rather not hold the connection:
+
+```python
+job = client.render_async(url="https://example.com/huge", webhookUrl="https://you/hook")
+status = client.get_render(job["id"])
+```
+
+`get_extraction` polls extractions. An extraction id is not a render id — each endpoint 404s
+on the other's ids, deliberately.
+
+## Accessibility
+
+Point it at a domain and it finds every PDF, checks each against PDF/UA and WCAG 2.1 AA, and
+returns a report ranked by severity weighted by reach, with a remediation cost range.
+
+```python
+import time
+
+scan = client.scan(domain="example.gov", max_documents=500)
+while scan["status"] not in ("succeeded", "failed"):
+    time.sleep(10)
+    scan = client.get_scan(scan["id"])
+
+for doc in scan["documents"][:10]:          # already ranked — this is the fix list
+    print(doc["severity"], doc["score"], doc["url"])
+    print(f"  ${doc['cost_low_usd']:.0f}-${doc['cost_high_usd']:.0f} to remediate")
+```
+
+Exactly one source: `domain=`, `sitemap=` or `urls=`. Passing none or two raises
+`PDFCraftError` before anything is sent, because a round trip to be told you contradicted
+yourself is a round trip wasted.
+
+A scan runs for minutes — one request per second per host is a rule we do not break — so it
+returns an id immediately and you poll. `max_documents` is **clamped to your plan rather than
+refused**; `discovered` minus `checked` is what was found and not looked at, which is also the
+upgrade prompt.
+
+`report_url` on a finished scan is a share token. Anyone holding it can read the full HTML
+report, and `GET /r/<token>/pdf` renders the same report to PDF through the render API. Treat
+it as a credential, not an identifier.
+
+Each finding carries `severity` (`blocker`, `major`, `minor`), the `wcag` criteria it breaks, a
+`message` written for whoever approves the budget, and `technical_detail` for whoever does the
+work. `occurrences` is volume, not severity — one check failing 1,535 times is one thing wrong,
+fixed once, so never rank on it.
+
+```python
+from pdfcraft import A11Y_SEVERITIES, FINDING_LAYERS, SCAN_STATUSES
+```
+
+Those are generated from the same contract the API validates against, so comparing against them
+beats comparing against a string you typed.
+
+Accessibility is a **separate subscription** from rendering. An account can hold either, both or
+neither, and the free tier is a real scan of 25 documents with full findings.
+
+## Errors
+
+Every failure raises `PDFCraftError`. Branch on `.code`, which is stable; the message is
+written for a human and may be reworded.
+
+```python
+from pdfcraft import PDFCraft, PDFCraftError
+
+try:
+    pdf = client.render(html=page)
+except PDFCraftError as error:
+    if error.code == "quota_exceeded":
+        ...          # out of renders this period
+    elif error.code == "render_failed":
+        ...          # their HTML broke — billable, and worth logging
+    elif error.retryable:
+        ...          # already retried; this is after the last attempt
+    else:
+        raise
+```
+
+`error.docs_url` points at the page explaining that specific code.
+
+### What is and is not billed
+
+A render is billable if Chromium actually ran. Successes and `render_failed` count;
+`render_timeout`, `internal_error` and every 4xx that never reached the browser do not.
+
+## Retries
+
+Retries happen automatically on `429` and `5xx` and on network failures — never on a `4xx`
+other than `429`, because those fail identically however often you ask. `Retry-After` is
+honoured when the API sends it, otherwise the backoff is exponential with jitter.
+
+```python
+client = PDFCraft("sk_live_...", max_retries=0)      # off
+client = PDFCraft("sk_live_...", timeout=200.0)      # seconds
+client = PDFCraft("sk_live_...", base_url="https://gateway.internal")
+```
+
+## Typing
+
+Ships `py.typed`. Responses are plain dicts rather than dataclasses: the API's response shape
+grows, and a dict that gains a key is a non-event where a frozen dataclass is a crash. The
+option and error enumerations you might want to validate against are exported:
+
+```python
+from pdfcraft import ERROR_CODES, PAGE_FORMATS
+```
+
+Those are generated from the same definitions the API validates requests against, so they
+cannot drift from the server.
+
+## Links
+
+- Docs — https://pdfcraft.dev/docs/
+- Every error code, cause and fix — https://pdfcraft.dev/errors/
+- Extraction guides on 27 real document shapes — https://pdfcraft.dev/guides/
+- TypeScript SDK — `@pdfcraft-dev/pdf`
+- Go SDK — `github.com/igaurav-dev/pdfcraft-go`
+
+MIT licensed.

pdfcraft_dev-1.4.0/PUBLISHING.md

@@ -0,0 +1,56 @@
+# Publishing `pdfcraft` to PyPI
+
+The name **`pdfcraft` is unclaimed** (checked with `pip index versions pdfcraft`, which
+returns nothing). Note that an unrelated project called **`pdf-craft`** exists at 2.2.0 — a
+different name under PyPI's normalisation rules, but close enough that the README and the
+project description should make clear which one this is.
+
+## Once, to set up
+
+1. Create the PyPI project by uploading the first release (below). There is no way to reserve
+   a name without publishing.
+2. Prefer a **Trusted Publisher** (PyPI → the project → Publishing) over a long-lived API
+   token, so no credential sits on disk. A token works too; scope it to this project only.
+
+## Every release
+
+```bash
+# 1. The contract, first. A release whose generated constants are stale ships
+#    something that disagrees with the server.
+node ../pdfcraft/packages/contract/scripts/sync-polyglot.mjs .
+git diff --stat src/pdfcraft/_contract.py     # empty is fine; non-empty needs a version bump
+
+# 2. Bump the version in ONE place.
+$EDITOR src/pdfcraft/_version.py
+
+# 3. Test.
+PYTHONPATH=src python3 -m pytest tests/ -q
+
+# 4. Build both artefacts.
+python3 -m pip install --upgrade build twine
+python3 -m build                       # -> dist/*.whl and dist/*.tar.gz
+
+# 5. Check the rendered README before it is public; PyPI will not let you
+#    re-upload the same version to fix a broken one.
+python3 -m twine check dist/*
+
+# 6. Upload.
+python3 -m twine upload dist/*
+```
+
+## The rule that has no undo
+
+**A version number on PyPI can never be reused**, even after deleting the release. A broken
+1.3.0 means shipping 1.3.1, and 1.3.0 stays visible forever. `twine check` and a real
+`pip install` from `dist/` are the two minutes that prevent it:
+
+```bash
+python3 -m venv /tmp/verify && /tmp/verify/bin/pip install dist/*.whl
+/tmp/verify/bin/python -c "import pdfcraft; print(pdfcraft.__version__)"
+```
+
+## Keep in step
+
+The three SDKs share a version line so a reader can tell at a glance whether their Python
+client knows about the same contract as their TypeScript one. When the contract changes, sync
+and release all three, or none.

pdfcraft_dev-1.4.0/README.md

@@ -0,0 +1,198 @@
+# PDFCraft for Python
+
+HTML to PDF, PDF to structured JSON, and accessibility triage for a whole document estate.
+The official Python client for [PDFCraft](https://pdfcraft.dev).
+
+**Zero dependencies.** The whole client is `urllib.request` plus a retry loop, so it installs
+into a Lambda or a slim container without dragging a transitive tree behind it.
+
+```bash
+pip install pdfcraft-dev
+```
+
+Installs as `pdfcraft-dev`, imports as `pdfcraft` — the same split as
+`python-dateutil`/`dateutil`. The plain name was taken on PyPI by an unrelated
+project, and the npm package is `@pdfcraft-dev/pdf`, so the two registries at
+least agree with each other.
+
+## Render
+
+```python
+from pdfcraft import PDFCraft
+
+client = PDFCraft("sk_live_...")
+
+pdf = client.render(html="<h1>Invoice 1042</h1>")
+open("invoice.pdf", "wb").write(pdf)
+```
+
+A URL instead of HTML, with page options:
+
+```python
+pdf = client.render(
+    url="https://example.com/report",
+    options={
+        "format": "A4",
+        "margin": {"top": "20mm", "bottom": "20mm"},
+        "printBackground": True,
+        "waitFor": {"selector": "#chart-ready", "networkIdle": True},
+    },
+    filename="report.pdf",
+)
+```
+
+Need a link rather than bytes — for an email, or a file too big to hold in memory:
+
+```python
+result = client.render_to_url(html=invoice_html)
+print(result["url"], result["expires_at"], result["pages"])
+```
+
+## Extract
+
+A PDF in, its tables and labelled fields out, each with a bounding box:
+
+```python
+data = client.extract_pdf(open("statement.pdf", "rb").read())
+
+for table in data["tables"]:
+    print(table["header"], len(table["rows"]), table["confidence"])
+```
+
+Ask for specific fields by name and type:
+
+```python
+data = client.extract(
+    file=base64_pdf,
+    schema={"invoice_total": "currency", "due_date": "date", "po_number": "string"},
+)
+print(data["fields"]["invoice_total"]["value"])
+```
+
+There is **no OCR**. A scanned document has no text layer, comes back as `extraction_failed`,
+and is not billed. Nothing is guessed by a model, so the same document always produces the
+same answer — which is the point if you are reconciling numbers.
+
+Extraction is billed per page read, so `options={"pages": "1-3"}` narrows the bill as well as
+the work.
+
+## Async
+
+For documents slow enough that you would rather not hold the connection:
+
+```python
+job = client.render_async(url="https://example.com/huge", webhookUrl="https://you/hook")
+status = client.get_render(job["id"])
+```
+
+`get_extraction` polls extractions. An extraction id is not a render id — each endpoint 404s
+on the other's ids, deliberately.
+
+## Accessibility
+
+Point it at a domain and it finds every PDF, checks each against PDF/UA and WCAG 2.1 AA, and
+returns a report ranked by severity weighted by reach, with a remediation cost range.
+
+```python
+import time
+
+scan = client.scan(domain="example.gov", max_documents=500)
+while scan["status"] not in ("succeeded", "failed"):
+    time.sleep(10)
+    scan = client.get_scan(scan["id"])
+
+for doc in scan["documents"][:10]:          # already ranked — this is the fix list
+    print(doc["severity"], doc["score"], doc["url"])
+    print(f"  ${doc['cost_low_usd']:.0f}-${doc['cost_high_usd']:.0f} to remediate")
+```
+
+Exactly one source: `domain=`, `sitemap=` or `urls=`. Passing none or two raises
+`PDFCraftError` before anything is sent, because a round trip to be told you contradicted
+yourself is a round trip wasted.
+
+A scan runs for minutes — one request per second per host is a rule we do not break — so it
+returns an id immediately and you poll. `max_documents` is **clamped to your plan rather than
+refused**; `discovered` minus `checked` is what was found and not looked at, which is also the
+upgrade prompt.
+
+`report_url` on a finished scan is a share token. Anyone holding it can read the full HTML
+report, and `GET /r/<token>/pdf` renders the same report to PDF through the render API. Treat
+it as a credential, not an identifier.
+
+Each finding carries `severity` (`blocker`, `major`, `minor`), the `wcag` criteria it breaks, a
+`message` written for whoever approves the budget, and `technical_detail` for whoever does the
+work. `occurrences` is volume, not severity — one check failing 1,535 times is one thing wrong,
+fixed once, so never rank on it.
+
+```python
+from pdfcraft import A11Y_SEVERITIES, FINDING_LAYERS, SCAN_STATUSES
+```
+
+Those are generated from the same contract the API validates against, so comparing against them
+beats comparing against a string you typed.
+
+Accessibility is a **separate subscription** from rendering. An account can hold either, both or
+neither, and the free tier is a real scan of 25 documents with full findings.
+
+## Errors
+
+Every failure raises `PDFCraftError`. Branch on `.code`, which is stable; the message is
+written for a human and may be reworded.
+
+```python
+from pdfcraft import PDFCraft, PDFCraftError
+
+try:
+    pdf = client.render(html=page)
+except PDFCraftError as error:
+    if error.code == "quota_exceeded":
+        ...          # out of renders this period
+    elif error.code == "render_failed":
+        ...          # their HTML broke — billable, and worth logging
+    elif error.retryable:
+        ...          # already retried; this is after the last attempt
+    else:
+        raise
+```
+
+`error.docs_url` points at the page explaining that specific code.
+
+### What is and is not billed
+
+A render is billable if Chromium actually ran. Successes and `render_failed` count;
+`render_timeout`, `internal_error` and every 4xx that never reached the browser do not.
+
+## Retries
+
+Retries happen automatically on `429` and `5xx` and on network failures — never on a `4xx`
+other than `429`, because those fail identically however often you ask. `Retry-After` is
+honoured when the API sends it, otherwise the backoff is exponential with jitter.
+
+```python
+client = PDFCraft("sk_live_...", max_retries=0)      # off
+client = PDFCraft("sk_live_...", timeout=200.0)      # seconds
+client = PDFCraft("sk_live_...", base_url="https://gateway.internal")
+```
+
+## Typing
+
+Ships `py.typed`. Responses are plain dicts rather than dataclasses: the API's response shape
+grows, and a dict that gains a key is a non-event where a frozen dataclass is a crash. The
+option and error enumerations you might want to validate against are exported:
+
+```python
+from pdfcraft import ERROR_CODES, PAGE_FORMATS
+```
+
+Those are generated from the same definitions the API validates requests against, so they
+cannot drift from the server.
+
+## Links
+
+- Docs — https://pdfcraft.dev/docs/
+- Every error code, cause and fix — https://pdfcraft.dev/errors/
+- Extraction guides on 27 real document shapes — https://pdfcraft.dev/guides/
+- TypeScript SDK — `@pdfcraft-dev/pdf`
+- Go SDK — `github.com/igaurav-dev/pdfcraft-go`
+
+MIT licensed.

pdfcraft_dev-1.4.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+# Upper bound, and it is load-bearing rather than cautious.
+#
+# hatchling 1.28+ emits `Metadata-Version: 2.5`. PyPI's upload endpoint
+# validates that field against a list it knows and currently stops at 2.4, so a
+# 2.5 wheel is rejected with a bare `400 Bad Request` — after uploading to 100%,
+# with no reason in the body. `twine check` does not catch it either, because it
+# only renders the README.
+#
+# Measured, not guessed:  1.26.3 -> 2.3    1.27.0 -> 2.4    1.32.4 -> 2.5
+#
+# Raise this bound when PyPI announces 2.5 support, not before. scripts/publish.sh
+# now asserts the built metadata version, so the pin and the check have to be
+# wrong together for this to recur.
+requires = ["hatchling>=1.24,<1.28"]
+build-backend = "hatchling.build"
+
+[project]
+# The DISTRIBUTION name, which is not the import name.
+#
+# `pdfcraft` is unavailable: PyPI compares names with every non-alphanumeric
+# character stripped, so the existing `pdf-craft` (a scanned-book to Markdown
+# converter, unrelated to this) and `pdfcraft` both reduce to `pdfcraft` and the
+# upload is refused as "too similar to an existing project" — a bare 400 with no
+# reason in the body.
+#
+# The package still imports as `pdfcraft`; only `pip install` differs, the same
+# split as python-dateutil/dateutil. `pdfcraft-dev` matches the npm scope
+# (@pdfcraft-dev/pdf) so the two registries tell one story.
+name = "pdfcraft-dev"
+dynamic = ["version"]
+description = "HTML to PDF, and PDF to structured JSON, in one call. The official PDFCraft SDK."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [{ name = "PDFCraft" }]
+# Zero runtime dependencies, on purpose: the whole client is urllib.request
+# plus a retry loop. Dragging requests and its transitive tree into a
+# customer's lockfile to save forty lines is a bad trade, especially for
+# anyone installing into a Lambda or a slim container.
+dependencies = []
+keywords = [
+  "pdf", "pdf-api", "html-to-pdf", "html-to-pdf-api", "url-to-pdf",
+  "pdf-generation", "headless-chrome", "chromium", "invoice",
+  "pdf-extraction", "pdf-to-json", "extract-tables-from-pdf",
+  "pdf-table-extraction", "pdf-accessibility",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Printing",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://pdfcraft.dev"
+Documentation = "https://pdfcraft.dev/sdk/python/"
+Source = "https://github.com/igaurav-dev/pdfcraft-python"
+Issues = "https://github.com/igaurav-dev/pdfcraft-python/issues"
+
+[tool.hatch.version]
+path = "src/pdfcraft/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pdfcraft"]
+
+[tool.pytest.ini_options]
+# src-layout means the package is not importable from the repo root, so a bare
+# `pytest` fails with ModuleNotFoundError on a fresh clone. Setting pythonpath
+# here rather than expecting everyone to remember PYTHONPATH=src — including
+# scripts/publish.sh, which got this wrong once.
+pythonpath = ["src"]
+testpaths = ["tests"]