pdftagger 0.1.1__tar.gz → 0.2.0__tar.gz

{pdftagger-0.1.1 → pdftagger-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pdftagger
-Version: 0.1.1
+Version: 0.2.0
 Summary: Official Python SDK for the PDF Tagger API — auto-tag PDFs for PDF/UA accessibility.
 Project-URL: Homepage, https://pdf-tagger.com
 Project-URL: Documentation, https://pdf-tagger.com/api/reference
@@ -56,6 +56,7 @@ Description-Content-Type: text/markdown
 Official Python SDK for the [PDF Tagger](https://pdf-tagger.com) API. Upload a PDF,
 submit a tagging job, and download a **PDF/UA-tagged, accessible** PDF — with correct
 reading order, headings, tables, and alt text. Tag one PDF, or up to 100 at once as a batch.
+Each job comes with a PDF/UA-1 report: the result for every accessibility requirement in PDF/UA-1.
 
 ```bash
 pip install pdftagger
@@ -99,6 +100,31 @@ job = client.tag_pdf("report.pdf", wait=False)   # returns immediately
 job = client.wait_for_job(job)                    # ...poll later
 ```
 
+## The PDF/UA-1 report
+
+Every completed job has a report: the result and evidence for every accessibility requirement in
+PDF/UA-1, and a report PDF you can keep.
+
+```python
+report = client.get_job_report(job)
+print(report.summary)   # {'handled': 169, 'failed': 0, 'needs_review': 0, 'for_information': 0, 'not_applicable': 51}
+
+for req in report.failed:   # also report.needs_review
+    print(req.reference, req.name, req.evidence)
+
+client.download_report(job, "report.accessibility-report.pdf")
+```
+
+Each `Requirement` has a `result`:
+
+| `result` | Meaning |
+|---|---|
+| `handled` | It passed, or PDF Tagger met or fixed it. |
+| `failed` | A validator found it failing in the file. |
+| `needs_review` | A person must confirm it. |
+| `for_information` | A limit from the source file that you cannot act on. |
+| `not_applicable` | The document has no content of this kind. |
+
 ## Many PDFs at once: batches
 
 Tag up to 100 PDFs as one batch. `tag_pdfs()` uploads every file, submits them in one
@@ -169,6 +195,7 @@ client.upload_file(upload, "report.pdf")
 job = client.submit_job(key=upload.key, ocr=True)
 job = client.get_job(job.id)               # processing / completed / failed
 result = client.get_job_result(job.id)     # short-lived download URL
+report = client.get_job_report(job.id)     # the PDF/UA-1 report
 ```
 
 ## Errors
@@ -180,8 +207,8 @@ All errors derive from `PdfTaggerError`.
 | `AuthenticationError` | 401 — key missing, invalid, or revoked |
 | `BadRequestError` | 400 — invalid request (for a batch, `.errors` lists each bad file) |
 | `InsufficientCreditsError` | 402 — not enough credits (a batch charges nothing) |
-| `NotFoundError` | 404 — no such job/resource for this account |
-| `ConflictError` | 409 — idempotency conflict, or result not ready |
+| `NotFoundError` | 404 — no such job/resource for this account, or the job has no report |
+| `ConflictError` | 409 — idempotency conflict, or result or report not ready |
 | `RateLimitError` | 429 — rate limited (`.retry_after` seconds) |
 | `JobFailed` | the job finished with a `failed` status (credits are refunded) |
 | `JobTimeout` | the job, or the batch, did not finish within the poll timeout |

{pdftagger-0.1.1 → pdftagger-0.2.0}/README.md

@@ -3,6 +3,7 @@
 Official Python SDK for the [PDF Tagger](https://pdf-tagger.com) API. Upload a PDF,
 submit a tagging job, and download a **PDF/UA-tagged, accessible** PDF — with correct
 reading order, headings, tables, and alt text. Tag one PDF, or up to 100 at once as a batch.
+Each job comes with a PDF/UA-1 report: the result for every accessibility requirement in PDF/UA-1.
 
 ```bash
 pip install pdftagger
@@ -46,6 +47,31 @@ job = client.tag_pdf("report.pdf", wait=False)   # returns immediately
 job = client.wait_for_job(job)                    # ...poll later
 ```
 
+## The PDF/UA-1 report
+
+Every completed job has a report: the result and evidence for every accessibility requirement in
+PDF/UA-1, and a report PDF you can keep.
+
+```python
+report = client.get_job_report(job)
+print(report.summary)   # {'handled': 169, 'failed': 0, 'needs_review': 0, 'for_information': 0, 'not_applicable': 51}
+
+for req in report.failed:   # also report.needs_review
+    print(req.reference, req.name, req.evidence)
+
+client.download_report(job, "report.accessibility-report.pdf")
+```
+
+Each `Requirement` has a `result`:
+
+| `result` | Meaning |
+|---|---|
+| `handled` | It passed, or PDF Tagger met or fixed it. |
+| `failed` | A validator found it failing in the file. |
+| `needs_review` | A person must confirm it. |
+| `for_information` | A limit from the source file that you cannot act on. |
+| `not_applicable` | The document has no content of this kind. |
+
 ## Many PDFs at once: batches
 
 Tag up to 100 PDFs as one batch. `tag_pdfs()` uploads every file, submits them in one
@@ -116,6 +142,7 @@ client.upload_file(upload, "report.pdf")
 job = client.submit_job(key=upload.key, ocr=True)
 job = client.get_job(job.id)               # processing / completed / failed
 result = client.get_job_result(job.id)     # short-lived download URL
+report = client.get_job_report(job.id)     # the PDF/UA-1 report
 ```
 
 ## Errors
@@ -127,8 +154,8 @@ All errors derive from `PdfTaggerError`.
 | `AuthenticationError` | 401 — key missing, invalid, or revoked |
 | `BadRequestError` | 400 — invalid request (for a batch, `.errors` lists each bad file) |
 | `InsufficientCreditsError` | 402 — not enough credits (a batch charges nothing) |
-| `NotFoundError` | 404 — no such job/resource for this account |
-| `ConflictError` | 409 — idempotency conflict, or result not ready |
+| `NotFoundError` | 404 — no such job/resource for this account, or the job has no report |
+| `ConflictError` | 409 — idempotency conflict, or result or report not ready |
 | `RateLimitError` | 429 — rate limited (`.retry_after` seconds) |
 | `JobFailed` | the job finished with a `failed` status (credits are refunded) |
 | `JobTimeout` | the job, or the batch, did not finish within the poll timeout |

pdftagger-0.2.0/RELEASING.md

@@ -0,0 +1,29 @@
+# Releasing
+
+PyPI publishing is automatic: publishing a GitHub release runs `.github/workflows/publish.yml`,
+which builds the package and uploads it with PyPI trusted publishing (no token).
+
+1. Set the new version in `src/pdftagger/_version.py` and merge it to `main`.
+2. On GitHub, create a release with the tag `v<version>` (for example `v0.1.0`) and publish it.
+3. Check the "Publish to PyPI" workflow run, then `pip install pdftagger==<version>`.
+
+One-time setup (already done once it has been published):
+
+- On PyPI, add a trusted publisher for the project `pdftagger`: owner `PDF-Tagger`,
+  repository `pdftagger-python`, workflow `publish.yml`, environment `pypi`. Before the first
+  release this is a "pending publisher" (Account settings → Publishing).
+- On GitHub, create the environment `pypi` (Settings → Environments).
+
+## The PyPI provenance banner
+
+PyPI compares each release with the latest earlier release that has attestations and was made within 14 days. It
+shows a "Change of provenance" warning when the publishing repository or workflow changed. 0.1.1 has that warning
+because 0.1.0 came from `rachel-ackeret/pdftagger-python` and 0.1.1 from `PDF-Tagger/pdftagger-python`. Every later
+release from this repository and `publish.yml` has no warning, so the project page is clean from 0.2.0 on. Keep the
+repository and the workflow file name the same; a change brings the warning back for one release. Do not delete
+0.1.0 to clear 0.1.1's own page: deletion is permanent and burns the version number.
+
+## Releases that need an API change
+
+Publish a release only after every API endpoint it calls is live on api.pdf-tagger.com. 0.2.0 calls
+`GET /v1/jobs/{id}/report`.

{pdftagger-0.1.1 → pdftagger-0.2.0}/examples/quickstart.py

@@ -1,4 +1,4 @@
-"""Tag a PDF and save the accessible result.
+"""Tag a PDF, save the accessible result and print its PDF/UA-1 report.
 
 Usage:
     export PDFTAGGER_API_KEY=sk_live_...
@@ -38,6 +38,11 @@ def main() -> int:
 
         client.download_result(job, out)
         print(f"Tagged PDF saved to {out} (job {job.id}, {job.credits_used} credits)")
+
+        report = client.get_job_report(job)
+        print(f"{report.standard}: {report.summary}")
+        for req in report.failed + report.needs_review:
+            print(f"  {req.result}: {req.reference} {req.name}")
     return 0
 
 

{pdftagger-0.1.1 → pdftagger-0.2.0}/src/pdftagger/__init__.py

@@ -6,6 +6,8 @@ Auto-tag PDFs for PDF/UA accessibility from your own code:
     >>> client = PdfTaggerClient(api_key="sk_live_...")
     >>> job = client.tag_pdf("report.pdf", ocr=True)
     >>> client.download_result(job, "report.tagged.pdf")
+    >>> report = client.get_job_report(job)  # the PDF/UA-1 report
+    >>> report.summary
 
 Many PDFs at once, as one batch:
 
@@ -30,7 +32,19 @@ from .exceptions import (
     RateLimitError,
     WebhookVerificationError,
 )
-from .models import Account, Batch, BatchCounts, BatchEvent, BatchItem, Job, JobResult, Upload, WebhookEvent
+from .models import (
+    Account,
+    Batch,
+    BatchCounts,
+    BatchEvent,
+    BatchItem,
+    Job,
+    JobReport,
+    JobResult,
+    Requirement,
+    Upload,
+    WebhookEvent,
+)
 from .webhooks import SIGNATURE_HEADER, verify_signature
 
 __all__ = [
@@ -42,6 +56,8 @@ __all__ = [
     "Upload",
     "Job",
     "JobResult",
+    "JobReport",
+    "Requirement",
     "Batch",
     "BatchItem",
     "BatchCounts",

pdftagger-0.2.0/src/pdftagger/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{pdftagger-0.1.1 → pdftagger-0.2.0}/src/pdftagger/client.py

@@ -20,7 +20,7 @@ from .exceptions import (
     NotFoundError,
     RateLimitError,
 )
-from .models import Account, Batch, BatchItem, BatchItemInput, Job, JobResult, Upload
+from .models import Account, Batch, BatchItem, BatchItemInput, Job, JobReport, JobResult, Upload
 
 DEFAULT_BASE_URL = "https://api.pdf-tagger.com"
 
@@ -236,6 +236,14 @@ class PdfTaggerClient:
         """Get a short-lived download URL for a completed job."""
         return JobResult.from_dict(self._request("GET", f"/v1/jobs/{_job_id(job)}/result"))
 
+    def get_job_report(self, job: Union[str, Job]) -> JobReport:
+        """Get a completed job's PDF/UA-1 report: the result for every accessibility requirement.
+
+        Raises :class:`ConflictError` while the job is not completed, and :class:`NotFoundError`
+        when the job has no PDF/UA-1 report.
+        """
+        return JobReport.from_dict(self._request("GET", f"/v1/jobs/{_job_id(job)}/report"))
+
     def submit_batch(
         self,
         items: Sequence[BatchItemInput],
@@ -440,9 +448,26 @@ class PdfTaggerClient:
         Returns the written :class:`~pathlib.Path` when ``dest`` is given, otherwise the
         PDF bytes.
         """
-        result = self.get_job_result(job)
+        return self._download(self.get_job_result(job).result_url, dest)
+
+    def download_report(
+        self,
+        job: Union[str, Job],
+        dest: Optional[Union[str, Path]] = None,
+    ) -> Union[bytes, Path]:
+        """Download a completed job's PDF/UA-1 report PDF.
+
+        Returns the written :class:`~pathlib.Path` when ``dest`` is given, otherwise the
+        PDF bytes. Raises :class:`NotFoundError` when the report PDF is no longer stored.
+        """
+        report = self.get_job_report(job)
+        if not report.report_pdf_url:
+            raise NotFoundError("The report PDF for this job is no longer stored.", status_code=404)
+        return self._download(report.report_pdf_url, dest)
+
+    def _download(self, url: str, dest: Optional[Union[str, Path]]) -> Union[bytes, Path]:
         try:
-            response = self._http.get(result.result_url)
+            response = self._http.get(url)
         except httpx.HTTPError as exc:
             raise APIError(f"Download failed: {exc}") from exc
         if not response.is_success:

{pdftagger-0.1.1 → pdftagger-0.2.0}/src/pdftagger/models.py

@@ -125,6 +125,88 @@ class JobResult:
         )
 
 
+@dataclass
+class Requirement:
+    """One accessibility requirement in a job's PDF/UA-1 report, with its result on this document.
+
+    ``result`` is one of ``handled`` (passed, or PDF Tagger met or fixed it), ``failed`` (a validator
+    found it failing in the file), ``needs_review`` (a person must confirm it), ``for_information`` (a
+    limit from the source file you cannot act on) or ``not_applicable`` (the document has no content of
+    this kind). ``evidence`` is the sentence behind the result, or ``None`` for a plain pass.
+    """
+
+    id: str
+    reference: str
+    name: str
+    result: str
+    level: Optional[str] = None
+    section_id: Optional[str] = None
+    section_title: Optional[str] = None
+    category: Optional[str] = None
+    evidence: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Requirement":
+        section = data.get("section") or {}
+        return cls(
+            id=data["id"],
+            reference=data.get("reference", ""),
+            name=data.get("name", ""),
+            result=data["result"],
+            level=data.get("level"),
+            section_id=section.get("id"),
+            section_title=section.get("title"),
+            category=data.get("category"),
+            evidence=data.get("evidence"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class JobReport:
+    """A job's PDF/UA-1 report (``GET /v1/jobs/{id}/report``).
+
+    ``requirements`` lists every accessibility requirement in PDF/UA-1, in the standard's order.
+    ``summary`` counts the requirements by result. ``report_pdf_url`` is a short-lived link to the
+    report PDF, or ``None`` when the file is no longer stored.
+    """
+
+    job_id: str
+    standard: str
+    total_requirements: int
+    summary: Dict[str, int]
+    requirements: List[Requirement]
+    report_pdf_url: Optional[str] = None
+    expires_in: Optional[int] = None
+    request_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "JobReport":
+        return cls(
+            job_id=data["job_id"],
+            standard=data.get("standard", ""),
+            total_requirements=int(data.get("total_requirements", 0)),
+            summary=dict(data.get("summary") or {}),
+            requirements=[Requirement.from_dict(r) for r in data.get("requirements") or []],
+            report_pdf_url=data.get("report_pdf_url"),
+            expires_in=data.get("expires_in"),
+            request_id=data.get("request_id"),
+            raw=dict(data),
+        )
+
+    @property
+    def failed(self) -> List[Requirement]:
+        """The requirements a validator found failing in the file."""
+        return [r for r in self.requirements if r.result == "failed"]
+
+    @property
+    def needs_review(self) -> List[Requirement]:
+        """The requirements a person must confirm."""
+        return [r for r in self.requirements if r.result == "needs_review"]
+
+
 @dataclass
 class BatchItem:
     """One file in a batch for :meth:`~pdftagger.client.PdfTaggerClient.submit_batch`.