Skip to main content
Version: API v1

Working with Pages

PDFDancer provides a straightforward API for working with PDF pages. You can access individual pages, iterate through all pages, get page information, and delete pages.

Accessing Pages​

Get a Specific Page​

PDFDancer uses standard page numbering — page 1 is the first page.

from pdfdancer import PDFDancer

with PDFDancer.open("document.pdf") as pdf:
    # Get the first page
    first_page = pdf.page(1)

    # Get the second page
    second_page = pdf.page(2)

    # Get the last page (if you know the total count)
    last_page = pdf.page(5)  # For a 5-page document

Get All Pages​

with PDFDancer.open("document.pdf") as pdf:
    # Get all pages
    all_pages = pdf.pages()

    # Iterate through pages
    for i, page in enumerate(all_pages):
        print(f"Page {i}: {page.internal_id}")

Page Information​

Getting Page Properties​

with PDFDancer.open("document.pdf") as pdf:
    page = pdf.page(1)

    print(f"Page ID: {page.internal_id}")
    print(f"Position: {page.position.bounding_rect}")
    print(f"Type: {page.object_type}")

    # Page size and orientation
    print(f"Page size: {page.page_size}")  # or page.size
    print(f"Orientation: {page.orientation}")  # or page.page_orientation

    # Get dimensions from page size
    if page.page_size:
        print(f"Width: {page.page_size.width}")
        print(f"Height: {page.page_size.height}")

    # Get bounding box dimensions (alternative method)
    bbox = page.position.bounding_rect
    print(f"Width: {bbox.get('width')}")
    print(f"Height: {bbox.get('height')}")

Deleting Pages​

info

For a comprehensive guide on deletion operations across all content types, see Deleting Content.

Delete a Single Page​

with PDFDancer.open("document.pdf") as pdf:
    # Delete the third page (page number 3)
    pdf.page(3).delete()

    # Save the modified PDF
    pdf.save("output.pdf")

Delete Multiple Pages​

with PDFDancer.open("document.pdf") as pdf:
    # Delete pages 2, 3, and 5
    # Delete in reverse order to avoid page number shifting
    for page_number in reversed([2, 3, 5]):
        pdf.page(page_number).delete()

    pdf.save("output.pdf")

Moving and Reordering Pages​

You can move pages to different positions within the document to reorder them.

Move a Page to a New Position​

with PDFDancer.open("document.pdf") as pdf:
    # Move page 4 to position 1 (make it the first page)
    pdf.move_page(from_page_number=4, to_page_number=1)

    # Alternative: use the page object's move_to method
    page = pdf.page(4)
    page.move_to(1)

    # Move the last page to position 2
    last_page_number = len(pdf.pages())
    pdf.move_page(last_page_number, 2)

    pdf.save("reordered.pdf")
Page Number Shifting

When you move a page, the page numbers of other pages shift automatically. If you're moving multiple pages, consider the order of operations to avoid unexpected results.

Adding Pages to Existing Documents​

You can add new blank pages to an existing PDF document.

Add a New Blank Page​

with PDFDancer.open("document.pdf") as pdf:
    # Add a new blank page (appended to the end)
    new_page_ref = pdf.new_page().add()

    # The new page is now available
    print(f"New page added at page number: {new_page_ref.position.page_number}")

    # You can now add content to the new page
    new_page = pdf.page(new_page_ref.position.page_number)
    new_page.new_paragraph() \
        .text("This is content on the new page") \
        .at(100, 700) \
        .add()

    pdf.save("with_new_page.pdf")
info

The new_page() method adds a blank page with default dimensions. To create a new PDF with custom page sizes, see Creating New PDFs.

Working with Page Content​

Once you have a page reference, you can select and manipulate content on that page.

Selecting Content on a Page​

with PDFDancer.open("document.pdf") as pdf:
    page = pdf.page(1)

    # Select paragraphs on this page
    paragraphs = page.select_paragraphs()

    # Select images on this page
    images = page.select_images()

    # Select form fields on this page
    fields = page.select_form_fields()

    # Select text lines on this page
    lines = page.select_text_lines()

Adding Content to a Page​

from pdfdancer import PDFDancer, Color

with PDFDancer.open("document.pdf") as pdf:
    # Add a paragraph to a specific page
    pdf.new_paragraph() \
        .text("New paragraph on page 1") \
        .font("Helvetica", 12) \
        .at(page_number=1, x=100, y=500) \
        .add()

    # Or use page reference
    page = pdf.page(1)
    page.new_paragraph() \
        .text("Another paragraph") \
        .at(x=100, y=400) \
        .add()

    pdf.save("output.pdf")

Iterating Through Pages​

Process All Pages​

with PDFDancer.open("document.pdf") as pdf:
    all_pages = pdf.pages()

    for i, page in enumerate(all_pages):
        print(f"Processing page {i}")

        # Get page information
        print(f"  Internal ID: {page.internal_id}")

        # Select content on this page
        paragraphs = page.select_paragraphs()
        print(f"  Paragraphs: {len(paragraphs)}")

        images = page.select_images()
        print(f"  Images: {len(images)}")

Creating New PDFs​

Create with Standard Page Sizes​

You can create new PDF documents with standard page sizes and orientations.

from pdfdancer import PDFDancer

# Create with default A4 portrait
with PDFDancer.new() as pdf:
    pdf.new_paragraph() \
        .text("Hello World") \
        .at(page_number=1, x=72, y=720) \
        .add()
    pdf.save("output.pdf")

# Create with specific page size
with PDFDancer.new(page_size="LETTER", orientation="PORTRAIT", initial_page_count=3) as pdf:
    pdf.save("letter_size.pdf")

Supported Standard Page Sizes​

The following standard page sizes are supported:

  • A4: 595 x 842 points (default)
  • LETTER: 612 x 792 points
  • LEGAL: 612 x 1008 points
  • TABLOID: 792 x 1224 points
  • A3: 842 x 1191 points
  • A5: 420 x 595 points

Create with Custom Page Sizes​

You can also create PDFs with custom page dimensions.

from pdfdancer import PDFDancer

# Custom page size with explicit dimensions (in points)
with PDFDancer.new(
    page_size={"width": 600, "height": 800},
    orientation="PORTRAIT"
) as pdf:
    pdf.save("custom_size.pdf")

# Custom named size
with PDFDancer.new(
    page_size={"name": "CUSTOM", "width": 500, "height": 700}
) as pdf:
    pdf.save("named_custom.pdf")

Landscape Orientation​

from pdfdancer import PDFDancer

# Create A4 landscape
with PDFDancer.new(page_size="A4", orientation="LANDSCAPE") as pdf:
    pdf.save("landscape.pdf")

Next Steps​