Essential Operations

This guide covers the essential operations you'll use in every PDFDancer workflow. Examples progress from simple to complex, introducing new patterns step by step.

---

Opening a PDF Document

The simplest way to open a PDF:

Python

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    # Your operations here
    pass

The with statement automatically closes the connection when done.

Opening from bytes:

from pathlib import Path

pdf_bytes = Path("document.pdf").read_bytes()
with PDFDancer.open(pdf_data=pdf_bytes) as pdf:
    pass

TypeScript

import { PDFDancer } from 'pdfdancer-client-typescript';

const pdf = await PDFDancer.open('document.pdf');
// Your operations here

Always await the open() call—PDFDancer establishes a session with the service.

Opening from bytes:

import { PDFDancer } from 'pdfdancer-client-typescript';
import { promises as fs } from 'node:fs';

const pdfBytes = await fs.readFile('document.pdf');
const pdf = await PDFDancer.open(pdfBytes);

Java

PDFDancer pdf = PDFDancer.createSession("document.pdf");
// Your operations here

---

Working with Pages

Access a specific page:

Python

page = pdf.page(1)

TypeScript

const page = pdf.page(1);

Java

Page page = pdf.page(1);

Iterate through all pages:

Python

for page in pdf.pages():
    print(f"Page ID: {page.internal_id}")

TypeScript

const allPages = await pdf.pages();
for (const [i, page] of allPages.entries()) {
  console.log(`Page ${i}: ${page.internalId}`);
}

Java

List<PageRef> allPages = pdf.getPages();
for (PageRef page : allPages) {
    System.out.println("Page ID: " + page.getInternalId());
}

Delete a page:

Python

pdf.page(3).delete()
pdf.save("output.pdf")

TypeScript

await pdf.page(3).delete();
await pdf.save('output.pdf');

Java

pdf.page(3).delete();
pdf.save("output.pdf");

---

Saving PDFs

Save to a file:

Python

pdf.save("output.pdf")

Automatically creates parent directories if needed.

TypeScript

await pdf.save('output.pdf');

Java

pdf.save("output.pdf");

Get PDF as bytes (for streaming, S3 upload, etc.):

Python

pdf_bytes = pdf.get_bytes()
s3_client.put_object(Bucket='my-bucket', Key='output.pdf', Body=pdf_bytes)

TypeScript

await pdf.save('output.pdf');

Java

byte[] pdfBytes = pdf.getFileBytes();
// For S3 upload or streaming:
// s3Client.putObject("my-bucket", "output.pdf", pdfBytes);

---

Editing Existing Content

Find all paragraphs on a page:

Python

paragraphs = pdf.page(1).select_paragraphs()

TypeScript

const paragraphs = await pdf.page(1).selectParagraphs();

Java

List<TextParagraphReference> paragraphs = pdf.page(1).selectParagraphs();

Find paragraphs by text prefix:

Python

headers = pdf.page(1).select_paragraphs_starting_with("Invoice #")

TypeScript

const headers = await pdf.page(1).selectParagraphsStartingWith('Invoice #');

Java

List<TextParagraphReference> headers = pdf.page(1).selectParagraphsStartingWith("Invoice #");

Replace text (simplest edit):

Python

if headers:
    headers[0].edit().replace("Invoice #12345").apply()

TypeScript

if (headers.length > 0) {
  await headers[0].edit().replace('Invoice #12345').apply();
}

Java

if (!headers.isEmpty()) {
    headers.get(0).edit().replace("Invoice #12345").apply();
}

Add styling while editing:

Python

from pdfdancer import Color

headers[0].edit() \
    .replace("Invoice #12345") \
    .font("Helvetica-Bold", 14) \
    .color(Color(255, 0, 0)) \
    .apply()

TypeScript

import { Color } from 'pdfdancer-client-typescript';

await headers[0].edit()
  .replace('Invoice #12345')
  .font('Helvetica-Bold', 14)
  .color(new Color(255, 0, 0))
  .apply();

Java

if (!headers.isEmpty()) {
    headers.get(0).edit()
        .replace("Invoice #12345")
        .font("Helvetica-Bold", 14)
        .color(new Color(255, 0, 0))
        .apply();
}

---

Adding New Content

Add a simple paragraph:

Python

pdf.new_paragraph() \
    .text("Hello World") \
    .at(page_number=1, x=100, y=500) \
    .add()

TypeScript

await pdf.page(1).newParagraph()
  .text('Hello World')
  .at(100, 500)
  .apply();

Java

pdf.newParagraph()
    .text("Hello World")
    .at(1, 100, 500)
    .add();

Add a paragraph with styling:

Python

from pdfdancer import Color

pdf.new_paragraph() \
    .text("Hello World") \
    .font("Helvetica", 12) \
    .color(Color(0, 0, 0)) \
    .line_spacing(1.5) \
    .at(page_number=1, x=100, y=500) \
    .add()

TypeScript

import { Color } from 'pdfdancer-client-typescript';

await pdf.page(1).newParagraph()
  .text('Hello World')
  .font('Helvetica', 12)
  .color(new Color(0, 0, 0))
  .lineSpacing(1.5)
  .at(100, 500)
  .apply();

Java

pdf.newParagraph()
    .text("Hello World")
    .font("Helvetica", 12)
    .color(new Color(0, 0, 0))
    .lineSpacing(1.5)
    .at(1, 100, 500)
    .add();

Add an image:

Python

pdf.new_image() \
    .from_file("logo.png") \
    .at(page=1, x=50, y=700) \
    .add()

TypeScript

await pdf.newImage()
  .fromFile('logo.png')
  .at(1, 50, 700)
  .add();

Java

pdf.newImage()
    .fromFile("logo.png")
    .at(1, 50, 700)
    .add();

---

Working with Forms

Find all form fields on a page:

Python

fields = pdf.page(1).select_form_fields()

TypeScript

const fields = await pdf.selectFormFields();

Java

List<FormFieldReference> fields = pdf.selectFormFields();

Find form fields by name:

Python

name_fields = pdf.page(1).select_form_fields_by_name("firstName")

TypeScript

const nameFields = await pdf.selectFieldsByName('firstName');

Java

List<FormFieldReference> nameFields = pdf.selectFormFieldsByName("firstName");

Fill a form field:

Python

if name_fields:
    name_fields[0].edit().value("John Doe").apply()

TypeScript

if (nameFields.length > 0) {
  await nameFields[0].fill('John Doe');
}

Java

if (!nameFields.isEmpty()) {
    nameFields.get(0).edit().value("John Doe").apply();
}

---

Next Steps

• Working with Text – Advanced text selection and manipulation
• Working with Fonts – Standard fonts and custom TTF fonts
• Concepts – Deeper understanding of PDFDancer's model
• Cookbook – Complete working examples