Annotations Reference

class pdfnaut.objects.annotations.Annotation

Bases: PdfDictionary

An annotation associates an object such as a note, link, or multimedia element with a location on a page of a PDF document.

See ISO 32000-2:2020 § 12.5 “Annotations” for details.

__init__(kind: Literal[typing.Union[typing.Literal['Text', 'FreeText', 'Line', 'Square', 'Circle', 'Polygon', 'PolyLine', 'Highlight', 'Underline', 'Squiggly', 'StrikeOut', 'Caret', 'Stamp', 'Ink', 'FileAttachment', 'Sound', 'Redact', 'Projection'], typing.Literal['Link', 'Popup', 'Movie', 'Screen', 'Widget', 'PrinterMark', 'TrapNet', 'Watermark', '3D', 'RichMedia']]], rect: Iterable[float], contents: str | None = None, name: str | None = None, *, indirect_ref: PdfReference | None = None) → None

color: list[float] | None

An array of 0 to 4 numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

• The background of the annotation’s icon when closed.

• The title bar of the annotation’s popup window.

• The border of a link annotation.

The number of array elements determines the color space in which the color shall be defined: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

contents: str | None

The text contents that shall be displayed when the annotation is open or, if this annotation kind does not display text, an alternate description of the annotation’s contents.

flags: AnnotationFlags

Flags specifying various characteristics of the annotation.

kind: Literal[typing.Union[typing.Literal['Text', 'FreeText', 'Line', 'Square', 'Circle', 'Polygon', 'PolyLine', 'Highlight', 'Underline', 'Squiggly', 'StrikeOut', 'Caret', 'Stamp', 'Ink', 'FileAttachment', 'Sound', 'Redact', 'Projection'], typing.Literal['Link', 'Popup', 'Movie', 'Screen', 'Widget', 'PrinterMark', 'TrapNet', 'Watermark', '3D', 'RichMedia']]]

2020 “Table 171 — Annotation types” for details.

Type:

The kind of annotation. See ISO 32000-2

language: str | None

(PDF 2.0) A language identifier specifying the natural language for all text in the annotation except where overridden by other explicit language specifications

See ISO 32000-2:2020 § 14.9.2 “Natural language specification” for details.

last_modified: str | None

The date and time the annotation was most recently modified. This value should be a PDF date string but PDF processors are expected to accept and display a string in any format.

name: str | None

An annotation name uniquely identifying the annotation among others in its page.

rect: list[float]

A rectangle specifying the location of the annotation in the page.

class pdfnaut.objects.annotations.AnnotationBorderStyle

Bases: PdfDictionary

The border style for the outline that surrounds an annotation.

See ISO 32000-2:2020 § 12.5.4 “Border styles” for details.

__init__(width=1, style=BorderStyleType.SOLID, dash_pattern=None)

dash_pattern: list[int] | None

The dash pattern that will be used for the border if the style specified is dashed. The array consists of alternating dashes and gaps. The dash phase is not specified and is assumed to be zero.

style: BorderStyleType | str

The border style.

width: float

The border width in points.

class pdfnaut.objects.annotations.AnnotationFlags

Bases: IntFlag

Flags for a particular annotation.

See ISO 32000-2:2020 § 12.5.3 “Annotation flags” for details.

HIDDEN = 2

Do not render the annotation or allow user interaction with it.

INVISIBLE = 1

If the annotation is non-standard, do not render or print the annotation.

If this flag is clear, the annotation shall be rendered according to its appearance stream.

LOCKED = 128

Do not allow the annotation to be removed or its properties to be modified but still allow its contents to be modified.

LOCKED_CONTENTS = 512

Do not allow the contents of the annotation to be modified.

NO_ROTATE = 16

Do not rotate the annotation to match the page’s rotation.

NO_VIEW = 32

Do not render the annotation or allow user interaction with it, but still allow printing according to the AnnotationFlags.PRINT flag.

NO_ZOOM = 8

Do not scale the annotation’s appearance to the page’s zoom factor.

NULL = 0

A default value meaning that no flags are set.

PRINT = 4

Print the annotation when the page is printed unless AnnotationFlags.HIDDEN is set. If clear, do not print the annotation.

READ_ONLY = 64

Do not allow user interaction with the annotation. This is ignored for Widget annotations.

TOGGLE_NO_VIEW = 256

Toggle the AnnotationFlags.NO_VIEW flag when selecting or hovering over the annotation.

__new__(value)

class pdfnaut.objects.annotations.AnnotationList

