Source code

Download source archive ↓

src/pypdf/generic/_link.py

1# All rights reserved.
2#
3# Redistribution and use in source and binary forms, with or without
4# modification, are permitted provided that the following conditions are
5# met:
6#
7# * Redistributions of source code must retain the above copyright notice,
8# this list of conditions and the following disclaimer.
9# * Redistributions in binary form must reproduce the above copyright notice,
10# this list of conditions and the following disclaimer in the documentation
11# and/or other materials provided with the distribution.
12# * The name of the author may not be used to endorse or promote products
13# derived from this software without specific prior written permission.
14#
15# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
19# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25# POSSIBILITY OF SUCH DAMAGE.
26
27
28# This module contains code used by _writer.py to track links in pages
29# being added to the writer until the links can be resolved.
30
31from typing import TYPE_CHECKING, cast
32
33from .._utils import logger_warning
34from . import ArrayObject, DictionaryObject, IndirectObject, PdfObject, TextStringObject, is_null_or_none
35
36if TYPE_CHECKING:
37    from .._page import PageObject
38    from .._reader import PdfReader
39    from .._writer import PdfWriter
40
41
42class NamedReferenceLink:
43    """Named reference link being preserved until we can resolve it correctly."""
44
45    def __init__(self, reference: TextStringObject, source_pdf: "PdfReader") -> None:
46        """reference: TextStringObject with named reference"""
47        self._reference = reference
48        self._source_pdf = source_pdf
49
50    def find_referenced_page(self) -> IndirectObject | None:
51        destination = self._source_pdf.named_destinations.get(str(self._reference))
52        return destination.page if destination else None
53
54    def patch_reference(
55        self,
56        target_pdf: "PdfWriter",
57        new_page: IndirectObject,
58        *,
59        known_names: set[str] | None = None,
60    ) -> None:
61        """
62        Add the named destination of the link to the new page, unless it exists.
63
64        Args:
65            target_pdf: PdfWriter which the new link went into.
66            new_page: IndirectObject representing the new page in the target PDF.
67            known_names: Names of the named destinations of target_pdf, kept up to
68                date by this method. Collecting them from target_pdf is expensive,
69                thus callers patching many links should pass them.
70        """
71        name = str(self._reference)
72        if known_names is None:
73            known_names = set(target_pdf.named_destinations)
74        # point named destination in new PDF to the new page
75        if name not in known_names:
76            target_pdf.add_named_destination(name, new_page.page_number)
77            known_names.add(name)
78
79
80class DirectReferenceLink:
81    """Direct reference link being preserved until we can resolve it correctly."""
82
83    def __init__(self, reference: ArrayObject) -> None:
84        """reference: an ArrayObject whose first element is the Page indirect object"""
85        self._reference = reference
86
87    def find_referenced_page(self) -> IndirectObject | None:
88        if not self._reference:
89            return None
90        return cast(IndirectObject, self._reference[0])
91
92    def patch_reference(self, target_pdf: "PdfWriter", new_page: IndirectObject) -> None:
93        """target_pdf: PdfWriter which the new link went into"""
94        self._reference[0] = new_page
95
96
97ReferenceLink = NamedReferenceLink | DirectReferenceLink
98
99
100def extract_links(new_page: "PageObject", old_page: "PageObject") -> list[tuple[ReferenceLink, ReferenceLink]]:
101    """Extracts links from two pages on the assumption that the two pages are
102    the same. Produces one list of (new link, old link) tuples.
103
104    Non-link annotations are ignored before pairing to avoid dropping valid
105    links when one page includes additional non-link annotation entries.
106    """
107    new_annotations = new_page.get("/Annots", ArrayObject()).get_object()
108    old_annotations = old_page.get("/Annots", ArrayObject()).get_object()
109    if is_null_or_none(new_annotations):
110        new_annotations = ArrayObject()
111    if is_null_or_none(old_annotations):
112        old_annotations = ArrayObject()
113    if not isinstance(new_annotations, ArrayObject) or not isinstance(old_annotations, ArrayObject):
114        logger_warning(
115            "Expected annotation arrays: %(old_annotations)s %(new_annotations)s. Ignoring annotations.",
116            source=__name__,
117            old_annotations=old_annotations,
118            new_annotations=new_annotations,
119        )
120        return []
121    new_links = [
122        link
123        for annotation in new_annotations
124        if (link := _build_link(annotation, new_page)) is not None
125    ]
126    old_links = [
127        link
128        for annotation in old_annotations
129        if (link := _build_link(annotation, old_page)) is not None
130    ]
131
132    if len(new_links) != len(old_links):
133        logger_warning(
134            "Annotation sizes differ: %(old_count)d vs. %(new_count)d",
135            source=__name__,
136            old_count=len(old_links),
137            new_count=len(new_links),
138        )
139
140    return list(zip(new_links, old_links))
141
142
143def _build_link(indirect_object: IndirectObject, page: "PageObject") -> ReferenceLink | None:
144    src = cast("PdfReader", page.pdf)
145    link = cast(DictionaryObject, indirect_object.get_object())
146    if (not isinstance(link, DictionaryObject)) or link.get("/Subtype") != "/Link":
147        return None
148
149    if "/A" in link:
150        action = cast(DictionaryObject, link["/A"])
151        if action.get("/S") != "/GoTo":
152            return None
153
154        if "/D" not in action:
155            return None
156        return _create_link(action["/D"], src)
157
158    if "/Dest" in link:
159        return _create_link(link["/Dest"], src)
160
161    return None  # Nothing to do here
162
163
164def _create_link(reference: PdfObject, source_pdf: "PdfReader") -> ReferenceLink | None:
165    if isinstance(reference, TextStringObject):
166        return NamedReferenceLink(reference, source_pdf)
167    if isinstance(reference, ArrayObject):
168        return DirectReferenceLink(reference)
169    return None