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