Bases: MutableSequence[Annotation]

A mutable sequence representing the list of annotations (the Annots key) in a page object.

__init__(array: PdfArray, pdf: PdfParser | None = None) → None

append(value: Annotation) → None

Appends an annotation value to the list.

clear() → None

Clears the annotation list.

extend(values: Iterable[Annotation]) → None

Extends the annotation list by appending values to its end.

insert(index: int, value: Annotation) → None

Inserts an annotation value at index.

pop(index: int = -1) → Annotation

Pops an annotation at index.

remove(value: Annotation) → None

Removes an annotation value from the list.

reverse() → None

Reverses the annotation list.

class pdfnaut.objects.annotations.AnnotationReplyType

Bases: str, Enum

The reply type or relationship between an annotation and its annotation’s MarkupAnnotation.in_reply_to value.

GROUP = 'Group'

The annotation shall be grouped with the annotation replied to.

REPLY = 'R'

The annotation is considered a reply to another annotation.

__new__(value)

class pdfnaut.objects.annotations.BorderStyleType

Bases: str, Enum

The border style type applied to an annotation via AnnotationBorderStyle.

BEVELED = 'B'

A simulated embossed (beveled) rectangle.

DASHED = 'D'

A dashed rectangle specified by AnnotationBorderStyle.dash_pattern.

INSET = 'I'

A simulated engraved (inset) rectangle.

SOLID = 'S'

A solid rectangle.

UNDERLINE = 'U'

An underline.

__new__(value)

class pdfnaut.objects.annotations.LineAnnotation

Bases: MarkupAnnotation

A line annotation displays a simple straight line on the page.

See ISO 32000-2:2020 § 12.5.6.7 “Line annotations” for details.

__init__(rect: Iterable[float], p1: tuple[int, int], p2: tuple[int, int], line_endings: tuple[LineEndingStyle, LineEndingStyle] | None = None, contents: str | None = None, name: str | None = None, *, indirect_ref: PdfReference | None = None) → None

border_style: AnnotationBorderStyle | None

The border style of the line annotation, controlling the width and dash pattern of the line.

color: list[float] | None

An array of 0 to 4 numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

• The background of the annotation’s icon when closed.

• The title bar of the annotation’s popup window.

• The border of a link annotation.

The number of array elements determines the color space in which the color shall be defined: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

contents: str | None

The text contents that shall be displayed when the annotation is open or, if this annotation kind does not display text, an alternate description of the annotation’s contents.

creation_date: datetime | None

The datetime the annotation was created.

flags: AnnotationFlags

Flags specifying various characteristics of the annotation.

kind: AnnotationKind

2020 “Table 171 — Annotation types” for details.

Type:

The kind of annotation. See ISO 32000-2

language: str | None

(PDF 2.0) A language identifier specifying the natural language for all text in the annotation except where overridden by other explicit language specifications

See ISO 32000-2:2020 § 14.9.2 “Natural language specification” for details.

last_modified: str | None

The date and time the annotation was most recently modified. This value should be a PDF date string but PDF processors are expected to accept and display a string in any format.

line_ending_color: list[float] | None

The interior color that will be used for the line endings.

The number of elements determines the color space: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

property line_endings: tuple[LineEndingStyle, LineEndingStyle]

The line ending styles to use when drawing the line.

The value consists of two line endings for the first and second pair of coordinates, respectively.

name: str | None

An annotation name uniquely identifying the annotation among others in its page.

path: list[float]

An array of four numbers (x1, y1, x2, y2) representing the start and end coordinates of the line in default user space units.

rect: list[float]

A rectangle specifying the location of the annotation in the page.

subject: str | None

A short description of the subject being addressed by the annotation.

title: str | None

The text label to display as the title of the annotation’s popup window. This shall identify the user who added the annotation.

class pdfnaut.objects.annotations.LineEndingStyle

Bases: str, Enum

The line ending style used for annotations.

See ISO 32000-2:2020 § Table 179 - “Line ending styles” for details.

__new__(value)

class pdfnaut.objects.annotations.LinkAnnotation

Bases: Annotation

A link annotation represents either a hypertext link to a location within the document or an action to perform.

See ISO 32000-2:2020 § 12.5.6.5 “Link annotations” for details.

__init__(rect: Iterable[float], contents: str | None = None, name: str | None = None, action: Action | None = None, destination: PdfName | PdfHexString | bytes | Destination | None = None, *, indirect_ref: PdfReference | None = None) → None

property action: Action | None

