ENH: Add add_free_text_annotation to PdfWriter

Full credit to the GitHub user snakemicro:
#107 (comment)

Co-authored-by: snakemicro

PyPDF2/_utils.py

@@ -58,14 +58,18 @@
  float, float, float, float, float, float
 ]
 
-bytes_type = type(bytes()) # Works the same in Python 2.X and 3.X
+bytes_type = bytes # Works the same in Python 2.X and 3.X
 StreamType = Union[BytesIO, BufferedReader, BufferedWriter, FileIO]
 StrByteType = Union[str, StreamType]
 
 DEPR_MSG_NO_REPLACEMENT = "{} is deprecated and will be removed in PyPDF2 {}."
 DEPR_MSG = "{} is deprecated and will be removed in PyPDF2 3.0.0. Use {} instead."
 
 
+def hex_to_rgb(value: str) -> Tuple[int, int, int]:
+ return tuple(int(value[i : i + 2], 16) / 255.0 for i in (0, 2, 4)) # type: ignore
+
+
 def read_until_whitespace(stream: StreamType, maxchars: Optional[int] = None) -> bytes:
  """
  Reads non-whitespace characters and returns them.

PyPDF2/_writer.py

@@ -41,7 +41,7 @@
 from ._page import PageObject, _VirtualList
 from ._reader import PdfReader
 from ._security import _alg33, _alg34, _alg35
-from ._utils import StreamType, b_, deprecate_with_replacement
+from ._utils import StreamType, b_, deprecate_with_replacement, hex_to_rgb
 from .constants import CatalogAttributes as CA
 from .constants import Core as CO
 from .constants import EncryptionDictAttributes as ED
@@ -143,6 +143,62 @@ def getObject(self, ido: IndirectObject) -> PdfObject: # pragma: no cover
  deprecate_with_replacement("getObject", "get_object")
  return self.get_object(ido)
 
+ def add_free_text_annotation(
+ self,
+ page_number: int,
+ text: str,
+ rect: Tuple[float, float, float, float],
+ font: str = "Helvetica",
+ bold: bool = False,
+ italic: bool = False,
+ font_size: str = "14pt",
+ font_color: str = "ff0000",
+ border_color: str = "ff0000",
+ bg_color: str = "ffffff",
+ ) -> None:
+ """Add text in a rectangle to a page."""
+ page_link = self.get_object(self._pages)["/Kids"][page_number] # type: ignore
+ page_ref = cast(DictionaryObject, self.get_object(page_link))
+
+ font_str = "font: "
+ if bold is True:
+ font_str = font_str + "bold "
+ if italic is True:
+ font_str = font_str + "italic "
+ font_str = font_str + font + " " + font_size
+ font_str = font_str + ";text-align:left;color:#" + font_color
+
+ bg_color_str = ""
+ for st in hex_to_rgb(border_color):
+ bg_color_str = bg_color_str + str(st) + " "
+ bg_color_str = bg_color_str + "rg"
+
+ free_text = DictionaryObject()
+ free_text.update(
+ {
+ NameObject("/Type"): NameObject("/Annot"),
+ NameObject("/Subtype"): NameObject("/FreeText"),
+ NameObject("/P"): page_link,
+ NameObject("/Rect"): RectangleObject(rect),
+ NameObject("/Contents"): TextStringObject(text),
+ # font size color
+ NameObject("/DS"): TextStringObject(font_str),
+ # border color
+ NameObject("/DA"): TextStringObject(bg_color_str),
+ # background color
+ NameObject("/C"): ArrayObject(
+ [FloatObject(n) for n in hex_to_rgb(bg_color)]
+ ),
+ }
+ )
+
+ link_ref = self._add_object(free_text)
+
+ if "/Annots" in page_ref:
+ page_ref["/Annots"].append(link_ref) # type: ignore
+ else:
+ page_ref[NameObject("/Annots")] = ArrayObject([link_ref])
+
  def _add_page(
  self, page: PageObject, action: Callable[[Any, IndirectObject], None]
  ) -> None:

tests/test_writer.py

@@ -440,3 +440,17 @@ def test_issue301():
  writer.append_pages_from_reader(reader)
  o = BytesIO()
  writer.write(o)
+
+
+def test_add_free_text_annotation():
+ filepath = os.path.join(RESOURCE_ROOT, "crazyones.pdf")
+
+ writer = PdfWriter()
+ reader = PdfReader(filepath)
+
+ writer.add_page(reader.pages[0])
+
+ writer.add_free_text_annotation(0, "Hello World", rect=(0, 0, 100, 100))
+
+ with open("foo.pdf", "wb") as fh:
+ writer.write(fh)