Skip to content

ENH: Add /IRT (in-reply-to) support for markup annotations#3631

Merged
stefan6419846 merged 12 commits intopy-pdf:mainfrom
costajohnt:feat/add-irt-annotation-support-2065
Mar 4, 2026
Merged

ENH: Add /IRT (in-reply-to) support for markup annotations#3631
stefan6419846 merged 12 commits intopy-pdf:mainfrom
costajohnt:feat/add-irt-annotation-support-2065

Conversation

@costajohnt
Copy link
Contributor

Summary

Adds first-class support for PDF annotation replies (PDF spec 1.5, Table 170) to the MarkupAnnotation base class.

New parameters on MarkupAnnotation

  • in_reply_to: Reference to a parent annotation (the object returned by writer.add_annotation()). Sets the /IRT entry.
  • reply_type: Either "R" (reply, default) or "Group" (grouped). Sets the /RT entry.
  • annotation_name: Sets the /NM entry for annotation threading. Auto-generated as a UUID when in_reply_to is set and no name is provided.

Usage example

from pypdf import PdfWriter
from pypdf.annotations import Text

writer = PdfWriter()
writer.add_blank_page(width=612, height=792)

# Create parent annotation
parent = Text(text="Original comment", rect=(50, 700, 200, 750))
parent_ref = writer.add_annotation(0, parent)

# Create reply annotation
reply = Text(
    text="Reply to the comment",
    rect=(50, 700, 200, 750),
    in_reply_to=parent_ref,
)
writer.add_annotation(0, reply)

with open("annotated.pdf", "wb") as f:
    writer.write(f)

Design notes

  • Follows the same pattern as Popup(parent=...) for referencing other annotations via indirect_reference
  • Warns (without crashing) when in_reply_to receives an unregistered annotation object, matching the existing Popup behavior
  • All existing MarkupAnnotation subclasses require rect, so the workaround discovered in the issue thread (reply annotations need /Rect to be visible) is handled naturally

Tests

5 new tests covering:

  • Basic reply with /IRT, /RT, /NM verification + round-trip read
  • reply_type="Group" variant
  • Explicit annotation_name without in_reply_to
  • Custom annotation_name with in_reply_to
  • Graceful warning for unregistered parent annotations

Closes #2065

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ENH: Add PDF annotation /IRT ("in reply to")

2 participants