ENH: Allow free-text annotation to have transparent border/background

pypdf/generic/_annotations.py

@@ -68,8 +68,8 @@ def free_text(
  italic: bool = False,
  font_size: str = "14pt",
  font_color: str = "000000",
- border_color: str = "000000",
- background_color: str = "ffffff",
+ border_color: Optional[str] = "000000",
+ background_color: Optional[str] = "ffffff",
  ) -> DictionaryObject:
  """
  Add text in a rectangle to a page.
@@ -83,9 +83,10 @@ def free_text(
  italic: Print the text in italic
  font_size: How big the text will be, e.g. '14pt'
  font_color: Hex-string for the color, e.g. cdcdcd
- border_color: Hex-string for the border color, e.g. cdcdcd
+ border_color: Hex-string for the border color, e.g. cdcdcd.
+ Use `None` for no border.
  background_color: Hex-string for the background of the annotation,
- e.g. cdcdcd
+ e.g. cdcdcd. Use `None` for transparent background.
 
  Returns:
  A dictionary object representing the annotation.
@@ -98,10 +99,11 @@ def free_text(
  font_str = f"{font_str}{font} {font_size}"
  font_str = f"{font_str};text-align:left;color:#{font_color}"
 
- bg_color_str = ""
- for st in hex_to_rgb(border_color):
- bg_color_str = f"{bg_color_str}{st} "
- bg_color_str = f"{bg_color_str}rg"
+ default_appearance_string = ""
+ if border_color:
+ for st in hex_to_rgb(border_color):
+ default_appearance_string = f"{default_appearance_string}{st} "
+ default_appearance_string = f"{default_appearance_string}rg"
 
  free_text = DictionaryObject()
  free_text.update(
@@ -112,14 +114,21 @@ def free_text(
  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(background_color)]
- ),
+ NameObject("/DA"): TextStringObject(default_appearance_string),
  }
  )
+ if border_color is None:
+ # Border Style
+ free_text[NameObject("/BS")] = DictionaryObject(
+ {
+ # width of 0 means no border
+ NameObject("/W"): NumberObject(0)
+ }
+ )
+ if background_color is not None:
+ free_text[NameObject("/C")] = ArrayObject(
+ [FloatObject(n) for n in hex_to_rgb(background_color)]
+ )
  return free_text
 
  @staticmethod

tests/test_generic.py

@@ -720,8 +720,8 @@ def test_annotation_builder_free_text():
  italic=True,
  font_size="20pt",
  font_color="00ff00",
- border_color="0000ff",
- background_color="cdcdcd",
+ border_color=None,
+ background_color=None,
  )
  writer.add_annotation(0, free_text_annotation)