Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/api-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,9 @@ Use this group for password protection, permissions, signatures, and standards.
[remove_open_password][pdfrest.PdfRestClient.remove_open_password]
- Digital signatures:
[sign_pdf][pdfrest.PdfRestClient.sign_pdf]
- Text-and-data-mining reservation:
[apply_tdm_reservation][pdfrest.PdfRestClient.apply_tdm_reservation] embeds
the URL of hosted terms or a machine-readable policy without fetching it
- Archival/print conformance:
[convert_to_pdfa][pdfrest.PdfRestClient.convert_to_pdfa],
[convert_to_pdfx][pdfrest.PdfRestClient.convert_to_pdfx]
Expand All @@ -115,6 +118,10 @@ Use this group for password protection, permissions, signatures, and standards.

Use this group to improve compatibility, performance, or file size.

- Page geometry:
[set_pdf_page_boxes][pdfrest.PdfRestClient.set_pdf_page_boxes] updates the
MediaBox, CropBox, BleedBox, TrimBox, or ArtBox on selected pages

- Size and optimization:
[compress_pdf][pdfrest.PdfRestClient.compress_pdf],
[linearize_pdf][pdfrest.PdfRestClient.linearize_pdf]
Expand Down
2 changes: 2 additions & 0 deletions docs/llms-full.txt
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,8 @@ to the API guide and API reference for exact method names and options.
- Redaction preview/apply
- Passwords and permissions
- Encryption/decryption/restrictions
- URL-based text-and-data-mining reservation metadata
- Typed MediaBox, CropBox, BleedBox, TrimBox, and ArtBox updates
- Watermarking (text/image)
- Digital signing

Expand Down
4 changes: 4 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ supported interpreter matrix.

## Available Examples

- `examples/apply_tdm_reservation/apply_tdm_reservation_example.py` – embed a
hosted TDM policy URL in an uploaded PDF.
- `examples/set_pdf_page_boxes/set_pdf_page_boxes_example.py` – enlarge a PDF's
MediaBox and apply a CropBox inset with typed page selections and margins.
- `examples/add_shapes/add_shapes_to_pdf_example.py` – add a styled rectangle
and divider line to a PDF with accessibility tagging enabled.
- `examples/convert_structured_documents/convert_structured_documents_to_pdf_example.py`
Expand Down
54 changes: 54 additions & 0 deletions examples/apply_tdm_reservation/apply_tdm_reservation_example.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# /// script
# requires-python = ">=3.10"
# dependencies = ["pdfrest", "python-dotenv"]
# ///
"""Apply a text-and-data-mining reservation policy to a PDF.

This sample demonstrates how to:

1. Load ``PDFREST_API_KEY`` from the environment or a local ``.env`` file.
2. Upload the checked-in ``examples/resources/report.pdf`` input.
3. Embed a URL for hosted TDM terms or a machine-readable policy document.
4. Print the generated PDF metadata.

Replace ``POLICY_URL`` with the URL of your hosted policy in a real integration.
Set ``PDFREST_BASE_URL`` only for a self-hosted deployment. pdfRest stores the
URL without fetching or inspecting its destination. Run from the repository root with
``uv run examples/apply_tdm_reservation/apply_tdm_reservation_example.py``.
"""

from __future__ import annotations

import os
from pathlib import Path

from dotenv import load_dotenv

from pdfrest import PdfRestClient

RESOURCE_DIRECTORY = Path(__file__).resolve().parents[1] / "resources"
INPUT_PATH = RESOURCE_DIRECTORY / "report.pdf"
POLICY_URL = "https://example.com/terms/tdm-policy"


def apply_tdm_reservation() -> None:
"""Upload a PDF and add a URL-based TDM reservation policy."""
load_dotenv()
base_url = os.getenv("PDFREST_BASE_URL")

with PdfRestClient(base_url=base_url) as client:
uploaded_pdf = client.files.create_from_paths(INPUT_PATH)[0]
response = client.apply_tdm_reservation(
uploaded_pdf,
policy=POLICY_URL,
output="report-with-tdm-reservation",
)

print(f"Input ID: {response.input_id}")
print(f"Output file: {response.output_file.name}")
print(f"Output MIME type: {response.output_file.type}")
print(f"Output URL: {response.output_file.url}")


if __name__ == "__main__": # pragma: no cover - manual example
apply_tdm_reservation()
85 changes: 85 additions & 0 deletions examples/set_pdf_page_boxes/set_pdf_page_boxes_example.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# /// script
# requires-python = ">=3.10"
# dependencies = ["pdfrest", "python-dotenv"]
# ///
"""Update the MediaBox and CropBox of an uploaded PDF.

This sample demonstrates how to:

1. Load ``PDFREST_API_KEY`` from the environment or a local ``.env`` file.
2. Upload the checked-in ``examples/resources/report.pdf`` input.
3. Enlarge its MediaBox and apply a positive CropBox inset to every page.
4. Print the generated PDF metadata.

Set ``PDFREST_BASE_URL`` only for a self-hosted deployment. Run from the
repository root with
``uv run examples/set_pdf_page_boxes/set_pdf_page_boxes_example.py``.
"""

from __future__ import annotations

import os
from pathlib import Path

from dotenv import load_dotenv

from pdfrest import PdfRestClient
from pdfrest.types import (
PdfInsetPageBoxDefinition,
PdfInsetPageBoxPage,
PdfMediaBoxDefinition,
PdfMediaBoxPage,
PdfPageBoxDefinition,
)

RESOURCE_DIRECTORY = Path(__file__).resolve().parents[1] / "resources"
INPUT_PATH = RESOURCE_DIRECTORY / "report.pdf"


def set_pdf_page_boxes() -> None:
"""Upload a PDF, update two page boxes, and print the output metadata."""
load_dotenv()
base_url = os.getenv("PDFREST_BASE_URL")
boxes: list[PdfPageBoxDefinition] = [
PdfMediaBoxDefinition(
box="media",
pages=[
PdfMediaBoxPage(
range="all",
top=-18,
bottom=-18,
left=-18,
right=-18,
)
],
),
PdfInsetPageBoxDefinition(
box="crop",
pages=[
PdfInsetPageBoxPage(
range="all",
top=36,
bottom=36,
left=36,
right=36,
)
],
),
]

with PdfRestClient(base_url=base_url) as client:
uploaded_pdf = client.files.create_from_paths(INPUT_PATH)[0]
response = client.set_pdf_page_boxes(
uploaded_pdf,
boxes=boxes,
output="report-with-page-boxes",
)

print(f"Input ID: {response.input_id}")
print(f"Output file: {response.output_file.name}")
print(f"Output MIME type: {response.output_file.type}")
print(f"Output URL: {response.output_file.url}")


if __name__ == "__main__": # pragma: no cover - manual example
set_pdf_page_boxes()
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "pdfrest"
version = "1.4.0"
version = "1.5.0"
description = "Python client library for interacting with the pdfRest API"
readme = { file = "README.md", content-type = "text/markdown" }
authors = [
Expand Down
Loading
Loading