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)