Source code

Download source archive ↓

src/pypdf/generic/_utils.py

1import codecs
2from dataclasses import dataclass
3from typing import Union
4
5from .._codecs import _pdfdoc_encoding
6from .._utils import StreamType, logger_warning, read_non_whitespace
7from ..errors import STREAM_TRUNCATED_PREMATURELY, PdfStreamError
8from ._base import ByteStringObject, TextStringObject
9
10_PDFDOC_DECODE_MAP = dict(enumerate(_pdfdoc_encoding))
11
12
13def hex_to_rgb(value: str) -> tuple[float, float, float]:
14    return tuple(int(value.lstrip("#")[i : i + 2], 16) / 255.0 for i in (0, 2, 4))  # type: ignore[return-value]
15
16
17def read_hex_string_from_stream(
18    stream: StreamType,
19    forced_encoding: str | list[str] | dict[int, str] | None = None,
20) -> Union["TextStringObject", "ByteStringObject"]:
21    stream.read(1)
22    arr = bytearray()
23    x = b""
24    while True:
25        tok = read_non_whitespace(stream)
26        if not tok:
27            raise PdfStreamError(STREAM_TRUNCATED_PREMATURELY)
28        if tok == b">":
29            break
30        if tok not in b"0123456789abcdefABCDEF":
31            raise PdfStreamError(
32                f"Invalid hexadecimal character {tok!r} in hex string"
33            )
34        x += tok
35        if len(x) == 2:
36            arr.append(int(x, base=16))
37            x = b""
38    if len(x) == 1:
39        x += b"0"
40    if x != b"":
41        arr.append(int(x, base=16))
42    return create_string_object(bytes(arr), forced_encoding)
43
44
45__ESCAPE_DICT__ = {
46    b"n": ord(b"\n"),
47    b"r": ord(b"\r"),
48    b"t": ord(b"\t"),
49    b"b": ord(b"\b"),
50    b"f": ord(b"\f"),
51    b"(": ord(b"("),
52    b")": ord(b")"),
53    b"/": ord(b"/"),
54    b"\\": ord(b"\\"),
55    b" ": ord(b" "),
56    b"%": ord(b"%"),
57    b"<": ord(b"<"),
58    b">": ord(b">"),
59    b"[": ord(b"["),
60    b"]": ord(b"]"),
61    b"#": ord(b"#"),
62    b"_": ord(b"_"),
63    b"&": ord(b"&"),
64    b"$": ord(b"$"),
65}
66__BACKSLASH_CODE__ = 92
67
68
69def read_string_from_stream(
70    stream: StreamType,
71    forced_encoding: str | list[str] | dict[int, str] | None = None,
72) -> Union["TextStringObject", "ByteStringObject"]:
73    tok = stream.read(1)
74    parens = 1
75    txt = []
76    while True:
77        tok = stream.read(1)
78        if not tok:
79            raise PdfStreamError(STREAM_TRUNCATED_PREMATURELY)
80        if tok == b"(":
81            parens += 1
82        elif tok == b")":
83            parens -= 1
84            if parens == 0:
85                break
86        elif tok == b"\\":
87            tok = stream.read(1)
88            try:
89                txt.append(__ESCAPE_DICT__[tok])
90                continue
91            except KeyError:
92                if b"0" <= tok <= b"7":
93                    # "The number ddd may consist of one, two, or three
94                    # octal digits; high-order overflow shall be ignored.
95                    # Three octal digits shall be used, with leading zeros
96                    # as needed, if the next character of the string is also
97                    # a digit." (PDF reference 7.3.4.2, p 16)
98                    sav = stream.tell() - 1
99                    for _ in range(2):
100                        ntok = stream.read(1)
101                        if b"0" <= ntok <= b"7":
102                            tok += ntok
103                        else:
104                            stream.seek(-1, 1)  # ntok has to be analyzed
105                            break
106                    i = int(tok, base=8)
107                    if i > 255:
108                        txt.append(__BACKSLASH_CODE__)
109                        stream.seek(sav)
110                    else:
111                        txt.append(i)
112                    continue
113                if tok in b"\n\r":
114                    # This case is hit when a backslash followed by a line
115                    # break occurs. If it's a multi-char EOL, consume the
116                    # second character:
117                    tok = stream.read(1)
118                    if tok not in b"\n\r":
119                        stream.seek(-1, 1)
120                    # Then don't add anything to the actual string, since this
121                    # line break was escaped:
122                    continue
123                logger_warning(
124                    "Unexpected escaped string: %(token)s",
125                    source=__name__,
126                    token=tok.decode("utf-8", "ignore"),
127                )
128                txt.append(__BACKSLASH_CODE__)
129        txt.append(ord(tok))
130    return create_string_object(bytes(txt), forced_encoding)
131
132
133def create_string_object(
134    string: str | bytes,
135    forced_encoding: str | list[str] | dict[int, str] | None = None,
136) -> TextStringObject | ByteStringObject:
137    """
138    Create a ByteStringObject or a TextStringObject from a string to represent the string.
139
140    Args:
141        string: The data being used
142        forced_encoding: Typically None, or an encoding string
143
144    Returns:
145        A ByteStringObject
146
147    Raises:
148        TypeError: If string is not of type str or bytes.
149
150    """
151    if isinstance(string, str):
152        return TextStringObject(string)
153    if isinstance(string, bytes):
154        if isinstance(forced_encoding, (list, dict)):
155            out = []
156
157            if isinstance(forced_encoding, list):
158                list_length = len(forced_encoding)
159            else:
160                list_length = None
161
162            for x in string:
163                if (
164                        (list_length is not None and x < list_length) or
165                        (list_length is None and x in forced_encoding)
166                ):
167                    value = forced_encoding[x]
168                else:
169                    value = bytes((x,)).decode("charmap")
170                out.append(value)
171            obj = TextStringObject("".join(out))
172            obj._original_bytes = string
173            return obj
174        if isinstance(forced_encoding, str):
175            if forced_encoding == "bytes":
176                return ByteStringObject(string)
177            obj = TextStringObject(string.decode(forced_encoding))
178            obj._original_bytes = string
179            return obj
180        try:
181            unicode_string = _create_unicode_string_object(string)
182            if unicode_string is not None:
183                return unicode_string
184
185            # This is probably a big performance hit here, but we need
186            # to convert string objects into the text/unicode-aware
187            # version if possible... and the only way to check if that's
188            # possible is to try.
189            # Some strings are strings, some are just byte arrays.
190            retval = TextStringObject(decode_pdfdocencoding(string))
191        except UnicodeDecodeError:
192            return ByteStringObject(string)
193
194        retval._original_bytes = string
195        retval.autodetect_pdfdocencoding = True
196        return retval
197    raise TypeError("create_string_object should have str or unicode arg")
198
199
200def _create_unicode_string_object(data: bytes) -> TextStringObject | None:
201    """
202    Decode a text string which is marked or detected as UTF-8 or UTF-16.
203
204    Args:
205        data: The data being used
206
207    Returns:
208        A TextStringObject, or None if the data should be decoded as PDFDocEncoding.
209
210    Raises:
211        UnicodeDecodeError: If the data cannot be decoded as UTF-16.
212
213    """
214    if data.startswith(codecs.BOM_UTF8):
215        # UTF-8 text strings have been added with PDF 2.0, see ISO 32000-2:2020, 7.9.2.2.1.
216        # Data which is not valid UTF-8 is still decoded as PDFDocEncoding.
217        try:
218            retval = TextStringObject(data[len(codecs.BOM_UTF8):].decode("utf-8"))
219        except UnicodeDecodeError:
220            return None
221        retval._original_bytes = data
222        return retval
223    if data.startswith((codecs.BOM_UTF16_BE, codecs.BOM_UTF16_LE)):
224        retval = TextStringObject(data.decode("utf-16"))
225        retval._original_bytes = data
226        retval.autodetect_utf16 = True
227        retval.utf16_bom = data[:2]
228        return retval
229    if data.startswith(b"\x00"):
230        retval = TextStringObject(data.decode("utf-16be"))
231        retval._original_bytes = data
232        retval.autodetect_utf16 = True
233        retval.utf16_bom = codecs.BOM_UTF16_BE
234        return retval
235    if data[1:2] == b"\x00":
236        retval = TextStringObject(data.decode("utf-16le"))
237        retval._original_bytes = data
238        retval.autodetect_utf16 = True
239        retval.utf16_bom = codecs.BOM_UTF16_LE
240        return retval
241    return None
242
243
244def decode_pdfdocencoding(byte_array: bytes) -> str:
245    # latin1 maps each byte to the code point of the same value, so translate()
246    # applies the PDFDocEncoding table in C instead of a Python loop.
247    # Unassigned bytes map to "\u0000"; check for them afterwards.
248    # codecs.charmap_decode() would be faster (a single pass in C), but it is
249    # an undocumented implementation detail of CPython, so we do not use it.
250    retval = bytes(byte_array).decode("latin1").translate(_PDFDOC_DECODE_MAP)
251
252    idx = retval.find("\u0000")
253    if idx != -1:
254        raise UnicodeDecodeError(
255            "pdfdocencoding",
256            bytes(byte_array),
257            idx,  # start
258            idx + 1,  # end
259            "does not exist in translation table",
260        )
261    return retval
262
263
264@dataclass
265class StreamParsingBudget:
266    """
267    Shared, mutable budget for limiting parsing work.
268
269    Pass the same instance to recursive parsing calls to enforce a
270    cumulative budget across nested arrays and dictionaries.
271    """
272    remaining_budget: int