MAINT: Cleanup of annotations (#1745)

The goal of this PR is to create a more intuitive interface for creating annotations. The AnnotationBuild gets deprecated in favor of several annotation classes, e.g.

```python
# old
from pypdf.generic import AnnotationBuilder
annotation = AnnotationBuilder.free_text(
    "Hello World\nThis is the second line!",
    rect=(50, 550, 200, 650),
    font="Arial",
    bold=True,
    italic=True,
    font_size="20pt",
    font_color="00ff00",
    border_color="0000ff",
    background_color="cdcdcd",
)

# new
from pypdf.annotations import FreeText
annotation = FreeText(
    text="Hello World\nThis is the second line!",
    rect=(50, 550, 200, 650),
    font="Arial",
    bold=True,
    italic=True,
    font_size="20pt",
    font_color="00ff00",
    border_color="0000ff",
    background_color="cdcdcd",
)
```

* `pypdf/generic/_annotations.py` ➔ `pypdf/annotations/`
* Create abstract base class AnnotationDictionary
* Create abstract base class MarkupAnnotation which inherits from AnnotationDictionary. Most annotations are MarkupAnnotations.
* Deprecated AnnotationBuilder
* Ensure the AnnotationBuilder is not used in the docs

Closes #107

docs/index.rst

@@ -54,7 +54,7 @@ You can contribute to `pypdf on GitHub <https://github.com/py-pdf/pypdf>`_.
  modules/RectangleObject
  modules/Field
  modules/PageRange
- modules/AnnotationBuilder
+ modules/annotations
  modules/Fit
  modules/PaperSize
 

docs/modules/annotations.rst

@@ -0,0 +1,7 @@
+The annotations module
+----------------------
+
+.. automodule:: pypdf.annotations
+ :members:
+ :undoc-members:
+ :show-inheritance:

docs/user/adding-pdf-annotations.md

@@ -22,11 +22,11 @@ If you want to add text in a box like this
 
 ![](free-text-annotation.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use the {py:class}`FreeText <pypdf.annotations.FreeText>`:
 
 ```python
 from pypdf import PdfReader, PdfWriter
-from pypdf.generic import AnnotationBuilder
+from pypdf.annotations import FreeText
 
 # Fill the writer with the pages you want
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
@@ -36,8 +36,8 @@ writer = PdfWriter()
 writer.add_page(page)
 
 # Create the annotation and add it
-annotation = AnnotationBuilder.free_text(
- "Hello World\nThis is the second line!",
+annotation = FreeText(
+ text="Hello World\nThis is the second line!",
  rect=(50, 550, 200, 650),
  font="Arial",
  bold=True,
@@ -66,17 +66,20 @@ If you want to add a line like this:
 
 ![](annotation-line.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use {py:class}`Line <pypdf.annotations.Line>`:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Line
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the line
-annotation = AnnotationBuilder.line(
+annotation = Line(
  text="Hello World\nLine2",
  rect=(50, 550, 200, 650),
  p1=(50, 550),
@@ -95,17 +98,20 @@ If you want to add a line like this:
 
 ![](annotation-polyline.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use {py:class}`PolyLine <pypdf.annotations.PolyLine>`:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Polyline
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the polyline
-annotation = AnnotationBuilder.polyline(
+annotation = Polyline(
  vertices=[(50, 550), (200, 650), (70, 750), (50, 700)],
 )
 writer.add_annotation(page_number=0, annotation=annotation)
@@ -121,17 +127,20 @@ If you want to add a rectangle like this:
 
 ![](annotation-square.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use {py:class}`Rectangle <pypdf.annotations.Rectangle>`:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Rectangle
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the rectangle
-annotation = AnnotationBuilder.rectangle(
+annotation = Rectangle(
  rect=(50, 550, 200, 650),
 )
 writer.add_annotation(page_number=0, annotation=annotation)
@@ -152,15 +161,20 @@ If you want to add a circle like this:
 
 ![](annotation-circle.png)
 
+you can use {py:class}`Ellipse <pypdf.annotations.Ellipse>`:
+
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Ellipse
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the rectangle
-annotation = AnnotationBuilder.ellipse(
+annotation = Ellipse(
  rect=(50, 550, 200, 650),
 )
 writer.add_annotation(page_number=0, annotation=annotation)
@@ -176,17 +190,20 @@ If you want to add a polygon like this:
 
 ![](annotation-polygon.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use {py:class}`Polygon <pypdf.annotations.Polygon>`:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Polygon
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the line
-annotation = AnnotationBuilder.polygon(
+annotation = Polygon(
  vertices=[(50, 550), (200, 650), (70, 750), (50, 700)],
 )
 writer.add_annotation(page_number=0, annotation=annotation)
@@ -202,26 +219,28 @@ Manage the Popup windows for markups. looks like this:
 
 ![](annotation-popup.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use the {py:class}`Popup <pypdf.annotations.Popup>`:
 
 you have to use the returned result from add_annotation() to fill-up the
 
 ```python
+from pypdf.annotations import Popup, Text
+
 # Arrange
 writer = pypdf.PdfWriter()
 writer.append(os.path.join(RESOURCE_ROOT, "crazyones.pdf"), [0])
 
 # Act
 text_annotation = writer.add_annotation(
  0,
- AnnotationBuilder.text(
+ Text(
  text="Hello World\nThis is the second line!",
  rect=(50, 550, 200, 650),
  open=True,
  ),
 )
 
-popup_annotation = AnnotationBuilder.popup(
+popup_annotation = Popup(
  rect=(50, 550, 200, 650),
  open=True,
  parent=text_annotation, # use the output of add_annotation
@@ -233,17 +252,20 @@ writer.write("annotated-pdf-popup.pdf")
 ## Link
 
 If you want to add a link, you can use
-the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+{py:class}`Link <pypdf.annotations.Link>`:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Link
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the line
-annotation = AnnotationBuilder.link(
+annotation = Link(
  rect=(50, 550, 200, 650),
  url="https://martin-thoma.com/",
 )
@@ -257,14 +279,17 @@ with open("annotated-pdf.pdf", "wb") as fp:
 You can also add internal links:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Link
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
 # Add the line
-annotation = AnnotationBuilder.link(
+annotation = Link(
  rect=(50, 550, 200, 650), target_page_index=3, fit="/FitH", fit_args=(123,)
 )
 writer.add_annotation(page_number=0, annotation=annotation)
@@ -287,17 +312,20 @@ If you want to highlight text like this:
 
 ![](annotation-highlight.png)
 
-you can use the {py:class}`AnnotationBuilder <pypdf.generic.AnnotationBuilder>`:
+you can use the {py:class}`Highlight <pypdf.annotations.Highlight>`:
 
 ```python
+from pypdf import PdfReader, PdfWriter
+from pypdf.annotations import Highlight
+
 pdf_path = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
 reader = PdfReader(pdf_path)
 page = reader.pages[0]
 writer = PdfWriter()
 writer.add_page(page)
 
-# Add the line
-annotation = AnnotationBuilder.polygon(
+# Add the highlight
+annotation = Highlight(
  vertices=[(50, 550), (200, 650), (70, 750), (50, 700)],
 )
 writer.add_annotation(page_number=0, annotation=annotation)

pypdf/_writer.py

@@ -68,6 +68,7 @@
  deprecation_with_replacement,
  logger_warning,
 )
+from .annotations import Link
 from .constants import AnnotationDictionaryAttributes as AA
 from .constants import CatalogAttributes as CA
 from .constants import (
@@ -90,7 +91,6 @@
 from .errors import PyPdfError
 from .generic import (
  PAGE_FIT,
- AnnotationBuilder,
  ArrayObject,
  BooleanObject,
  ByteStringObject,
@@ -2352,7 +2352,7 @@ def add_link(
  *args: ZoomArgType,
  ) -> DictionaryObject:
  deprecation_with_replacement(
- "add_link", "add_annotation(AnnotationBuilder.link(...))"
+ "add_link", "add_annotation(pypdf.annotations.Link(...))"
  )
 
  if isinstance(rect, str):
@@ -2365,7 +2365,7 @@ def add_link(
  else:
  rect = RectangleObject(rect)
 
- annotation = AnnotationBuilder.link(
+ annotation = Link(
  rect=rect,
  border=border,
  target_page_index=page_destination,
@@ -2388,7 +2388,7 @@ def addLink(
  .. deprecated:: 1.28.0
  """
  deprecate_with_replacement(
- "addLink", "add_annotation(AnnotationBuilder.link(...))", "4.0.0"
+ "addLink", "add_annotation(pypdf.annotations.Link(...))", "4.0.0"
  )
  self.add_link(pagenum, page_destination, rect, border, fit, *args)
 

pypdf/annotations/__init__.py

@@ -0,0 +1,46 @@
+"""
+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.
+"""
+
+
+from ._base import NO_FLAGS, AnnotationDictionary
+from ._markup_annotations import (
+ Ellipse,
+ FreeText,
+ Highlight,
+ Line,
+ Link,
+ MarkupAnnotation,
+ Polygon,
+ PolyLine,
+ Rectangle,
+ Text,
+)
+from ._non_markup_annotations import Popup
+
+__all__ = [
+ "NO_FLAGS",
+ # Export abstract base classes so that they are shown in the docs
+ "AnnotationDictionary",
+ "MarkupAnnotation",
+ # markup annotations
+ "Ellipse",
+ "FreeText",
+ "Highlight",
+ "Line",
+ "Link",
+ "Polygon",
+ "PolyLine",
+ "Rectangle",
+ "Text",
+ # Non-markup annotations
+ "Popup",
+]

pypdf/annotations/_base.py

@@ -0,0 +1,27 @@
+from abc import ABC
+
+from ..constants import AnnotationFlag
+from ..generic import NameObject, NumberObject
+from ..generic._data_structures import DictionaryObject
+
+
+class AnnotationDictionary(DictionaryObject, ABC):
+ def __init__(self) -> None:
+ from ..generic._base import NameObject
+
+ # "rect" should not be added here as PolyLine can automatically set it
+ self[NameObject("/Type")] = NameObject("/Annot")
+ # The flags was NOT added to the constructor on purpose: We expect that
+ # most users don't want to change the default. If they want, they
+ # can use the property. The default is 0.
+
+ @property
+ def flags(self) -> AnnotationFlag:
+ return self.get(NameObject("/F"), AnnotationFlag(0))
+
+ @flags.setter
+ def flags(self, value: AnnotationFlag) -> None:
+ self[NameObject("/F")] = NumberObject(value)
+
+
+NO_FLAGS = AnnotationFlag(0)