The AnnotationBuilder Class

class pypdf.generic.AnnotationBuilder[source]

Bases: object

The AnnotationBuilder creates dictionaries representing PDF annotations.

Those dictionaries can be modified before they are added to a PdfWriter instance via writer.add_annotation.

See adding PDF annotations for it’s usage combined with PdfWriter.

static text(rect: Union[RectangleObject, Tuple[float, float, float, float]], text: str, open: bool = False, flags: int = 0) → DictionaryObject[source]

Add text annotation.

Parameters

  • rect – array of four integers [xLL, yLL, xUR, yUR] specifying the clickable rectangular area

  • text – The text that is added to the document

  • open –

  • flags –

Returns

A dictionary object representing the annotation.

static free_text(text: str, rect: Union[RectangleObject, Tuple[float, float, float, float]], font: str = 'Helvetica', bold: bool = False, italic: bool = False, font_size: str = '14pt', font_color: str = '000000', border_color: Optional[str] = '000000', background_color: Optional[str] = 'ffffff') → DictionaryObject[source]

Add text in a rectangle to a page.

Parameters

  • text – Text to be added

  • rect – array of four integers [xLL, yLL, xUR, yUR] specifying the clickable rectangular area

  • font – Name of the Font, e.g. ‘Helvetica’

  • bold – Print the text in bold

  • italic – Print the text in italic

  • font_size – How big the text will be, e.g. ‘14pt’

  • font_color – Hex-string for the color, e.g. cdcdcd

  • border_color – Hex-string for the border color, e.g. cdcdcd. Use None for no border.

  • background_color – Hex-string for the background of the annotation, e.g. cdcdcd. Use None for transparent background.

Returns

A dictionary object representing the annotation.

static popup(*, rect: ~typing.Union[~pypdf.generic._rectangle.RectangleObject, ~typing.Tuple[float, float, float, float]], flags: ~pypdf.constants.AnnotationFlag = AnnotationFlag.None, parent: ~typing.Optional[~pypdf.generic._data_structures.DictionaryObject] = None, open: bool = False) → DictionaryObject[source]

Add a popup to the document.

Parameters

  • rect – Specifies the clickable rectangular area as [xLL, yLL, xUR, yUR]

  • flags – 1 - invisible, 2 - hidden, 3 - print, 4 - no zoom, 5 - no rotate, 6 - no view, 7 - read only, 8 - locked, 9 - toggle no view, 10 - locked contents

  • open – Whether the popup should be shown directly (default is False).

  • parent – The contents of the popup. Create this via the AnnotationBuilder.

Returns

A dictionary object representing the annotation.

static line(p1: Tuple[float, float], p2: Tuple[float, float], rect: Union[RectangleObject, Tuple[float, float, float, float]], text: str = '', title_bar: str = '') → DictionaryObject[source]

Draw a line on the PDF.

Parameters

  • p1 – First point

  • p2 – Second point

  • rect – array of four integers [xLL, yLL, xUR, yUR] specifying the clickable rectangular area

  • text – Text to be displayed as the line annotation

  • title_bar – Text to be displayed in the title bar of the annotation; by convention this is the name of the author

Returns

A dictionary object representing the annotation.

static polyline(vertices: List[Tuple[float, float]]) → DictionaryObject[source]

Draw a polyline on the PDF.

Parameters

vertices – Array specifying the vertices (x, y) coordinates of the poly-line.

Returns

A dictionary object representing the annotation.

static rectangle(rect: Union[RectangleObject, Tuple[float, float, float, float]], interiour_color: Optional[str] = None) → DictionaryObject[source]

Draw a rectangle on the PDF.

This method uses the /Square annotation type of the PDF format.

Parameters

  • rect – array of four integers [xLL, yLL, xUR, yUR] specifying the clickable rectangular area

  • interiour_color – None or hex-string for the color, e.g. cdcdcd If None is used, the interiour is transparent.

Returns

A dictionary object representing the annotation.

static highlight(*, rect: Union[RectangleObject, Tuple[float, float, float, float]], quad_points: ArrayObject, highlight_color: str = 'ff0000') → DictionaryObject[source]

Add a highlight annotation to the document.

Parameters

  • rect – Array of four integers [xLL, yLL, xUR, yUR] specifying the highlighted area

  • quad_points – An ArrayObject of 8 FloatObjects. Must match a word or a group of words, otherwise no highlight will be shown.

  • highlight_color – The color used for the hightlight

Returns

A dictionary object representing the annotation.

static ellipse(rect: Union[RectangleObject, Tuple[float, float, float, float]], interiour_color: Optional[str] = None) → DictionaryObject[source]

Draw a rectangle on the PDF.

This method uses the /Circle annotation type of the PDF format.

Parameters

  • rect – array of four integers [xLL, yLL, xUR, yUR] specifying the bounding box of the ellipse

  • interiour_color – None or hex-string for the color, e.g. cdcdcd If None is used, the interiour is transparent.

Returns

A dictionary object representing the annotation.

Add a link to the document.

The link can either be an external link or an internal link.

An external link requires the URL parameter. An internal link requires the target_page_index, fit, and fit args.

Parameters

  • rect – array of four integers [xLL, yLL, xUR, yUR] specifying the clickable rectangular area

  • border – if provided, an array describing border-drawing properties. See the PDF spec for details. No border will be drawn if this argument is omitted. - horizontal corner radius, - vertical corner radius, and - border width - Optionally: Dash

  • url – Link to a website (if you want to make an external link)

  • target_page_index – index of the page to which the link should go (if you want to make an internal link)

  • fit – Page fit or ‘zoom’ option.

Returns

A dictionary object representing the annotation.