src/pypdf/generic/_base.py
1# Copyright (c) 2006, Mathieu Fenniak
2# All rights reserved.
3#
4# Redistribution and use in source and binary forms, with or without
5# modification, are permitted provided that the following conditions are
6# met:
7#
8# * Redistributions of source code must retain the above copyright notice,
9# this list of conditions and the following disclaimer.
10# * Redistributions in binary form must reproduce the above copyright notice,
11# this list of conditions and the following disclaimer in the documentation
12# and/or other materials provided with the distribution.
13# * The name of the author may not be used to endorse or promote products
14# derived from this software without specific prior written permission.
15#
16# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26# POSSIBILITY OF SUCH DAMAGE.
27import binascii
28import codecs
29import hashlib
30import re
31import sys
32from collections.abc import Callable, Sequence
33from math import log10
34from struct import iter_unpack
35from typing import Any, ClassVar, Optional, TypeGuard, Union, cast
36
37if sys.version_info >= (3, 11):
38 from typing import Self
39else:
40 from typing_extensions import Self
41
42from .._codecs import _pdfdoc_encoding_rev
43from .._protocols import PdfWriterProtocol
44from .._utils import (
45 WHITESPACES,
46 StreamType,
47 logger_warning,
48 read_non_whitespace,
49 read_until_regex,
50)
51from ..errors import STREAM_TRUNCATED_PREMATURELY, PdfReadError, PdfStreamError
52
53__author__ = "Mathieu Fenniak"
54__author_email__ = "biziqe@mathieu.fenniak.net"
55
56
57class PdfObject:
58 # function for calculating a hash value
59 hash_func: Callable[..., "hashlib._Hash"] = hashlib.sha1
60 indirect_reference: Optional["IndirectObject"]
61
62 def hash_bin(self) -> int:
63 """
64 Used to detect modified object.
65
66 Returns:
67 Hash considering type and value.
68
69 """
70 raise NotImplementedError(
71 f"{self.__class__.__name__} does not implement .hash_bin() so far"
72 )
73
74 def hash_value_data(self) -> bytes:
75 return f"{self}".encode()
76
77 def hash_value(self) -> bytes:
78 return (
79 f"{self.__class__.__name__}:"
80 f"{self.hash_func(self.hash_value_data()).hexdigest()}"
81 ).encode()
82
83 def replicate(
84 self,
85 pdf_dest: PdfWriterProtocol,
86 ) -> "PdfObject":
87 """
88 Clone object into pdf_dest (PdfWriterProtocol which is an interface for PdfWriter)
89 without ensuring links. This is used in clone_document_from_root with incremental = True.
90
91 Args:
92 pdf_dest: Target to clone to.
93
94 Returns:
95 The cloned PdfObject
96
97 """
98 return self.clone(pdf_dest)
99
100 def clone(
101 self,
102 pdf_dest: PdfWriterProtocol,
103 force_duplicate: bool = False,
104 ignore_fields: Sequence[str | int] | None = (),
105 ) -> "PdfObject":
106 """
107 Clone object into pdf_dest (PdfWriterProtocol which is an interface for PdfWriter).
108
109 By default, this method will call ``_reference_clone`` (see ``_reference``).
110
111
112 Args:
113 pdf_dest: Target to clone to.
114 force_duplicate: By default, if the object has already been cloned and referenced,
115 the copy will be returned; when ``True``, a new copy will be created.
116 (Default value = ``False``)
117 ignore_fields: List/tuple of field names (for dictionaries) that will be ignored
118 during cloning (applies to children duplication as well). If fields are to be
119 considered for a limited number of levels, you have to add it as integer, for
120 example ``[1,"/B","/TOTO"]`` means that ``"/B"`` will be ignored at the first
121 level only but ``"/TOTO"`` on all levels.
122
123 Returns:
124 The cloned PdfObject
125
126 """
127 raise NotImplementedError(
128 f"{self.__class__.__name__} does not implement .clone so far"
129 )
130
131 def _reference_clone(
132 self, clone: "PdfObject", pdf_dest: PdfWriterProtocol, force_duplicate: bool = False
133 ) -> "PdfObject":
134 """
135 Reference the object within the _objects of pdf_dest only if
136 indirect_reference attribute exists (which means the objects was
137 already identified in xref/xobjstm) if object has been already
138 referenced do nothing.
139
140 Args:
141 clone:
142 pdf_dest:
143
144 Returns:
145 The clone
146
147 """
148 if not hasattr(self, "indirect_reference"):
149 # Direct object: nothing to reference.
150 # Returning early is much faster than handling the exceptions below.
151 return clone
152 try:
153 if (
154 not force_duplicate
155 and clone.indirect_reference is not None
156 and clone.indirect_reference.pdf == pdf_dest
157 ):
158 return clone
159 except MemoryError: # pragma: no cover # TODO: BLE001
160 raise
161 except Exception:
162 pass
163 ind = self.indirect_reference
164 if (
165 pdf_dest.incremental
166 and ind is not None
167 and ind.pdf == pdf_dest._reader
168 and ind.idnum <= len(pdf_dest._objects)
169 ):
170 i = ind.idnum
171 else:
172 i = len(pdf_dest._objects) + 1
173 if ind is not None:
174 if id(ind.pdf) not in pdf_dest._id_translated:
175 pdf_dest._id_translated[id(ind.pdf)] = {}
176 pdf_dest._id_translated[id(ind.pdf)]["PreventGC"] = ind.pdf
177 if (
178 not force_duplicate
179 and ind.idnum in pdf_dest._id_translated[id(ind.pdf)]
180 ):
181 obj = pdf_dest.get_object(
182 pdf_dest._id_translated[id(ind.pdf)][ind.idnum]
183 )
184 assert isinstance(obj, PdfObject), "mypy"
185 return obj
186 pdf_dest._id_translated[id(ind.pdf)][ind.idnum] = i
187 try:
188 pdf_dest._objects[i - 1] = clone
189 except IndexError:
190 pdf_dest._objects.append(clone)
191 i = len(pdf_dest._objects)
192 clone.indirect_reference = IndirectObject(i, 0, pdf_dest)
193 return clone
194
195 def get_object(self) -> Optional["PdfObject"]:
196 """Resolve indirect references."""
197 return self
198
199 def write_to_stream(self, stream: StreamType) -> None:
200 raise NotImplementedError
201
202
203class NullObject(PdfObject):
204 def clone(
205 self,
206 pdf_dest: PdfWriterProtocol,
207 force_duplicate: bool = False,
208 ignore_fields: Sequence[str | int] | None = (),
209 ) -> "NullObject":
210 """Clone object into pdf_dest."""
211 if not hasattr(self, "indirect_reference"):
212 # Direct object: shortcut, as some arrays consist mostly of nulls
213 return NullObject()
214 return cast(
215 "NullObject", self._reference_clone(NullObject(), pdf_dest, force_duplicate)
216 )
217
218 def hash_bin(self) -> int:
219 """
220 Used to detect modified object.
221
222 Returns:
223 Hash considering type and value.
224
225 """
226 return hash((self.__class__,))
227
228 def write_to_stream(self, stream: StreamType) -> None:
229 stream.write(b"null")
230
231 @staticmethod
232 def read_from_stream(stream: StreamType) -> "NullObject":
233 nulltxt = stream.read(4)
234 if nulltxt != b"null":
235 raise PdfReadError("Could not read Null object")
236 return NullObject()
237
238 def __repr__(self) -> str:
239 return "NullObject"
240
241 def __eq__(self, other: object) -> bool:
242 return isinstance(other, NullObject)
243
244 def __hash__(self) -> int:
245 return self.hash_bin()
246
247
248class BooleanObject(PdfObject):
249 value: bool
250
251 def __init__(self, value: Any) -> None:
252 self.value = value
253
254 def clone(
255 self,
256 pdf_dest: PdfWriterProtocol,
257 force_duplicate: bool = False,
258 ignore_fields: Sequence[str | int] | None = (),
259 ) -> "BooleanObject":
260 """Clone object into pdf_dest."""
261 return cast(
262 "BooleanObject",
263 self._reference_clone(BooleanObject(self.value), pdf_dest, force_duplicate),
264 )
265
266 def hash_bin(self) -> int:
267 """
268 Used to detect modified object.
269
270 Returns:
271 Hash considering type and value.
272
273 """
274 return hash((self.__class__, self.value))
275
276 def __eq__(self, o: object, /) -> bool:
277 if isinstance(o, BooleanObject):
278 return self.value == o.value
279 if isinstance(o, bool):
280 return self.value == o
281 return False
282
283 def __hash__(self) -> int:
284 return self.hash_bin()
285
286 def __repr__(self) -> str:
287 return "True" if self.value else "False"
288
289 def write_to_stream(self, stream: StreamType) -> None:
290 if self.value:
291 stream.write(b"true")
292 else:
293 stream.write(b"false")
294
295 @staticmethod
296 def read_from_stream(stream: StreamType) -> "BooleanObject":
297 word = stream.read(4)
298 if word == b"true":
299 return BooleanObject(True)
300 if word == b"fals":
301 stream.read(1)
302 return BooleanObject(False)
303 raise PdfReadError("Could not read Boolean object")
304
305
306class IndirectObject(PdfObject):
307 _MAXIMUM_PART_LENGTH = 64
308
309 def __init__(self, idnum: int, generation: int, pdf: Any) -> None: # PdfReader
310 self.idnum = idnum
311 self.generation = generation
312 self.pdf = pdf
313
314 def __hash__(self) -> int:
315 return hash((self.idnum, self.generation, id(self.pdf)))
316
317 def hash_bin(self) -> int:
318 """
319 Used to detect modified object.
320
321 Returns:
322 Hash considering type and value.
323
324 """
325 return hash((self.__class__, self.idnum, self.generation, id(self.pdf)))
326
327 def replicate(
328 self,
329 pdf_dest: PdfWriterProtocol,
330 ) -> "PdfObject":
331 return IndirectObject(self.idnum, self.generation, pdf_dest)
332
333 def clone(
334 self,
335 pdf_dest: PdfWriterProtocol,
336 force_duplicate: bool = False,
337 ignore_fields: Sequence[str | int] | None = (),
338 ) -> "IndirectObject":
339 """Clone object into pdf_dest."""
340 if self.pdf == pdf_dest and not force_duplicate:
341 # Already duplicated and no extra duplication required
342 return self
343 if id(self.pdf) not in pdf_dest._id_translated:
344 pdf_dest._id_translated[id(self.pdf)] = {}
345 pdf_dest._id_translated[id(self.pdf)]["PreventGC"] = self.pdf
346
347 if self.idnum in pdf_dest._id_translated[id(self.pdf)]:
348 dup = pdf_dest.get_object(pdf_dest._id_translated[id(self.pdf)][self.idnum])
349 if force_duplicate:
350 assert dup is not None
351 assert dup.indirect_reference is not None
352 idref = dup.indirect_reference
353 return IndirectObject(idref.idnum, idref.generation, idref.pdf)
354 else:
355 obj = self.get_object()
356 # case observed : a pointed object can not be found
357 if obj is None:
358 # this normally
359 obj = NullObject()
360 assert isinstance(self, (IndirectObject,))
361 obj.indirect_reference = self
362 dup = pdf_dest._add_object(
363 obj.clone(pdf_dest, force_duplicate, ignore_fields)
364 )
365 assert isinstance(dup, PdfObject), "mypy"
366 assert dup.indirect_reference is not None, "mypy"
367 return dup.indirect_reference
368
369 @property
370 def indirect_reference(self) -> "IndirectObject": # type: ignore[override]
371 return self
372
373 def get_object(self) -> Optional["PdfObject"]:
374 obj: PdfObject | None = self.pdf.get_object(self)
375 return obj
376
377 def __deepcopy__(self, memo: Any) -> "IndirectObject":
378 return IndirectObject(self.idnum, self.generation, self.pdf)
379
380 def _get_object_with_check(self) -> Optional["PdfObject"]:
381 o = self.get_object()
382 # the check is done here to not slow down get_object()
383 if isinstance(o, IndirectObject):
384 raise PdfStreamError(
385 f"{self.__repr__()} references an IndirectObject {o.__repr__()}"
386 )
387 return o
388
389 def __getattr__(self, name: str) -> Any:
390 # Attribute not found in object: look in pointed object
391 try:
392 return getattr(self._get_object_with_check(), name)
393 except AttributeError as exception:
394 raise AttributeError(
395 f"No attribute {name} found in IndirectObject or pointed object"
396 ) from exception
397
398 def __getitem__(self, key: Any) -> Any:
399 # items should be extracted from pointed Object
400 return self._get_object_with_check()[key] # type: ignore[index]
401
402 def __contains__(self, key: Any) -> bool:
403 return key in self._get_object_with_check() # type: ignore[operator]
404
405 def __iter__(self) -> Any:
406 return self._get_object_with_check().__iter__() # type: ignore[union-attr]
407
408 def __float__(self) -> str:
409 # in this case we are looking for the pointed data
410 return self.get_object().__float__() # type: ignore[union-attr, no-any-return]
411
412 def __int__(self) -> int:
413 # in this case we are looking for the pointed data
414 return self.get_object().__int__() # type: ignore[union-attr, no-any-return]
415
416 def __str__(self) -> str:
417 # in this case we are looking for the pointed data
418 return self.get_object().__str__()
419
420 def __repr__(self) -> str:
421 return f"IndirectObject({self.idnum!r}, {self.generation!r}, {id(self.pdf)})"
422
423 def __eq__(self, other: object) -> bool:
424 return (
425 other is not None
426 and isinstance(other, IndirectObject)
427 and self.idnum == other.idnum
428 and self.generation == other.generation
429 and self.pdf is other.pdf
430 )
431
432 def __ne__(self, other: object) -> bool:
433 return not self.__eq__(other)
434
435 def write_to_stream(self, stream: StreamType) -> None:
436 stream.write(f"{self.idnum} {self.generation} R".encode())
437
438 @staticmethod
439 def read_from_stream(stream: StreamType, pdf: Any) -> "IndirectObject": # PdfReader
440 def read_part(name: str, skip_leading_whitespace: bool) -> bytes:
441 result = bytearray()
442 while True:
443 tok = stream.read(1)
444 if not tok:
445 raise PdfStreamError(STREAM_TRUNCATED_PREMATURELY)
446 if tok.isspace() or tok in WHITESPACES:
447 if skip_leading_whitespace and not result:
448 continue
449 break
450 if len(result) >= IndirectObject._MAXIMUM_PART_LENGTH:
451 raise PdfReadError(f"{name} exceeds maximum length limit of {IndirectObject._MAXIMUM_PART_LENGTH}.")
452 result += tok
453 return bytes(result)
454
455 idnum = read_part("Object ID", skip_leading_whitespace=False)
456 generation = read_part("Generation number", skip_leading_whitespace=True)
457
458 r = read_non_whitespace(stream)
459 if r != b"R":
460 raise PdfReadError(
461 f"Error reading indirect object reference at byte {hex(stream.tell())}"
462 )
463 try:
464 return IndirectObject(int(idnum), int(generation), pdf)
465 except (ValueError, OverflowError) as exception:
466 raise PdfReadError(
467 f"Invalid indirect object reference ({idnum!r} {generation!r} R): {exception}"
468 ) from exception
469
470
471FLOAT_WRITE_PRECISION = 8 # shall be min 5 digits max, allow user adj
472
473
474class FloatObject(float, PdfObject):
475 def __new__(
476 cls, value: Any = "0.0", context: Any | None = None
477 ) -> Self:
478 try:
479 value = float(value)
480 return float.__new__(cls, value)
481 except MemoryError: # pragma: no cover # TODO: BLE001
482 raise
483 except Exception as exception:
484 # If this isn't a valid decimal (happens in malformed PDFs)
485 # fallback to 0
486 logger_warning(
487 "%(error)s : FloatObject (%(value)s) invalid; use 0.0 instead",
488 source=__name__,
489 error=exception,
490 value=value,
491 )
492 return float.__new__(cls, 0.0)
493
494 def clone(
495 self,
496 pdf_dest: Any,
497 force_duplicate: bool = False,
498 ignore_fields: Sequence[str | int] | None = (),
499 ) -> "FloatObject":
500 """Clone object into pdf_dest."""
501 return cast(
502 "FloatObject",
503 self._reference_clone(FloatObject(self), pdf_dest, force_duplicate),
504 )
505
506 def hash_bin(self) -> int:
507 """
508 Used to detect modified object.
509
510 Returns:
511 Hash considering type and value.
512
513 """
514 return hash((self.__class__, self.as_numeric()))
515
516 def myrepr(self) -> str:
517 if self == 0: # type: ignore[comparison-overlap]
518 return "0.0"
519 nb = FLOAT_WRITE_PRECISION - int(log10(abs(self)))
520 return f"{self:.{max(1, nb)}f}".rstrip("0").rstrip(".")
521
522 def __repr__(self) -> str:
523 return self.myrepr() # repr(float(self))
524
525 def as_numeric(self) -> float:
526 return float(self)
527
528 def write_to_stream(self, stream: StreamType) -> None:
529 stream.write(self.myrepr().encode("utf8"))
530
531
532class NumberObject(int, PdfObject):
533 NumberPattern = re.compile(b"[^+-.0-9]")
534 _LENGTH_LIMIT = 64
535
536 def __new__(cls, value: Any) -> Self:
537 try:
538 return int.__new__(cls, int(value))
539 except ValueError:
540 logger_warning("NumberObject(%(value)s) invalid; use 0 instead", source=__name__, value=value)
541 return int.__new__(cls, 0)
542
543 def clone(
544 self,
545 pdf_dest: Any,
546 force_duplicate: bool = False,
547 ignore_fields: Sequence[str | int] | None = (),
548 ) -> "NumberObject":
549 """Clone object into pdf_dest."""
550 return cast(
551 "NumberObject",
552 self._reference_clone(NumberObject(self), pdf_dest, force_duplicate),
553 )
554
555 def hash_bin(self) -> int:
556 """
557 Used to detect modified object.
558
559 Returns:
560 Hash considering type and value.
561
562 """
563 return hash((self.__class__, self.as_numeric()))
564
565 def as_numeric(self) -> int:
566 return int(repr(self).encode("utf8"))
567
568 def write_to_stream(self, stream: StreamType) -> None:
569 stream.write(repr(self).encode("utf8"))
570
571 @staticmethod
572 def read_from_stream(stream: StreamType) -> Union["NumberObject", "FloatObject"]:
573 num = read_until_regex(stream=stream, regex=NumberObject.NumberPattern, length=NumberObject._LENGTH_LIMIT)
574 if b"." in num:
575 return FloatObject(num)
576 return NumberObject(num)
577
578
579class ByteStringObject(bytes, PdfObject):
580 """
581 Represents a string object where the text encoding could not be determined.
582
583 This occurs quite often, as the PDF spec doesn't provide an alternate way to
584 represent strings -- for example, the encryption data stored in files (like
585 /O) is clearly not text, but is still stored in a "String" object.
586 """
587
588 def clone(
589 self,
590 pdf_dest: Any,
591 force_duplicate: bool = False,
592 ignore_fields: Sequence[str | int] | None = (),
593 ) -> "ByteStringObject":
594 """Clone object into pdf_dest."""
595 return cast(
596 "ByteStringObject",
597 self._reference_clone(
598 ByteStringObject(bytes(self)), pdf_dest, force_duplicate
599 ),
600 )
601
602 def hash_bin(self) -> int:
603 """
604 Used to detect modified object.
605
606 Returns:
607 Hash considering type and value.
608
609 """
610 return hash((self.__class__, bytes(self)))
611
612 @property
613 def original_bytes(self) -> bytes:
614 """For compatibility with TextStringObject.original_bytes."""
615 return self
616
617 def write_to_stream(self, stream: StreamType) -> None:
618 stream.write(b"<")
619 stream.write(binascii.hexlify(self))
620 stream.write(b">")
621
622 def __str__(self) -> str:
623 charset_to_try = ["utf-16", *list(NameObject.CHARSETS)]
624 for enc in charset_to_try:
625 try:
626 return self.decode(enc)
627 except UnicodeDecodeError:
628 pass
629 raise PdfReadError("Cannot decode ByteStringObject.")
630
631
632class TextStringObject(str, PdfObject): # noqa: SLOT000
633 """
634 A string object that has been decoded into a real unicode string.
635
636 If read from a PDF document, this string appeared to match the
637 PDFDocEncoding, or contained a UTF-16BE BOM mark to cause UTF-16 decoding
638 to occur.
639 """
640
641 autodetect_pdfdocencoding: bool
642 autodetect_utf16: bool
643 utf16_bom: bytes
644 _original_bytes: bytes | None = None
645
646 def __new__(cls, value: Any) -> Self:
647 original_bytes = None
648 if isinstance(value, bytes):
649 original_bytes = value
650 value = value.decode("charmap")
651 text_string_object = str.__new__(cls, value)
652 text_string_object._original_bytes = original_bytes
653 text_string_object.autodetect_utf16 = False
654 text_string_object.autodetect_pdfdocencoding = False
655 text_string_object.utf16_bom = b""
656 if original_bytes is not None and original_bytes[:2] in {codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE}:
657 # The value of `original_bytes` is only set for inputs being `bytes`.
658 # If this is UTF-16 data according to the BOM (first two characters),
659 # perform special handling. All other cases should not need any special conversion
660 # due to already being a string.
661 try:
662 text_string_object = str.__new__(cls, original_bytes.decode("utf-16"))
663 except UnicodeDecodeError as exception:
664 logger_warning(
665 "%(exception)s; initial string: %(initial_string)r",
666 source=__name__,
667 exception=exception,
668 initial_string=exception.object,
669 )
670 text_string_object = str.__new__(cls, exception.object[: exception.start].decode("utf-16"))
671 text_string_object._original_bytes = original_bytes
672 text_string_object.autodetect_utf16 = True
673 text_string_object.utf16_bom = original_bytes[:2]
674 else:
675 try:
676 encode_pdfdocencoding(text_string_object)
677 text_string_object.autodetect_pdfdocencoding = True
678 except UnicodeEncodeError:
679 text_string_object.autodetect_utf16 = True
680 text_string_object.utf16_bom = codecs.BOM_UTF16_BE
681 return text_string_object
682
683 def clone(
684 self,
685 pdf_dest: Any,
686 force_duplicate: bool = False,
687 ignore_fields: Sequence[str | int] | None = (),
688 ) -> "TextStringObject":
689 """Clone object into pdf_dest."""
690 obj = TextStringObject(self)
691 obj._original_bytes = self._original_bytes
692 obj.autodetect_pdfdocencoding = self.autodetect_pdfdocencoding
693 obj.autodetect_utf16 = self.autodetect_utf16
694 obj.utf16_bom = self.utf16_bom
695 return cast(
696 "TextStringObject", self._reference_clone(obj, pdf_dest, force_duplicate)
697 )
698
699 def hash_bin(self) -> int:
700 """
701 Used to detect modified object.
702
703 Returns:
704 Hash considering type and value.
705
706 """
707 return hash((self.__class__, self.original_bytes))
708
709 @property
710 def original_bytes(self) -> bytes:
711 """
712 It is occasionally possible that a text string object gets created where
713 a byte string object was expected due to the autodetection mechanism --
714 if that occurs, this "original_bytes" property can be used to
715 back-calculate what the original encoded bytes were.
716 """
717 if self._original_bytes is not None:
718 return self._original_bytes
719 return self.get_original_bytes()
720
721 def get_original_bytes(self) -> bytes:
722 # We're a text string object, but the library is trying to get our raw
723 # bytes. This can happen if we auto-detected this string as text, but
724 # we were wrong. It's pretty common. Return the original bytes that
725 # would have been used to create this object, based upon the autodetect
726 # method.
727 if self.autodetect_utf16:
728 if self.utf16_bom == codecs.BOM_UTF16_LE:
729 return codecs.BOM_UTF16_LE + self.encode("utf-16le")
730 if self.utf16_bom == codecs.BOM_UTF16_BE:
731 return codecs.BOM_UTF16_BE + self.encode("utf-16be")
732 return self.encode("utf-16be")
733 if self.autodetect_pdfdocencoding:
734 return encode_pdfdocencoding(self)
735 raise Exception("no information about original bytes") # pragma: no cover
736
737 def get_encoded_bytes(self) -> bytes:
738 # Try to write the string out as a PDFDocEncoding encoded string. It's
739 # nicer to look at in the PDF file. Sadly, we take a performance hit
740 # here for trying...
741 try:
742 if self._original_bytes is not None:
743 return self._original_bytes
744 if self.autodetect_utf16:
745 raise UnicodeEncodeError("", "forced", -1, -1, "")
746 bytearr = encode_pdfdocencoding(self)
747 except UnicodeEncodeError:
748 if self.utf16_bom == codecs.BOM_UTF16_LE:
749 bytearr = codecs.BOM_UTF16_LE + self.encode("utf-16le")
750 elif self.utf16_bom == codecs.BOM_UTF16_BE:
751 bytearr = codecs.BOM_UTF16_BE + self.encode("utf-16be")
752 else:
753 bytearr = self.encode("utf-16be")
754 return bytearr
755
756 def write_to_stream(self, stream: StreamType) -> None:
757 bytearr = self.get_encoded_bytes()
758 stream.write(b"(")
759 for c_ in iter_unpack("c", bytearr):
760 c = cast(bytes, c_[0])
761 if not c.isalnum() and c != b" ":
762 # This:
763 # stream.write(rf"\{c:0>3o}".encode())
764 # gives
765 # https://github.com/davidhalter/parso/issues/207
766 stream.write(b"\\%03o" % ord(c))
767 else:
768 stream.write(c)
769 stream.write(b")")
770
771
772class NameObject(str, PdfObject): # noqa: SLOT000
773 delimiter_pattern = re.compile(rb"\s+|[\(\)<>\[\]{}/%]")
774 prefix = b"/"
775 renumber_table: ClassVar[dict[str, bytes]] = {
776 **{chr(i): f"#{i:02X}".encode() for i in b"#()<>[]{}/%"},
777 **{chr(i): f"#{i:02X}".encode() for i in range(33)},
778 }
779 _LENGTH_LIMIT = 4096
780
781 def clone(
782 self,
783 pdf_dest: Any,
784 force_duplicate: bool = False,
785 ignore_fields: Sequence[str | int] | None = (),
786 ) -> "NameObject":
787 """Clone object into pdf_dest."""
788 return cast(
789 "NameObject",
790 self._reference_clone(NameObject(self), pdf_dest, force_duplicate),
791 )
792
793 def hash_bin(self) -> int:
794 """
795 Used to detect modified object.
796
797 Returns:
798 Hash considering type and value.
799
800 """
801 return hash((self.__class__, self))
802
803 def write_to_stream(self, stream: StreamType) -> None:
804 stream.write(self.renumber())
805
806 def renumber(self) -> bytes:
807 out = self[0].encode("utf-8")
808 if out != b"/":
809 raise PdfStreamError(
810 f"Incorrect first char in NameObject, should start with '/': ({self})",
811 )
812 parts = [out]
813 for c in self[1:]:
814 if c > "~":
815 parts.extend(f"#{x:02X}".encode() for x in c.encode("utf-8"))
816 else:
817 try:
818 parts.append(self.renumber_table[c])
819 except KeyError:
820 parts.append(c.encode("utf-8"))
821 return b"".join(parts)
822
823 def _sanitize(self) -> "NameObject":
824 """
825 Sanitize the NameObject's name to be a valid PDF name part
826 (alphanumeric, underscore, hyphen). The _sanitize method replaces
827 spaces and any non-alphanumeric/non-underscore/non-hyphen with
828 underscores.
829
830 Returns:
831 NameObject with sanitized name.
832 """
833 name = str(self).removeprefix("/")
834 name = re.sub(r" ", "_", name)
835 name = re.sub(r"[^a-zA-Z0-9_-]", "_", name)
836 return NameObject("/" + name)
837
838 @staticmethod
839 def unnumber(sin: bytes) -> bytes:
840 if b"#" not in sin:
841 return bytes(sin)
842 result = bytearray()
843 i = 0
844 while i < len(sin):
845 if sin[i:i + 1] == b"#":
846 try:
847 result.append(int(sin[i + 1 : i + 3], 16))
848 i += 3
849 continue
850 except (ValueError, IndexError):
851 # if the 2 characters after # can not be converted to hex
852 # we change nothing and carry on
853 pass
854 result.append(sin[i])
855 i += 1
856 return bytes(result)
857
858 CHARSETS = ("utf-8", "gbk", "latin1")
859
860 @staticmethod
861 def read_from_stream(stream: StreamType, pdf: Any) -> "NameObject": # PdfReader
862 name = stream.read(1)
863 if name != NameObject.prefix:
864 raise PdfReadError("Name read error")
865 name += read_until_regex(stream=stream, regex=NameObject.delimiter_pattern, length=NameObject._LENGTH_LIMIT)
866 try:
867 # Name objects should represent irregular characters
868 # with a '#' followed by the symbol's hex number
869 name = NameObject.unnumber(name)
870 for enc in NameObject.CHARSETS:
871 try:
872 ret = name.decode(enc)
873 return NameObject(ret)
874 except MemoryError: # pragma: no cover # TODO: BLE001
875 raise
876 except Exception:
877 pass
878 raise UnicodeDecodeError("", name, 0, 0, "Code Not Found")
879 except (UnicodeEncodeError, UnicodeDecodeError) as exception:
880 if not pdf.strict:
881 logger_warning(
882 "Illegal character in NameObject (%(name)r), you may need to adjust NameObject.CHARSETS",
883 source=__name__,
884 name=name,
885 )
886 return NameObject(name.decode("charmap"))
887 raise PdfReadError(
888 f"Illegal character in NameObject ({name!r}). "
889 "You may need to adjust NameObject.CHARSETS.",
890 ) from exception
891
892
893def encode_pdfdocencoding(unicode_string: str) -> bytes:
894 try:
895 return bytes([_pdfdoc_encoding_rev[k] for k in unicode_string])
896 except KeyError as exception:
897 raise UnicodeEncodeError(
898 "pdfdocencoding",
899 unicode_string,
900 -1,
901 -1,
902 "does not exist in translation table",
903 ) from exception
904
905
906def is_null_or_none(x: Any) -> TypeGuard[NullObject | IndirectObject | None]:
907 """
908 Returns:
909 True if x is None or NullObject.
910
911 """
912 return x is None or (
913 isinstance(x, PdfObject)
914 and (x.get_object() is None or isinstance(x.get_object(), NullObject))
915 )