The action that shall be performed when the link annotation is triggered.

property border_style: AnnotationBorderStyle | None

The border style specifying the line width and dash pattern that shall be used when drawing the annotation outline.

color: list[float] | None

An array of 0 to 4 numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

• The background of the annotation’s icon when closed.

• The title bar of the annotation’s popup window.

• The border of a link annotation.

The number of array elements determines the color space in which the color shall be defined: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

contents: str | None

The text contents that shall be displayed when the annotation is open or, if this annotation kind does not display text, an alternate description of the annotation’s contents.

property destination: PdfName | PdfHexString | bytes | Destination | None

The destination that shall be displayed when the link annotation is triggered.

flags: AnnotationFlags

Flags specifying various characteristics of the annotation.

highlight_mode: LinkHighlightMode | str

The annotation’s highlight mode.

kind: AnnotationKind

2020 “Table 171 — Annotation types” for details.

Type:

The kind of annotation. See ISO 32000-2

language: str | None

(PDF 2.0) A language identifier specifying the natural language for all text in the annotation except where overridden by other explicit language specifications

See ISO 32000-2:2020 § 14.9.2 “Natural language specification” for details.

last_modified: str | None

The date and time the annotation was most recently modified. This value should be a PDF date string but PDF processors are expected to accept and display a string in any format.

name: str | None

An annotation name uniquely identifying the annotation among others in its page.

quad_points: list[float] | None

A sequence of n quadrilaterals, comprised of 8 numbers representing the coordinates in default user space that comprise the region in which the link should be activated.

Item order: x1, y1, x2, y2, x3, y3, x4, y4

rect: list[float]

A rectangle specifying the location of the annotation in the page.

class pdfnaut.objects.annotations.LinkHighlightMode

Bases: str, Enum

The highlighting mode for link annotations (see LinkAnnotation).

INVERT_CONTENTS = 'I'

Invert the contents of the annotation rectangle (default).

INVERT_OUTLINE = 'O'

Invert the annotation’s border or outline.

NONE = 'N'

No highlight.

PUSH = 'P'

Display the annotation as if it were being pushed below the surface of the page.

__new__(value)

class pdfnaut.objects.annotations.MarkupAnnotation

Bases: Annotation

A markup annotation is a type of annotation used primarily to mark PDF documents.

See ISO 32000-2:2020 § 12.5.6.2 “Markup annotations” for details.

__init__(kind: Literal[typing.Union[typing.Literal['Text', 'FreeText', 'Line', 'Square', 'Circle', 'Polygon', 'PolyLine', 'Highlight', 'Underline', 'Squiggly', 'StrikeOut', 'Caret', 'Stamp', 'Ink', 'FileAttachment', 'Sound', 'Redact', 'Projection'], typing.Literal['Link', 'Popup', 'Movie', 'Screen', 'Widget', 'PrinterMark', 'TrapNet', 'Watermark', '3D', 'RichMedia']]], rect: Iterable[float], contents: str | None = None, name: str | None = None, *, indirect_ref: PdfReference | None = None) → None

color: list[float] | None

An array of 0 to 4 numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

• The background of the annotation’s icon when closed.

• The title bar of the annotation’s popup window.

• The border of a link annotation.

The number of array elements determines the color space in which the color shall be defined: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

contents: str | None

The text contents that shall be displayed when the annotation is open or, if this annotation kind does not display text, an alternate description of the annotation’s contents.

creation_date: datetime | None

The datetime the annotation was created.

flags: AnnotationFlags

Flags specifying various characteristics of the annotation.

property in_reply_to: Annotation | None

The annotation that this annotation is in reply to.

kind: AnnotationKind

2020 “Table 171 — Annotation types” for details.

Type:

The kind of annotation. See ISO 32000-2

language: str | None

(PDF 2.0) A language identifier specifying the natural language for all text in the annotation except where overridden by other explicit language specifications

See ISO 32000-2:2020 § 14.9.2 “Natural language specification” for details.

last_modified: str | None

The date and time the annotation was most recently modified. This value should be a PDF date string but PDF processors are expected to accept and display a string in any format.

name: str | None

An annotation name uniquely identifying the annotation among others in its page.

rect: list[float]

A rectangle specifying the location of the annotation in the page.

property reply_type: AnnotationReplyType | str | None

The relationship or reply type between this annotation and the one in in_reply_to.

subject: str | None

A short description of the subject being addressed by the annotation.

title: str | None

The text label to display as the title of the annotation’s popup window. This shall identify the user who added the annotation.

