Source code

Download source archive ↓

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    )