The annotations module

PDF specifies several annotation types which pypdf makes available here.

The names of the annotations and their attributes do not reflect the names in the specification in all cases. For example, the PDF standard defines a ‘Square’ annotation that does not actually need to be square. For this reason, pypdf calls it ‘Rectangle’.

At their core, all annotation types are DictionaryObjects. That means if pypdf does not implement a feature, users can easily extend the given functionality.

class pypdf.annotations.AnnotationDictionary[source]

Bases: DictionaryObject, ABC

property flags: AnnotationFlag
class pypdf.annotations.Ellipse(rect: RectangleObject | tuple[float, float, float, float], *, interior_color: str | None = None, **kwargs: Any)[source]

Bases: MarkupAnnotation

class pypdf.annotations.FreeText(*, text: str, rect: 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: str | None = '000000', background_color: str | None = 'ffffff', **kwargs: Any)[source]

Bases: MarkupAnnotation

A FreeText annotation

class pypdf.annotations.Highlight(*, rect: RectangleObject | tuple[float, float, float, float], quad_points: ArrayObject, highlight_color: str = 'ff0000', printing: bool = False, **kwargs: Any)[source]

Bases: MarkupAnnotation

class pypdf.annotations.Line(p1: tuple[float, float], p2: tuple[float, float], rect: RectangleObject | tuple[float, float, float, float], text: str = '', **kwargs: Any)[source]

Bases: MarkupAnnotation

Bases: AnnotationDictionary

class pypdf.annotations.MarkupAnnotation(*, title_bar: str | None = None, in_reply_to: DictionaryObject | IndirectObject | None = None, reply_type: Literal['R', 'Group'] = 'R', annotation_name: str | None = None)[source]

Bases: AnnotationDictionary, ABC

Base class for all markup annotations.

Parameters:

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

  • in_reply_to – The annotation that this annotation is “in reply to” (PDF 1.5). Can be either an annotation (previously added using add_annotation()) or a reference to the target annotation.

  • reply_type – The relationship between this annotation and the one specified by in_reply_to. Either "R" (a reply, default) or "Group" (grouped with the parent annotation). Raises ValueError if a non-default value is provided without in_reply_to.

  • annotation_name – A text string uniquely identifying this annotation among all annotations on its page. Automatically generated when in_reply_to is set and no name is provided. Raises ValueError if provided without in_reply_to.

class pypdf.annotations.PolyLine(vertices: list[tuple[float, float]], **kwargs: Any)[source]

Bases: MarkupAnnotation

class pypdf.annotations.Polygon(vertices: list[tuple[float, float]], **kwargs: Any)[source]

Bases: MarkupAnnotation

class pypdf.annotations.Popup(*, rect: RectangleObject | tuple[float, float, float, float], parent: DictionaryObject | None = None, open: bool = False, **kwargs: Any)[source]

Bases: AnnotationDictionary

class pypdf.annotations.Rectangle(rect: RectangleObject | tuple[float, float, float, float], *, interior_color: str | None = None, **kwargs: Any)[source]

Bases: MarkupAnnotation

class pypdf.annotations.Text(*, rect: ~pypdf.generic._rectangle.RectangleObject | tuple[float, float, float, float], text: str, open: bool = False, flags: int = <AnnotationFlag: 0>, **kwargs: ~typing.Any)[source]

Bases: MarkupAnnotation

A 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