class pdfnaut.objects.annotations.RectangleAnnotation

Bases: MarkupAnnotation

A rectangle annotation displays a rectangle on the page.

See ISO 32000-2:2020 § 12.5.6.8 “Square and circle annotations” for details.

__init__(rect: Iterable[float], interior_color: list[float] | None = None, border_style: AnnotationBorderStyle | None = None, contents: str | None = None, name: str | None = None, *, indirect_ref: PdfReference | None = None) → None

border_style: AnnotationBorderStyle | None

The border style of the rectangle.

color: list[float] | None

An array of 0 to 4 numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

• The background of the annotation’s icon when closed.

• The title bar of the annotation’s popup window.

• The border of a link annotation.

The number of array elements determines the color space in which the color shall be defined: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

contents: str | None

The text contents that shall be displayed when the annotation is open or, if this annotation kind does not display text, an alternate description of the annotation’s contents.

creation_date: datetime | None

The datetime the annotation was created.

flags: AnnotationFlags

Flags specifying various characteristics of the annotation.

interior_color: list[float] | None

The interior color that will be used for the rectangle.

The number of elements determines the color space: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

kind: AnnotationKind

2020 “Table 171 — Annotation types” for details.

Type:

The kind of annotation. See ISO 32000-2

language: str | None

(PDF 2.0) A language identifier specifying the natural language for all text in the annotation except where overridden by other explicit language specifications

See ISO 32000-2:2020 § 14.9.2 “Natural language specification” for details.

last_modified: str | None

The date and time the annotation was most recently modified. This value should be a PDF date string but PDF processors are expected to accept and display a string in any format.

name: str | None

An annotation name uniquely identifying the annotation among others in its page.

rect: list[float]

A rectangle specifying the location of the annotation in the page.

subject: str | None

A short description of the subject being addressed by the annotation.

title: str | None

The text label to display as the title of the annotation’s popup window. This shall identify the user who added the annotation.

class pdfnaut.objects.annotations.TextAnnotation

Bases: MarkupAnnotation

A text annotation represents a sticky note attached to a point in the PDF document. When closed, it shall appear as an icon (defined by TextAnnotation.icon); when open, it shall display a popup window containing the text of the note.

See ISO 32000-2:2020 § 12.5.6.4 “Text annotations” for details.

__init__(rect: Iterable[float], contents: str | None = None, name: str | None = None, is_open: bool = False, icon: str = 'Note', *, indirect_ref: PdfReference | None = None) → None

color: list[float] | None

An array of 0 to 4 numbers in the range 0.0 to 1.0, representing a color used for the following purposes:

• The background of the annotation’s icon when closed.

• The title bar of the annotation’s popup window.

• The border of a link annotation.

The number of array elements determines the color space in which the color shall be defined: 0 is no color or transparent, 1 is grayscale, 3 is RGB, and 4 is CMYK.

contents: str | None

The text contents that shall be displayed when the annotation is open or, if this annotation kind does not display text, an alternate description of the annotation’s contents.

creation_date: datetime | None

The datetime the annotation was created.

flags: AnnotationFlags

Flags specifying various characteristics of the annotation.

icon: Annotated[str, 'name']

The name of an icon that shall be used when displaying the annotation.

The icon name may be any of the following standard names or any other supported value.

Standard names: Comment, Key, Note, Help, NewParagraph, Paragraph, and Insert.

is_open: bool

Whether the annotation is initially displayed open.

kind: AnnotationKind

2020 “Table 171 — Annotation types” for details.

Type:

The kind of annotation. See ISO 32000-2

language: str | None

(PDF 2.0) A language identifier specifying the natural language for all text in the annotation except where overridden by other explicit language specifications

See ISO 32000-2:2020 § 14.9.2 “Natural language specification” for details.

last_modified: str | None

The date and time the annotation was most recently modified. This value should be a PDF date string but PDF processors are expected to accept and display a string in any format.

name: str | None

An annotation name uniquely identifying the annotation among others in its page.

rect: list[float]

A rectangle specifying the location of the annotation in the page.

subject: str | None

A short description of the subject being addressed by the annotation.

title: str | None

The text label to display as the title of the annotation’s popup window. This shall identify the user who added the annotation.

pdfnaut.objects.annotations.annotation_into(annot: PdfDictionary, *, indirect_ref: PdfReference | None = None) → Annotation

Converts a mapping annot into an instance of Annotation or one of its subclasses according to the annotation subtype.