Which AnnotationBuilder design should we use?

[MartinThoma]

The AnnotationBuilder class as multiple methods. Each method creates a different annotation type. Currently, the return value is simply a DictionaryObject.

Annotations have a few required attributes and a lot of optional attributes. Some of the optional attributes are shared across the annotations, but most are not.

Possible paths forward

I see three ways to add the optional attributes:

1. Plain parameters: Add more (keyword-only) parameters
2. Fluid design: Keep only the mandatory parameters and return an AnnotationDictionary. Add set_XYZ methods to the AnnotationDictionary. Those create a copy of the whole object, similar to the Transformation class.
3. AnnotationDictionary-base + Custom classes + properties: Keep only the mandatory parameters and return a class inheriting from (a new to-be-created) AnnotationDictionary. Add XYZproperties to the AnnotationDictionary.

All three options could use more complex attributes, e.g.

• A new AnnotationMeta class which would have (1) the author of the annotation, (2) contents (3) modification date
• A new AnnotationAppearance class which would have (1) border_color (2) fill_color

Shared parameter

According to "Table 164 – Entries common to all annotation dictionaries" the following properties are shared:

• Type / Subtype: Those are specific to the annotation and should be hidden from the user.

1. Rect (mandatory): Typically the location of the annotation; it's a bit more complicated for some (e.g. the geometric ones and potentially also the text annotations)
2. Contents: Text that shall be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation’s contents in human-readable form. In either case, this text is useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes
3. P: An indirect reference to the page object with which this annotation is associated
4. NM: The annotation name, a text string uniquely identifying it among all the annotations on its page.
5. M: The date and time when the annotation was most recently modified.
6. F: A set of flags specifying various characteristics of the annotation
7. AP: An appearance dictionary specifying how the annotation shall be presented visually
8. AS: The annotation’s appearance state, which selects the applicable appearance stream from an appearance subdictionary
9. Border: An array specifying the characteristics of the annotation’s border, which shall be drawn as a rounded rectangle.
10. C: An array of numbers in the range 0.0 to 1.0, representing a colour used for the following purposes: (1) The background of the annotation’s icon when closed (2) The title bar of the annotation’s pop-up window (3) The border of a link annotation
11. StructParent: The integer key of the annotation’s entry in the structural parent tree
12. OC: An optional content group or optional content membership dictionary

There is also "Table 171 – Annotation states" adding potentially a few more:

• "Marked" and "Review" states
• The T entry (see Table 170) shall specify the user.
• The IRT entry (see Table 173) shall refer to the original annotation

Pros / Cons

Plain Parameter vs Rest

• Pro: It's simpler to write, simpler to use. Just one way to influence what annotation you get
• Con: Likely duplicated code within pypdf

AnnotationDictionary-base + Custom classes + properties

• Pro: Simpler and more intuitive than the Annotation-builder pattern
• Neutral: Annotations are not as easy to discover. But we can just make a public submodule pypdf.annotations to get rid of that issue.
• Pro: Shared parameters / behavior can be part of the Annotation-builder pattern
• Con: It's harder for the user to add missing parts. But we could add something like "to_dict" so that the user could continue with that.

What do other libraries do?

PyMuPDF

A lot in plain parameters, but also some (non-fluid) parameters 🤔 😕

See https://pymupdf.readthedocs.io/en/latest/recipes-annotations.html

annot = page.add_freetext_annot(
    r,
    t1,
    fontsize=10,
    rotate=90,
    text_color=blue,
    fill_color=gold,
    align=fitz.TEXT_ALIGN_CENTER,
)
annot.set_border(width=0.3, dashes=[2])
annot.update(text_color=blue, fill_color=gold)

FPDF2

https://pyfpdf.github.io/fpdf2/Annotations.html

Looks like pure parameters:

pdf.ink_annotation([(100, 200), (200, 100), (300, 200), (200, 300), (100, 200)],
                   title="Lucas", contents="Hello world!")

pdf.text_annotation(
    x=100,
    y=130,
    text="This is a text annotation.",
)

# This part is confusing me a lot:
with pdf.highlight("Highlight comment"):
    pdf.text(50, 50, "Line 1")
    pdf.set_y(50)
    pdf.multi_cell(w=30, txt="Line 2")

Question / Discussion

What do you think about the three options? Which aspects are important to you? Where do you see pros / cons?

[hirenpopat67]

How to improve:-

Consider creating a separate class for each annotation type: This would help organize the code and make it easier to understand. Each class would be responsible for creating annotations of a specific type and could have its own set of required and optional attributes.

Use inheritance to share common attributes: If there are optional attributes that are shared between multiple annotation types, consider using inheritance to avoid duplicating code. we could create a base Annotation class with the shared attributes, and then create subclasses for each annotation type that inherit from the base class.

[MartinThoma]

Thank you for your input. The suggestion to create a AnnotationDictionary base class and subclasses for each type is a variant that we hadn't discussed yet. I think it's strictly better than the "(3) Properties" suggestion, hence I adjusted that suggestion to "(3) Custom classes + properties"

[MartinThoma]

Thinking about it: An advantage of the class-based approach is that we could completely get rid of the AnnotationBuilder. It would simply not be necessary anymore (of course following the deprecation process to not break anybodies workflow).

This would make the usage simpler for new developers. I like that a lot.

[MartinThoma]

#1745 - here is a first draft. There are no common attributes (so far).

[hirenpopat67]

@MartinThoma ,

Great, Using an abstract base class provides a common interface for different annotation types, which can make the code more modular and maintainable.
Thanks for taking my opinion

In my opinion creating an abstract base class for annotations seems to be a good design choice...