Source code

Download source archive ↓

src/pypdf/generic/_files.py

1from __future__ import annotations
2
3import bisect
4from functools import cached_property
5from typing import TYPE_CHECKING, cast
6
7from pypdf._utils import format_iso8824_date, logger_warning, parse_iso8824_date
8from pypdf.constants import CatalogAttributes, FileSpecificationDictionaryEntries, PageAttributes
9from pypdf.errors import PdfReadError, PyPdfError
10from pypdf.generic import (
11    ArrayObject,
12    ByteStringObject,
13    DecodedStreamObject,
14    DictionaryObject,
15    NameObject,
16    NullObject,
17    NumberObject,
18    StreamObject,
19    TextStringObject,
20    is_null_or_none,
21)
22
23if TYPE_CHECKING:
24    import datetime
25    from collections.abc import Iterator
26
27    from pypdf._writer import PdfWriter
28
29
30class EmbeddedFile:
31    """
32    Container holding the information on an embedded file.
33
34    Attributes are evaluated lazily if possible.
35
36    Further information on embedded files can be found in section 7.11 of the PDF 2.0 specification.
37    """
38    def __init__(self, name: str, pdf_object: DictionaryObject, parent: ArrayObject | None = None) -> None:
39        """
40        Args:
41            name: The (primary) name as provided in the name tree.
42            pdf_object: The corresponding PDF object to allow retrieving further data.
43            parent: The parent list.
44        """
45        self._name = name
46        self.pdf_object = pdf_object
47        self._parent = parent
48
49    @property
50    def name(self) -> str:
51        """
52        The (primary) name of the embedded file as provided in the name tree.
53
54        .. warning::
55
56            This value can contain arbitrary characters. Please make sure to sanitize it before
57            using it to write the file content to the disk for example.
58        """
59        return self._name
60
61    @classmethod
62    def _create_new(cls, writer: PdfWriter, name: str, content: str | bytes) -> EmbeddedFile:
63        """
64        Create a new embedded file and add it to the PdfWriter.
65
66        Args:
67            writer: The PdfWriter instance to add the embedded file to.
68            name: The filename to display.
69            content: The data in the file.
70
71        Returns:
72            EmbeddedFile instance for the newly created embedded file.
73        """
74        # Convert string content to bytes if needed
75        if isinstance(content, str):
76            content = content.encode("latin-1")
77
78        # Create the file entry (the actual embedded file stream)
79        file_entry = DecodedStreamObject()
80        file_entry.set_data(content)
81        file_entry.update({NameObject(PageAttributes.TYPE): NameObject("/EmbeddedFile")})
82
83        # Create the /EF entry
84        ef_entry = DictionaryObject()
85        ef_entry.update({NameObject("/F"): writer._add_object(file_entry)})
86
87        # Create the filespec dictionary
88        from pypdf.generic import create_string_object  # noqa: PLC0415
89        filespec = DictionaryObject()
90        filespec_reference = writer._add_object(filespec)
91        name_object = cast(TextStringObject, create_string_object(name))
92        filespec.update(
93            {
94                NameObject(PageAttributes.TYPE): NameObject("/Filespec"),
95                NameObject(FileSpecificationDictionaryEntries.F): name_object,
96                NameObject(FileSpecificationDictionaryEntries.EF): ef_entry,
97            }
98        )
99
100        # Add the name and filespec to the names array.
101        # We use the inverse order for insertion, as this allows us to re-use the
102        # same index.
103        names_array = cls._get_names_array(writer)
104        insertion_index = cls._get_insertion_index(names_array, name_object)
105        names_array.insert(insertion_index, filespec_reference)
106        names_array.insert(insertion_index, name_object)
107
108        # Return an EmbeddedFile instance
109        return cls(name=name, pdf_object=filespec, parent=names_array)
110
111    @classmethod
112    def _get_names_array(cls, writer: PdfWriter) -> ArrayObject:
113        """Get the names array for embedded files, possibly creating and flattening it."""
114        if CatalogAttributes.NAMES not in writer.root_object:
115            # Add the /Names entry to the catalog.
116            writer.root_object[NameObject(CatalogAttributes.NAMES)] = writer._add_object(DictionaryObject())
117
118        names_dict = cast(DictionaryObject, writer.root_object[CatalogAttributes.NAMES])
119        if "/EmbeddedFiles" not in names_dict:
120            # We do not yet have an entry for embedded files. Create and return it.
121            names = ArrayObject()
122            embedded_files_names_dictionary = DictionaryObject(
123                {NameObject(CatalogAttributes.NAMES): names}
124            )
125            names_dict[NameObject("/EmbeddedFiles")] = writer._add_object(embedded_files_names_dictionary)
126            return names
127
128        # We have an existing embedded files entry.
129        embedded_files_names_tree = cast(DictionaryObject, names_dict["/EmbeddedFiles"])
130        if "/Names" in embedded_files_names_tree:
131            # Simple case: We already have a flat list.
132            return cast(ArrayObject, embedded_files_names_tree[NameObject(CatalogAttributes.NAMES)])
133        if "/Kids" not in embedded_files_names_tree:
134            # Invalid case: This is no name tree.
135            raise PdfReadError("Got neither Names nor Kids in embedded files tree.")
136
137        # Complex case: Convert a /Kids-based name tree to a /Names-based one.
138        # /Name-based ones are much easier to handle and allow us to simplify the
139        # actual insertion logic by only having to consider one case.
140        names = ArrayObject()
141        kids = cast(ArrayObject, embedded_files_names_tree["/Kids"].get_object())
142        embedded_files_names_dictionary = DictionaryObject(
143            {NameObject(CatalogAttributes.NAMES): names}
144        )
145        names_dict[NameObject("/EmbeddedFiles")] = writer._add_object(embedded_files_names_dictionary)
146        for kid in kids:
147            # Write the flattened file entries. As we do not change the actual files,
148            # this should not have any impact on references to them.
149            # There might be further (nested) kids here.
150            # Wait for an example before evaluating an implementation.
151            for name in kid.get_object().get("/Names", []):
152                names.append(name)
153        return names
154
155    @classmethod
156    def _get_insertion_index(cls, names_array: ArrayObject, name: str) -> int:
157        keys = [names_array[i].encode("utf-8") for i in range(0, len(names_array), 2)]
158        name_bytes = name.encode("utf-8")
159
160        start = bisect.bisect_left(keys, name_bytes)
161        end = bisect.bisect_right(keys, name_bytes)
162
163        if start != end:
164            return end * 2
165        if start == 0:
166            return 0
167        if start == (key_count := len(keys)):
168            return key_count * 2
169        return end * 2
170
171    @property
172    def alternative_name(self) -> str | None:
173        """
174        Retrieve the alternative name (as per the file specification dictionary).
175
176        .. warning::
177
178            This value can contain arbitrary characters. Please make sure to sanitize it before
179            using it to write the file content to the disk for example.
180        """
181        for key in [FileSpecificationDictionaryEntries.UF, FileSpecificationDictionaryEntries.F]:
182            # PDF 2.0 reference, table 43:
183            #   > A PDF reader shall use the value of the UF key, when present, instead of the F key.
184            if key in self.pdf_object:
185                value = self.pdf_object[key].get_object()
186                if not is_null_or_none(value):
187                    return cast(str, value)
188        return None
189
190    @alternative_name.setter
191    def alternative_name(self, value: TextStringObject | None) -> None:
192        """Set the alternative name (as per the file specification dictionary)."""
193        if value is None:
194            if FileSpecificationDictionaryEntries.UF in self.pdf_object:
195                self.pdf_object[NameObject(FileSpecificationDictionaryEntries.UF)] = NullObject()
196            if FileSpecificationDictionaryEntries.F in self.pdf_object:
197                self.pdf_object[NameObject(FileSpecificationDictionaryEntries.F)] = NullObject()
198        else:
199            self.pdf_object[NameObject(FileSpecificationDictionaryEntries.UF)] = value
200            self.pdf_object[NameObject(FileSpecificationDictionaryEntries.F)] = value
201
202    @property
203    def description(self) -> str | None:
204        """Retrieve the description."""
205        value = self.pdf_object.get(FileSpecificationDictionaryEntries.DESC)
206        if is_null_or_none(value):
207            return None
208        return value
209
210    @description.setter
211    def description(self, value: TextStringObject | None) -> None:
212        """Set the description."""
213        if value is None:
214            self.pdf_object[NameObject(FileSpecificationDictionaryEntries.DESC)] = NullObject()
215        else:
216            self.pdf_object[NameObject(FileSpecificationDictionaryEntries.DESC)] = value
217
218    @property
219    def associated_file_relationship(self) -> str:
220        """Retrieve the relationship of the referring document to this embedded file."""
221        return cast(
222            NameObject,
223            self.pdf_object.get("/AFRelationship", NameObject("/Unspecified")),
224        )
225
226    @associated_file_relationship.setter
227    def associated_file_relationship(self, value: NameObject) -> None:
228        """Set the relationship of the referring document to this embedded file."""
229        self.pdf_object[NameObject("/AFRelationship")] = value
230
231    @property
232    def _embedded_file(self) -> StreamObject:
233        """Retrieve the actual embedded file stream."""
234        if "/EF" not in self.pdf_object:
235            raise PdfReadError(f"/EF entry not found: {self.pdf_object}")
236        ef = cast(DictionaryObject, self.pdf_object["/EF"])
237        for key in [FileSpecificationDictionaryEntries.UF, FileSpecificationDictionaryEntries.F]:
238            if key in ef:
239                return cast(StreamObject, ef[key].get_object())
240        raise PdfReadError(f"No /(U)F key found in file dictionary: {ef}")
241
242    @property
243    def _params(self) -> DictionaryObject:
244        """Retrieve the file-specific parameters."""
245        return cast(DictionaryObject, self._embedded_file.get("/Params", DictionaryObject()).get_object())
246
247    @cached_property
248    def _ensure_params(self) -> DictionaryObject:
249        """Ensure the /Params dictionary exists and return it."""
250        embedded_file = self._embedded_file
251        if "/Params" not in embedded_file:
252            embedded_file[NameObject("/Params")] = DictionaryObject()
253        return cast(DictionaryObject, embedded_file["/Params"])
254
255    @property
256    def subtype(self) -> str | None:
257        """Retrieve the subtype. This is a MIME media type, prefixed by a slash."""
258        value = self._embedded_file.get("/Subtype")
259        if is_null_or_none(value):
260            return None
261        return value
262
263    @subtype.setter
264    def subtype(self, value: NameObject | None) -> None:
265        """Set the subtype. This should be a MIME media type, prefixed by a slash."""
266        embedded_file = self._embedded_file
267        if value is None:
268            embedded_file[NameObject("/Subtype")] = NullObject()
269        else:
270            embedded_file[NameObject("/Subtype")] = value
271
272    @property
273    def content(self) -> bytes:
274        """Retrieve the actual file content."""
275        return self._embedded_file.get_data()
276
277    @content.setter
278    def content(self, value: str | bytes) -> None:
279        """Set the file content."""
280        if isinstance(value, str):
281            value = value.encode("latin-1")
282        self._embedded_file.set_data(value)
283
284    @property
285    def size(self) -> int | None:
286        """Retrieve the size of the uncompressed file in bytes."""
287        value = self._params.get("/Size")
288        if is_null_or_none(value):
289            return None
290        return value
291
292    @size.setter
293    def size(self, value: NumberObject | None) -> None:
294        """Set the size of the uncompressed file in bytes."""
295        params = self._ensure_params
296        if value is None:
297            params[NameObject("/Size")] = NullObject()
298        else:
299            params[NameObject("/Size")] = value
300
301    @property
302    def creation_date(self) -> datetime.datetime | None:
303        """Retrieve the file creation datetime."""
304        return parse_iso8824_date(self._params.get("/CreationDate"))
305
306    @creation_date.setter
307    def creation_date(self, value: datetime.datetime | None) -> None:
308        """Set the file creation datetime."""
309        params = self._ensure_params
310        if value is None:
311            params[NameObject("/CreationDate")] = NullObject()
312        else:
313            date_str = format_iso8824_date(value)
314            params[NameObject("/CreationDate")] = TextStringObject(date_str)
315
316    @property
317    def modification_date(self) -> datetime.datetime | None:
318        """Retrieve the datetime of the last file modification."""
319        return parse_iso8824_date(self._params.get("/ModDate"))
320
321    @modification_date.setter
322    def modification_date(self, value: datetime.datetime | None) -> None:
323        """Set the datetime of the last file modification."""
324        params = self._ensure_params
325        if value is None:
326            params[NameObject("/ModDate")] = NullObject()
327        else:
328            date_str = format_iso8824_date(value)
329            params[NameObject("/ModDate")] = TextStringObject(date_str)
330
331    @property
332    def checksum(self) -> bytes | None:
333        """Retrieve the MD5 checksum of the (uncompressed) file."""
334        value = self._params.get("/CheckSum")
335        if is_null_or_none(value):
336            return None
337        return value
338
339    @checksum.setter
340    def checksum(self, value: ByteStringObject | None) -> None:
341        """Set the MD5 checksum of the (uncompressed) file."""
342        params = self._ensure_params
343        if value is None:
344            params[NameObject("/CheckSum")] = NullObject()
345        else:
346            params[NameObject("/CheckSum")] = value
347
348    @property
349    def _names(self) -> Iterator[str]:
350        yield self.name
351        if self.alternative_name is not None and self.alternative_name != self.name:
352            yield self.alternative_name
353
354    def delete(self) -> None:
355        """Delete the file from the document."""
356        if not self._parent:
357            raise PyPdfError("Parent required to delete file from document.")
358        if self.pdf_object in self._parent:
359            index = self._parent.index(self.pdf_object)
360        elif (
361                (indirect_reference := getattr(self.pdf_object, "indirect_reference", None)) is not None
362                and indirect_reference in self._parent
363        ):
364            index = self._parent.index(indirect_reference)
365        else:
366            raise PyPdfError("File not found in parent object.")
367        self._parent.pop(index)  # Reference.
368        self._parent.pop(index - 1)  # Name.
369        self.pdf_object = DictionaryObject()  # Invalidate.
370
371    def __repr__(self) -> str:
372        return f"<{self.__class__.__name__} name={self.name!r}>"
373
374    @staticmethod
375    def _report_malformed(message: str, strict: bool) -> None:
376        """Raise an exception in strict mode, warn otherwise."""
377        if strict:
378            raise PdfReadError(message)
379        logger_warning(message, source=__name__)
380
381    @classmethod
382    def _load_from_names(cls, names: ArrayObject, strict: bool = False) -> Iterator[EmbeddedFile]:
383        """
384        Convert the given name tree into class instances.
385
386        Args:
387            names: The name tree to load the data from.
388            strict: Whether to raise an exception on a file specification that is not a dictionary
389                instead of issuing a warning and skipping it.
390
391        Returns:
392            Iterable of class instances for the files found.
393        """
394        # This is a name tree of the format [name_1, reference_1, name_2, reference_2, ...]
395        for i, name in enumerate(names):
396            if not isinstance(name, str):
397                # Skip plain strings and retrieve them as `direct_name` by index.
398                file_dictionary = name.get_object()
399                if isinstance(file_dictionary, NullObject):
400                    # A null value is equivalent to an omitted entry.
401                    continue
402                if not isinstance(file_dictionary, DictionaryObject):
403                    cls._report_malformed(
404                        f"Embedded file specification is not a dictionary: {file_dictionary}", strict=strict
405                    )
406                    continue
407                direct_name = names[i - 1].get_object()
408                yield EmbeddedFile(name=direct_name, pdf_object=file_dictionary, parent=names)
409
410    @classmethod
411    def _load(cls, catalog: DictionaryObject, strict: bool = False) -> Iterator[EmbeddedFile]:
412        """
413        Load the embedded files for the given document catalog.
414
415        This method and its signature are considered internal API and thus not exposed publicly for now.
416
417        Args:
418            catalog: The document catalog to load from.
419            strict: Whether to raise an exception on malformed name trees
420                instead of issuing a warning and skipping them.
421
422        Returns:
423            Iterable of class instances for the files found.
424        """
425        if "/Names" not in catalog:
426            return
427        names = catalog["/Names"]
428        if isinstance(names, NullObject):
429            # A null value is equivalent to an omitted entry.
430            return
431        if not isinstance(names, DictionaryObject):
432            cls._report_malformed(f"Names tree is not a dictionary: {names}", strict=strict)
433            return
434        if "/EmbeddedFiles" not in names:
435            return
436        container = names["/EmbeddedFiles"]
437        if isinstance(container, NullObject):
438            return
439        if not isinstance(container, DictionaryObject):
440            cls._report_malformed(f"Embedded files entry is not a dictionary: {container}", strict=strict)
441            return
442
443        if "/Kids" in container:
444            kids = container["/Kids"].get_object()
445            if isinstance(kids, NullObject):
446                kids = ArrayObject()
447            elif not isinstance(kids, ArrayObject):
448                cls._report_malformed(f"Embedded files /Kids is not an array: {kids}", strict=strict)
449                return
450            for kid in kids:
451                # There might be further (nested) kids here.
452                # Wait for an example before evaluating an implementation.
453                kid = kid.get_object()
454                if not isinstance(kid, DictionaryObject):
455                    cls._report_malformed(f"Embedded files kid is not a dictionary: {kid}", strict=strict)
456                    continue
457                if "/Names" not in kid:
458                    continue
459                kid_names = kid["/Names"].get_object()
460                if isinstance(kid_names, NullObject):
461                    continue
462                if not isinstance(kid_names, ArrayObject):
463                    cls._report_malformed(f"Embedded files name list is not an array: {kid_names}", strict=strict)
464                    continue
465                yield from cls._load_from_names(kid_names, strict=strict)
466        if "/Names" in container:
467            container_names = container["/Names"].get_object()
468            if isinstance(container_names, NullObject):
469                return
470            if not isinstance(container_names, ArrayObject):
471                cls._report_malformed(f"Embedded files name list is not an array: {container_names}", strict=strict)
472                return
473            yield from cls._load_from_names(container_names, strict=strict)