PDFCLOUD-6559 Add passwords to image conversions

docs/api-guide.md

@@ -141,6 +141,11 @@ formats.
   [convert_json_to_pdf][pdfrest.PdfRestClient.convert_json_to_pdf],
   [convert_xml_to_pdf][pdfrest.PdfRestClient.convert_xml_to_pdf],
   [convert_csv_to_pdf][pdfrest.PdfRestClient.convert_csv_to_pdf]
+
+  For PostScript or EPS conversion, upload a `.joboptions` file first and pass
+  the returned `PdfRestFile` as `job_options` to apply a custom Distiller
+  profile. See the
+  [custom job options example](https://github.com/pdfrest/pdfrest-python/blob/main/examples/convert_postscript_to_pdf/convert_postscript_with_job_options_example.py).
 - Out of PDF:
   [convert_to_word][pdfrest.PdfRestClient.convert_to_word],
   [convert_to_excel][pdfrest.PdfRestClient.convert_to_excel],
@@ -153,6 +158,11 @@ formats.
   [convert_to_jpeg][pdfrest.PdfRestClient.convert_to_jpeg],
   [convert_to_tiff][pdfrest.PdfRestClient.convert_to_tiff]
 
+All PDF-to-image helpers accept `password` for opening an encrypted input PDF.
+See the
+[password-protected PDF example](https://github.com/pdfrest/pdfrest-python/blob/main/examples/convert_to_image/convert_password_protected_pdf_to_png_example.py)
+for the complete upload, protection, and conversion workflow.
+
 ## Forms data workflows
 
 Use this group when users need to transfer form field values in/out of PDFs.

docs/llms-full.txt

@@ -153,6 +153,8 @@ to the API guide and API reference for exact method names and options.
 - Convert to Office/image/Markdown formats (for example Word, Excel,
   PowerPoint, PNG/JPEG/TIFF/GIF/BMP, Markdown)
 - Convert source assets to PDF (Office, HTML, URL, email, images, PostScript)
+- Apply an uploaded `.joboptions` Distiller profile when converting PostScript
+  or EPS with `convert_postscript_to_pdf`
 - Convert to standards formats (`PDF/A`, `PDF/X`)
 
 ### Extraction and Analysis

examples/README.md

@@ -26,6 +26,11 @@ supported interpreter matrix.
 - `examples/convert_structured_documents/convert_structured_documents_to_pdf_example.py`
   – convert Markdown, plain text, JSON, XML, and CSV documents to PDF with
   format-specific options.
+- `examples/convert_postscript_to_pdf/convert_postscript_with_job_options_example.py`
+  – convert PostScript to PDF with an uploaded custom `.joboptions` profile.
+- `examples/convert_to_image/convert_password_protected_pdf_to_png_example.py` –
+  convert a password-protected PDF into PNG images by supplying its open
+  password.
 - `examples/delete/delete_example.py` – demonstrate file deletion (sync + async
   variants).
 - `examples/extract_text/extract_pdf_text_example.py` – run `extract_pdf_text`

examples/convert_postscript_to_pdf/convert_postscript_with_job_options_example.py

@@ -0,0 +1,54 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pdfrest", "python-dotenv"]
+# ///
+"""Convert PostScript to PDF with a custom Distiller profile.
+
+This sample demonstrates how to:
+
+1. Upload the checked-in PostScript and ``.joboptions`` files.
+2. Pass the uploaded profile to ``convert_postscript_to_pdf``.
+3. Print the generated PDF's metadata and download URL.
+
+Set ``PDFREST_API_KEY``, then run from the repository root with
+``uv run examples/convert_postscript_to_pdf/convert_postscript_with_job_options_example.py``.
+All required input files are included in the repository.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from pdfrest import PdfRestClient
+
+RESOURCE_DIRECTORY = Path(__file__).resolve().parents[1] / "resources"
+POSTSCRIPT_PATH = RESOURCE_DIRECTORY / "job-options-sample.ps"
+JOB_OPTIONS_PATH = RESOURCE_DIRECTORY / "valid.joboptions"
+
+
+def convert_postscript_with_job_options() -> None:
+    """Upload a PostScript document and convert it with a custom profile."""
+    load_dotenv()
+
+    with PdfRestClient() as client:
+        postscript = client.files.create_from_paths(POSTSCRIPT_PATH)[0]
+        job_options = client.files.create_from_paths(
+            [(JOB_OPTIONS_PATH, "application/octet-stream")]
+        )[0]
+        response = client.convert_postscript_to_pdf(
+            postscript,
+            job_options=job_options,
+            output="custom-profile",
+        )
+
+    output = response.output_file
+    print(f"Created: {output.name}")
+    print(f"MIME type: {output.type}")
+    print(f"Size: {output.size} bytes")
+    print(f"Download URL: {output.url}")
+
+
+if __name__ == "__main__":  # pragma: no cover - manual example
+    convert_postscript_with_job_options()

examples/convert_to_image/convert_password_protected_pdf_to_png_example.py

@@ -0,0 +1,55 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pdfrest", "python-dotenv"]
+# ///
+"""Convert a password-protected PDF into PNG images.
+
+This sample demonstrates how to:
+
+1. Upload the bundled ``examples/resources/report.pdf`` resource.
+2. Add an open password to create a protected PDF.
+3. Supply that password to ``convert_to_png``.
+4. Print metadata for every generated PNG image.
+
+Set ``PDFREST_API_KEY``, then run from the repository root with
+``uv run examples/convert_to_image/convert_password_protected_pdf_to_png_example.py``.
+The input PDF is included in the repository, so no additional files are required.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from pdfrest import PdfRestClient
+
+RESOURCE = Path(__file__).resolve().parents[1] / "resources" / "report.pdf"
+PASSWORD = "example-password"  # noqa: S105 - Demonstration-only password.
+
+
+def convert_password_protected_pdf() -> None:
+    """Protect the sample PDF, then convert its pages with the same password."""
+    load_dotenv()
+
+    with PdfRestClient() as client:
+        uploaded = client.files.create_from_paths([RESOURCE])[0]
+        protected = client.add_open_password(
+            uploaded,
+            new_open_password=PASSWORD,
+            output="password-protected-report",
+        ).output_file
+        response = client.convert_to_png(
+            protected,
+            password=PASSWORD,
+            output_prefix="password-protected-report-page",
+        )
+
+    print(f"Created {len(response.output_files)} PNG image(s)")
+    for output in response.output_files:
+        print(f"{output.name}: {output.type}, {output.size} bytes")
+        print(f"  Download URL: {output.url}")
+
+
+if __name__ == "__main__":  # pragma: no cover - manual example
+    convert_password_protected_pdf()

examples/resources/valid.joboptions

@@ -0,0 +1,28 @@
+%!PS-Adobe-3.0
+% Minimal conservative profile for custom joboptions sanity tests.
+<<
+  /ASCII85EncodePages false
+  /AutoRotatePages /All
+  /CompatibilityLevel 1.7
+  /CompressObjects /All
+  /CompressPages true
+  /CreateJobTicket false
+  /DefaultRenderingIntent /Default
+  /ColorConversionStrategy /LeaveColorUnchanged
+  /EmbedAllFonts true
+  /EndPage -1
+  /LockDistillerParams false
+  /StartPage 1
+  /SubsetFonts true
+  /UsePrologue false
+  /DownsampleColorImages false
+  /ColorImageResolution 300
+  /DownsampleGrayImages false
+  /GrayImageResolution 300
+  /DownsampleMonoImages false
+  /MonoImageResolution 1200
+>> setdistillerparams
+<<
+  /HWResolution [600 600]
+  /PageSize [612.000 792.000]
+>> setpagedevice

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdfrest"
-version = "1.2.0"
+version = "1.3.0"
 description = "Python client library for interacting with the pdfRest API"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [