Feature: Extract Page Range Method

[jdrhyne]

Feature: Extract Page Range Method

Summary

Implement extract_pages() as a simpler alternative to split_pdf() for extracting a continuous range of pages.

Proposed Implementation

def extract_pages(
    self,
    input_file: FileInput,
    start_page: int,
    end_page: Optional[int] = None,  # None means to end
    output_path: Optional[str] = None,
) -> Optional[bytes]:

Benefits

• Simpler API than split_pdf for common use case
• More intuitive for single range extraction
• Clear intent and usage
• Memory efficient for large documents

Implementation Details

• Use Build API with single FilePart and page range
• Support negative indexing (-1 for last page)
• Handle "to end" extraction with None
• Clear error messages for invalid ranges

Testing Requirements

• Test single page extraction
• Test range extraction
• Test "to end" extraction (end_page=None)
• Test negative page indexes
• Test invalid ranges (start > end)
• Test out of bounds pages

OpenAPI Reference

• Uses FilePart with pages parameter
• Page ranges use start/end format
• Build API with single part

Use Case Example

# Extract first 10 pages
first_chapter = client.extract_pages(
    "book.pdf",
    start_page=0,
    end_page=10
)

# Extract from page 50 to end
appendix = client.extract_pages(
    "book.pdf", 
    start_page=50
    # end_page=None means to end
)

# Extract single page
cover = client.extract_pages(
    "book.pdf",
    start_page=0,
    end_page=1
)

Relationship to split_pdf

• split_pdf: Multiple ranges, multiple outputs
• extract_pages: Single range, single output
• This method is essentially split_pdf with a single range

Priority

🟢 Priority 2 - Core missing method

Labels

• feature
• pdf-manipulation
• pages
• openapi-compliance

[jdrhyne]

Status: Addressed by PR #7's split_pdf implementation

The split_pdf() method in PR #7 provides the functionality requested:

# Extract pages 5-10 (0-based indexing)
result = client.split_pdf(
    "document.pdf",
    page_ranges=[{"start": 4, "end": 10}]
)

# Extract from page 10 to end
result = client.split_pdf(
    "document.pdf", 
    page_ranges=[{"start": 9}]  # Omit 'end' to go to end of document
)

While the method name is split_pdf rather than extract_pages, it provides the exact functionality described in this issue:

• Single range extraction ✅
• Support for "to end" extraction ✅
• Clear error messages for invalid ranges ✅
• Memory efficient implementation ✅