Skip to main content
Version: API v2 Preview

Position

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

Spatial locator used to find or place objects on a page.

Parameters:

  • page_number: One-based page number this position refers to. Required for most operations that place or search on a specific page; use Position.at_page() as a shortcut.
  • shape: Optional geometric shape used when matching by area (POINT, LINE, CIRCLE, RECT).
  • mode: How to match objects relative to the shape (INTERSECT or CONTAINS).
  • bounding_rect: Rectangle describing the area or point (for POINT, width/height are 0).
  • text_starts_with: Filter for text objects whose content starts with this string.
  • text_pattern: Regex pattern to match text content.
  • name: Named anchor or element name to target (e.g. form field name).

Builder helpers:

  • Position.at_page(page_number) – target a whole page.
  • Position.at_page_coordinates(page_number, x, y) – target a point on a page.
  • Position.by_name(name) – target object(s) by name.
  • pos.at_coordinates(Point(x, y)) – switch to a point on the current page.
  • pos.move_x(dx), pos.move_y(dy) – offset the current coordinates.

Examples:

# A point on page 1
pos = Position.at_page_coordinates(1, x=72, y=720)

# Search by name (e.g. a form field) and then move down 12 points
pos = Position.by_name("Email").move_y(-12)

# Match anything intersecting a rectangular area on page 1
pos = Position.at_page(1)
pos.shape = ShapeType.RECT
pos.mode = PositionMode.INTERSECT
pos.bounding_rect = BoundingRect(x=100, y=100, width=200, height=50)

Declaration​

Position(page_number: int | None = None, shape: pdfdancer.models.ShapeType | None = None, mode: pdfdancer.models.PositionMode | None = None, bounding_rect: pdfdancer.models.BoundingRect | None = None, text_starts_with: str | None = None, text_pattern: str | None = None, name: str | None = None) -> None

Members​

__init__​

__init__(self, page_number: int | None = None, shape: pdfdancer.models.ShapeType | None = None, mode: pdfdancer.models.PositionMode | None = None, bounding_rect: pdfdancer.models.BoundingRect | None = None, text_starts_with: str | None = None, text_pattern: str | None = None, name: str | None = None) -> None

Initialize self. See help(type(self)) for accurate signature.

at_coordinates​

at_coordinates(self, point: pdfdancer.models.Point) -> 'Position'

Sets the position to a specific point location.

at_page​

at_page(page_number: int) -> 'Position'

Creates a position specification for an entire page.

at_page_coordinates​

at_page_coordinates(page_number: int, x: float, y: float) -> 'Position'

Creates a position specification for specific coordinates on a page.

by_name​

by_name(name: str) -> 'Position'

Creates a position specification for finding objects by name.

move_x​

move_x(self, x_offset: float) -> 'Position'

Move the position horizontally by the specified offset.

move_y​

move_y(self, y_offset: float) -> 'Position'

Move the position vertically by the specified offset.

with_text_starts​

with_text_starts(self, text: str) -> 'Position'

x​

x(self) -> float | None

Returns the X coordinate of this position.

y​

y(self) -> float | None

Returns the Y coordinate of this position.

View source at af2a1171a1b9