Skip to main content
Version: API v2 Preview

PDFDancer

Kind: class
Module/package: pdfdancer_v2
SDK: pdfdancer-client-python 2.0.0

REST API client for interacting with the PDFDancer PDF manipulation service. This client provides a convenient Python interface for performing PDF operations including session management, object searching, manipulation, and retrieval. Handles authentication, session lifecycle, and HTTP communication transparently.

Declaration​

PDFDancer(token: 'str', pdf_data: 'Union[bytes, Path, str, BinaryIO]', base_url: 'str', read_timeout: 'float' = 0, max_attempts: 'int' = 3, retry_backoff_factor: 'float' = 2.0)

Members​

__init__​

__init__(self, token: 'str', pdf_data: 'Union[bytes, Path, str, BinaryIO]', base_url: 'str', read_timeout: 'float' = 0, max_attempts: 'int' = 3, retry_backoff_factor: 'float' = 2.0)

Creates a new client with PDF data. This constructor initializes the client, uploads the PDF data to create a new session, and prepares the client for PDF manipulation operations.

Args: token: Authentication token for API access pdf_data: PDF file data as bytes, Path, filename string, or file-like object base_url: Base URL of the PDFDancer API server read_timeout: Timeout in seconds for HTTP requests (default: 30.0) max_attempts: Maximum number of total attempts (default: 3). The initial request counts as one attempt. retry_backoff_factor: Base multiplier for exponential backoff delays (default: 2.0). Delay calculation: initial_delay * (retry_backoff_factor ** attempt_number). Examples: 2.0 → delays of 1s, 2s, 4s; 3.0 → delays of 1s, 3s, 9s.

Raises: ValidationException: If token is empty or PDF data is invalid SessionException: If session creation fails HttpClientException: If HTTP communication fails

clear_clipping​

clear_clipping(self, object_ref: 'ObjectRef') -> 'bool'

Clear clipping on a single PDF object.

Args: object_ref: Reference to the object whose clipping should be removed

Returns: True when the server cleared clipping successfully

clear_path_group_clipping​

clear_path_group_clipping(self, page_number: 'int', group_id: 'str') -> 'bool'

Clear clipping for a grouped set of paths.

Args: page_number: 1-based page number containing the path group group_id: Identifier returned by group_paths(...)

Returns: True when the server cleared clipping successfully

close​

close(self) -> 'None'

Close the HTTP client and free resources.

find_fonts​

find_fonts(self, font_name: 'str', font_size: 'int') -> 'List[Font]'

Finds available fonts matching the specified name and size.

Args: font_name: Name of the font to search for font_size: Size of the font

Returns: List of matching Font objects

get_bytes​

get_bytes(self) -> 'bytes'

Downloads the current state of the PDF document with all modifications applied.

Returns: PDF file data as bytes with all session modifications applied

get_document_snapshot​

get_document_snapshot(self, types: 'Optional[str]' = None) -> 'DocumentSnapshot'

Retrieve a snapshot of the entire document with all pages and elements.

Args: types: Optional comma-separated string of object types to filter (e.g., "TEXT_LINE,IMAGE")

Returns: DocumentSnapshot containing page count, fonts, and all page snapshots

get_page_snapshot​

get_page_snapshot(self, page_number: 'int', types: 'Optional[str]' = None) -> 'PageSnapshot'

Retrieve a snapshot of a specific page with all its elements.

Args: page_number: The page number to snapshot (1-based, page 1 is first page) types: Optional comma-separated string of object types to filter (e.g., "TEXT_LINE,IMAGE")

Returns: PageSnapshot containing page reference and all elements on that page

Raises: ValidationException: If page_number is less than 1

move_page​

move_page(self, from_page: 'int', to_page: 'int') -> 'bool'

Move a page to a different position within the document.

Args: from_page: The source page number (1-based, page 1 is first page) to_page: The target page number (1-based)

Returns: True if the page was successfully moved

Raises: ValidationException: If from_page or to_page is less than 1

new​

new(cls, token: 'Optional[str]' = None, base_url: 'Optional[str]' = None, timeout: 'float' = 30.0, page_size: 'Optional[Union[PageSize, str, Mapping[str, Any]]]' = None, orientation: 'Optional[Union[Orientation, str]]' = None, initial_page_count: 'int' = 1, max_attempts: 'int' = 3, retry_backoff_factor: 'float' = 2.0) -> "'PDFDancer'"

Create a new blank PDF document with optional configuration.

Authentication:

  • If token is provided, uses it
  • Otherwise, checks PDFDANCER_API_TOKEN environment variable (preferred)
  • Falls back to PDFDANCER_TOKEN environment variable (legacy)
  • If no token is found, automatically obtains an anonymous token

