Merge PR #1195

pdfplumber/page.py

@@ -13,6 +13,7 @@ from typing import (
     Union,
 )
 from unicodedata import normalize as normalize_unicode
+from warnings import warn
 
 from pdfminer.converter import PDFPageAggregator
 from pdfminer.layout import (
@@ -307,7 +308,15 @@ class Page(Container):
                     try:
                         extras[k] = v.decode("utf-8")
                     except UnicodeDecodeError:
-                        extras[k] = v.decode("utf-16")
+                        try:
+                            extras[k] = v.decode("utf-16")
+                        except UnicodeDecodeError:
+                            if self.pdf.raise_unicode_errors:
+                                raise
+                            warn(
+                                f"Could not decode {k} of annotation."
+                                f" {k} will be missing."
+                            )
 
             parsed = {
                 "page_number": self.page_number,

pdfplumber/pdf.py

@@ -35,6 +35,7 @@ class PDF(Container):
         password: Optional[str] = None,
         strict_metadata: bool = False,
         unicode_norm: Optional[Literal["NFC", "NFKC", "NFD", "NFKD"]] = None,
+        raise_unicode_errors: bool = True,
     ):
         self.stream = stream
         self.stream_is_external = stream_is_external
@@ -43,6 +44,7 @@ class PDF(Container):
         self.laparams = None if laparams is None else LAParams(**laparams)
         self.password = password
         self.unicode_norm = unicode_norm
+        self.raise_unicode_errors = raise_unicode_errors
 
         self.doc = PDFDocument(PDFParser(stream), password=password or "")
         self.rsrcmgr = PDFResourceManager()
@@ -76,6 +78,7 @@ class PDF(Container):
         repair: bool = False,
         gs_path: Optional[Union[str, pathlib.Path]] = None,
         repair_setting: T_repair_setting = "default",
+        raise_unicode_errors: bool = True,
     ) -> "PDF":
 
         stream: Union[BufferedReader, BytesIO]
@@ -107,6 +110,7 @@ class PDF(Container):
                 strict_metadata=strict_metadata,
                 unicode_norm=unicode_norm,
                 stream_is_external=stream_is_external,
+                raise_unicode_errors=raise_unicode_errors,
             )
 
         except PSException:

tests/test_issues.py

@@ -9,6 +9,8 @@ except ModuleNotFoundError:
     resource = None
 import unittest
 
+import pytest
+
 import pdfplumber
 
 logging.disable(logging.ERROR)
@@ -332,3 +334,26 @@ class Test(unittest.TestCase):
                 ["Bar10", "Bar11", "Bar12"],
                 ["", "", ""],
             ]
+
+    def test_pr_1195(self):
+        """
+        In certain scenarios, annotations may include invalid or extraneous
+        data that can obstruct the annotation processing workflow.  To mitigate
+        this, the raise_unicode_errors parameter in the PDF initializer and the
+        .open() method provides a configurable option to bypass these errors
+        and generate warnings instead, ensuring smoother handling of such
+        anomalies.
+
+        The following tests verifies the functionality of the
+        raise_unicode_errors parameter.
+        """
+        path = os.path.join(HERE, "pdfs/annotations-unicode-issues.pdf")
+        with pdfplumber.open(path) as pdf, pytest.raises(UnicodeDecodeError):
+            for _ in pdf.annots:
+                pass
+
+        with pdfplumber.open(path, raise_unicode_errors=False) as pdf, pytest.warns(
+            UserWarning
+        ):
+            for _ in pdf.annots:
+                pass