Propertly inserting alt_text when it is provided to FPDF.link - close #90 (#109)

+ Fixing unit tests assertion mechanism

Author: Lucas-C

.github/workflows/continuous-integration-workflow.yml

@@ -49,7 +49,7 @@ jobs:
           # Ensuring there is no `generate=True` left remaining in calls to assert_pdf_equal:
           grep -IRF generate=True test/ && exit 1
           # Executing all tests:
-          pytest
+          pytest -vv
           # Uploading coverage report to codecov.io
           bash <(curl -s https://codecov.io/bash)
       - name: Generating HTML documentation 🏗️

CHANGELOG.md

@@ -12,6 +12,8 @@ and [PEP 440](https://www.python.org/dev/peps/pep-0440/).
 - `FPDF.set_margin` : new method to set the document right, left, top & bottom margins to the same value
 - `FPDF.image` now accepts new optional `title` & `alt_text` parameters defining the image title
   and alternative text describing it, for accessibility purposes
+- `FPDF.link` now honor its `alt_text` optional parameter and this alternative text describing links
+  is now properly included in the resulting PDF document
 - the document language can be set using `FPDF.set_lang`
 ### Deprecated
 - `fpdf.FPDF_CACHE_MODE` & `fpdf.FPDF_CACHE_DIR` in favor of a configurable new `font_cache_dir` optional argument of the `fpdf.FPDF` constructor

docs/reference/link.md

@@ -1,33 +1,6 @@
-## link ##
+_cf._ https://pypi.org/project/fpdf2/fpdf/#fpdf.FPDF.dashed_line
 
-```python
-fpdf.link(x: float, y: float, w: float, h: float, link, alt_text = '')
-```
-
-### Description ###
-
-Puts a link on a rectangular area of the page. Text or image links are generally put via [cell](cell.md), [write](write.md) or [image](image.md), but this method can be useful for instance to define a clickable area inside an image.
-
-### Parameters ###
-
-x:
-> Abscissa of the upper-left corner of the rectangle.
-
-y:
-> Ordinate of the upper-left corner of the rectangle.
-
-w:
-> Width of the rectangle.
-
-h:
-> Height of the rectangle.
-
-link:
-> URL or identifier returned by [add_link](add_link.md).
-
-alt_text:
-> An optional string defining the link alternative text `Contents`
-
-### See also ###
-
-[add_link](add_link.md), [cell](cell.md), [write](write.md), [image](image.md).
+<script>
+// Migrating Markdown doc to docstrings - cf. https://github.com/PyFPDF/fpdf2/issues/31
+window.location = 'https://pypi.org/project/fpdf2/fpdf/#fpdf.FPDF.link'
+</script>

fpdf/fpdf.py

@@ -28,6 +28,7 @@
 from enum import IntEnum
 from functools import wraps
 from pathlib import Path
+from typing import NamedTuple, Optional
 
 from .errors import FPDFException, FPDFPageFormatException
 from .fonts import fpdf_charwidths
@@ -83,6 +84,15 @@ class DocumentState(IntEnum):
     CLOSED = 3  # EOF printed
 
 
+class PageLink(NamedTuple):
+    x: int
+    y: int
+    width: int
+    height: int
+    link: str
+    alt_text: Optional[str] = None
+
+
 # Disabling this check due to the "format" parameter below:
 # pylint: disable=redefined-builtin
 def get_page_format(format, k=None):
@@ -172,7 +182,7 @@ def __init__(
         self.font_files = {}  # array of font files
         self.diffs = {}  # array of encoding differences
         self.images = {}  # array of used images
-        self.page_links = {}  # array of links in pages
+        self.page_links = {}  # array of PageLink
         self.links = {}  # array of internal links
         self.in_footer = 0  # flag set when processing footer
         self.lasth = 0  # height of last cell printed
@@ -191,7 +201,7 @@ def __init__(
         self.angle = 0  # used by deprecated method: rotate()
         self.font_cache_dir = font_cache_dir
         self._marked_contents = []  # list of MarkedContent
-        self._struct_parents_id_per_page = {}  # {page_object_id -> StructParents ID}
+        self._struct_parents_id_per_page = {}  # {page_object_id -> StructParent(s) ID}
         # Only set if a Structure Tree is added to the document:
         self._struct_tree_root_obj_id = None
 
@@ -927,13 +937,33 @@ def set_link(self, link, y=0, page=-1):
 
         self.links[link] = [page, y]
 
-    def link(self, x, y, w, h, link, alt_text=""):
-        """Put a link on the page"""
+    def link(self, x, y, w, h, link, alt_text=None):
+        """
+        Puts a link on a rectangular area of the page.
+        Text or image links are generally put via [cell](#fpdf.FPDF.cell),
+        [write](#fpdf.FPDF.write) or [image](#fpdf.FPDF.image),
+        but this method can be useful for instance to define a clickable area inside an image.
+
+        Args:
+            x (int): horizontal position (from the left) to the left side of the link rectangle
+            y (int): vertical position (from the top) to the bottom side of the link rectangle
+            w (int): width of the link rectangle
+            h (int): width of the link rectangle
+            link (str): either an URL or a integer returned by `add_link`, defining an internal link to a page
+            alt_text (str): optional textual description of the link, for accessibility purposes
+        """
         if self.page not in self.page_links:
             self.page_links[self.page] = []
-        self.page_links[self.page] += [
-            (x * self.k, self.h_pt - y * self.k, w * self.k, h * self.k, link, alt_text)
-        ]
+        self.page_links[self.page].append(
+            PageLink(
+                x * self.k,
+                self.h_pt - y * self.k,
+                w * self.k,
+                h * self.k,
+                link,
+                alt_text,
+            )
+        )
 
     @check_page
     def text(self, x, y, txt=""):
@@ -1559,9 +1589,9 @@ def image(
             type (str): [**DEPRECATED**] unused, will be removed in a later version.
             link (str): optional link to add on the image, internal
                 (identifier returned by `add_link`) or external URL.
-            title (str): optional
+            title (str): optional. Currently, never seem rendered by PDF readers.
             alt_text (str): optional alternative text describing the image,
-                for accessibility purposes
+                for accessibility purposes. Displayed by some PDF readers on hover.
         """
         if type:
             warnings.warn(
@@ -1615,20 +1645,25 @@ def image(
     @contextmanager
     def _marked_sequence(self, **kwargs):
         page_object_id = self._current_page_object_id()
-        struct_parents_id = self._struct_parents_id_per_page.get(page_object_id)
-        if struct_parents_id is None:
-            struct_parents_id = len(self._struct_parents_id_per_page)
-            self._struct_parents_id_per_page[page_object_id] = struct_parents_id
         mcid = sum(
             1 for mc in self._marked_contents if mc.page_object_id == page_object_id
         )
-        self._marked_contents.append(
-            MarkedContent(page_object_id, struct_parents_id, mcid, **kwargs)
+        self._add_marked_content(
+            page_object_id, struct_type="/Figure", mcid=mcid, **kwargs
         )
         self._out(f"/P <</MCID {mcid}>> BDC")
         yield
         self._out("EMC")
 
+    def _add_marked_content(self, page_object_id, **kwargs):
+        struct_parents_id = self._struct_parents_id_per_page.get(page_object_id)
+        if struct_parents_id is None:
+            struct_parents_id = len(self._struct_parents_id_per_page)
+            self._struct_parents_id_per_page[page_object_id] = struct_parents_id
+        marked_content = MarkedContent(page_object_id, struct_parents_id, **kwargs)
+        self._marked_contents.append(marked_content)
+        return marked_content
+
     def _current_page_object_id(self):
         # Predictable given that _putpages is invoked first in _enddoc:
         return 2 * self.page + 1
@@ -1758,8 +1793,8 @@ def _putpages(self):
                 for pl in self.page_links[n]:
                     # first four things in 'link' list are coordinates?
                     rect = (
-                        f"{pl[0]:.2f} {pl[1]:.2f} "
-                        f"{pl[0] + pl[2]:.2f} {pl[1] - pl[3]:.2f}"
+                        f"{pl.x:.2f} {pl.y:.2f} "
+                        f"{pl.x + pl.width:.2f} {pl.y - pl.height:.2f}"
                     )
 
                     # start the annotation entry
@@ -1772,24 +1807,30 @@ def _putpages(self):
                         f"/F 4"
                     )
 
-                    # HTML ending of annotation entry
-                    if isinstance(pl[4], str):
-                        annots += f"/A <</S /URI /URI {enclose_in_parens(pl[4])}>>>>"
+                    if pl.alt_text is not None:
+                        # Note: the spec indicates that a /StructParent could be added **inside* this /Annot,
+                        # but tests with Adobe Acrobat Reader reveal that the page /StructParents inserted below
+                        # is enough to link the marked content in the hierarchy tree with this annotation link.
+                        self._add_marked_content(
+                            self.n, struct_type="/Link", alt_text=pl.alt_text
+                        )
 
-                    # Dest type ending of annotation entry
-                    else:
-                        assert pl[4] in self.links, (
+                    # HTML ending of annotation entry
+                    if isinstance(pl.link, str):
+                        annots += f"/A <</S /URI /URI {enclose_in_parens(pl.link)}>>"
+                    else:  # Dest type ending of annotation entry
+                        assert pl.link in self.links, (
                             f"Page {n} has a link with an invalid index: "
-                            f"{pl[4]} (doc #links={len(self.links)})"
+                            f"{pl.link} (doc #links={len(self.links)})"
                         )
-                        l = self.links[pl[4]]
-                        # if l[0] in self.orientation_changes: h = w_pt
-                        # else:                                h = h_pt
+                        link = self.links[pl.link]
+                        # if link[0] in self.orientation_changes: h = w_pt
+                        # else:                                   h = h_pt
                         annots += (
-                            f"/Dest [{1 + 2 * l[0]} 0 R /XYZ 0 "
-                            f"{h_pt - l[1] * self.k:.2f} null]>>"
+                            f"/Dest [{1 + 2 * link[0]} 0 R /XYZ 0 "
+                            f"{h_pt - link[1] * self.k:.2f} null]"
                         )
-
+                    annots += ">>"
                 # End links list
                 self._out(f"{annots}]")
             if self.pdf_version > "1.3":

fpdf/recorder.py

@@ -22,7 +22,7 @@ class FPDFRecorder:
 
     def __init__(self, pdf, accept_page_break=True):
         self._pdf = pdf
-        self._initial = deepcopy(pdf.__dict__)
+        self._initial = deepcopy(self._pdf.__dict__)
         self._calls = []
         if not accept_page_break:
             self.accept_page_break = False
@@ -35,6 +35,7 @@ def __getattr__(self, name):
 
     def rewind(self):
         self._pdf.__dict__ = self._initial
+        self._initial = deepcopy(self._pdf.__dict__)
 
     def replay(self):
         for call in self._calls:

fpdf/structure_tree.py

@@ -18,7 +18,8 @@
 class MarkedContent(NamedTuple):
     page_object_id: int  # refers to the first page displaying this marked content
     struct_parents_id: int
-    mcid: int
+    struct_type: str
+    mcid: Optional[int] = None
     title: Optional[str] = None
     alt_text: Optional[str] = None
 
@@ -113,7 +114,7 @@ def serialize(self):
         elif all(isinstance(elem, int) for elem in self):
             serialized_elems = " ".join(map(str, self))
         else:
-            raise NotImplementedError
+            raise NotImplementedError(f"PDFArray.serialize with self={self}")
         return f"[{serialized_elems}]"
 
 
@@ -206,9 +207,9 @@ def __init__(self, marked_contents=()):
     def add_marked_content(self, marked_content):
         page = PDFObject(marked_content.page_object_id)
         struct_elem = StructElem(
-            struct_type="/Figure",
+            struct_type=marked_content.struct_type,
             parent=self.doc_struct_elem,
-            kids=[marked_content.mcid],
+            kids=[] if marked_content.mcid is None else [marked_content.mcid],
             page=page,
             title=marked_content.title,
             alt=marked_content.alt_text,

test/alias_nb_pages.pdf

@@ -1,7 +1,7 @@
 from pathlib import Path
 
 from fpdf import FPDF
-from test.utilities import assert_pdf_equal
+from test.conftest import assert_pdf_equal
 
 HERE = Path(__file__).resolve().parent
 

test/barcodes/test_barcodes.py

@@ -1,7 +1,7 @@
 from pathlib import Path
 
 import fpdf
-from test.utilities import assert_pdf_equal
+from test.conftest import assert_pdf_equal
 
 TEXT_SIZE, SPACING = 36, 1.15
 LINE_HEIGHT = TEXT_SIZE * SPACING

test/catalog-layout-continuous.pdf

@@ -1,7 +1,7 @@
 from pathlib import Path
 
 import fpdf
-from test.utilities import assert_pdf_equal
+from test.conftest import assert_pdf_equal
 
 TEXT_SIZE, SPACING = 36, 1.15
 LINE_HEIGHT = TEXT_SIZE * SPACING