Args: token: Override for the API token; falls back to PDFDANCER_API_TOKEN or PDFDANCER_TOKEN environment variable, then to anonymous token if not set. base_url: Override for the API base URL; falls back to PDFDANCER_BASE_URL or defaults to https://api.pdfdancer.com. timeout: HTTP read timeout in seconds. page_size: Page size for the PDF (default: A4). Accepts PageSize, a standard name string, or a mapping with width/height values. orientation: Page orientation (default: PORTRAIT). Can be Orientation enum or string. initial_page_count: Number of initial blank pages (default: 1). max_attempts: Maximum number of total attempts (default: 3). The initial request counts as one attempt. retry_backoff_factor: Base multiplier for exponential backoff delays (default: 2.0). Delay calculation: initial_delay * (retry_backoff_factor ** attempt_number). Examples: 2.0 → delays of 1s, 2s, 4s; 3.0 → delays of 1s, 3s, 9s.

Returns: A ready-to-use PDFDancer client instance with a blank PDF.

new_bezier​

new_bezier(self, page_number: 'int') -> 'BezierBuilder'

new_image​

new_image(self) -> 'ImageBuilder'

new_line​

new_line(self, page_number: 'int') -> 'LineBuilder'

new_page​

new_page(self, orientation: 'Optional[Union[Orientation, str]]' = <Orientation.PORTRAIT: 'PORTRAIT'>, size: 'Optional[Union[PageSize, str, Mapping[str, Any]]]' = PageSize(name='A4', width=595.0, height=842.0)) -> 'PageBuilder'

new_path​

new_path(self, page_number: 'int') -> "'PathBuilder'"

new_rectangle​

new_rectangle(self, page_number: 'int') -> "'RectangleBuilder'"

open​

open(cls, pdf_data: 'Union[bytes, Path, str, BinaryIO]', token: 'Optional[str]' = None, base_url: 'Optional[str]' = None, timeout: 'float' = 30.0, max_attempts: 'int' = 3, retry_backoff_factor: 'float' = 2.0) -> "'PDFDancer'"

Create a client session, falling back to environment variables when needed.

Authentication:

  • If token is provided, uses it
  • Otherwise, checks PDFDANCER_API_TOKEN environment variable (preferred)
  • Falls back to PDFDANCER_TOKEN environment variable (legacy)
  • If no token is found, automatically obtains an anonymous token

Args: pdf_data: PDF payload supplied directly or via filesystem handles. token: Override for the API token; falls back to PDFDANCER_API_TOKEN or PDFDANCER_TOKEN environment variable, then to anonymous token if not set. base_url: Override for the API base URL; falls back to PDFDANCER_BASE_URL or defaults to https://api.pdfdancer.com. timeout: HTTP read timeout in seconds. max_attempts: Maximum number of total attempts (default: 3). The initial request counts as one attempt. retry_backoff_factor: Base multiplier for exponential backoff delays (default: 2.0). Delay calculation: initial_delay * (retry_backoff_factor ** attempt_number). Examples: 2.0 → delays of 1s, 2s, 4s; 3.0 → delays of 1s, 3s, 9s.

Returns: A ready-to-use PDFDancer client instance.

page​

page(self, page_number: 'int') -> 'PageClient'

Get a specific page by page number, using snapshot cache when available.

Args: page_number: The 1-based page number (page 1 is the first page)

Returns: PageClient with page properties populated

Raises: ValidationException: If page_number is less than 1

pages​

pages(self) -> 'List[PageClient]'

register_font​

register_font(self, ttf_file: 'Union[Path, str, bytes, BinaryIO]') -> 'str'

Registers a custom font for use in PDF operations.

Args: ttf_file: TTF font file as Path, filename, bytes, or file-like object

Returns: Font registration result

Raises: ValidationException: If font file is invalid HttpClientException: If registration fails

save​

save(self, file_path: 'Union[str, Path]') -> 'None'

Saves the current PDF to a file.

Args: file_path: Path where to save the PDF file

Raises: ValidationException: If file path is invalid PdfDancerException: If file writing fails

select_elements​

select_elements(self) -> 'List[ObjectRef]'

Select all live object-reference elements in the document.

Returns: List of all PDF objects in the document

select_form_field_by_name​

select_form_field_by_name(self, field_name: 'str') -> 'Optional[FormFieldObject]'

Select the first form field with the specified name.

Args: field_name: Name of the form field to search for

Returns: First FormFieldObject with the specified name, or None if no match

select_form_fields​

select_form_fields(self) -> 'List[FormFieldObject]'

Searches for form field objects in the whole document.

select_form_fields_by_name​

select_form_fields_by_name(self, field_name: 'str') -> 'List[FormFieldObject]'

Searches for form field objects in the whole document.

select_forms​

select_forms(self) -> 'List[FormObject]'

Searches for form field objects in the whole document.

select_images​

select_images(self) -> 'List[ImageObject]'

Searches for image objects in the whole document

select_paths​

select_paths(self) -> 'List[ObjectRef]'

Searches for vector path objects at the specified position.

text​

text(self) -> 'TextClient'

Return document-scoped selector-based text editing operations.

View source at af2a1171a1b9