Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pypdf/generic/_appearance_stream.py: 15%

1from __future__ import annotations 

2 

3import copy 

4from dataclasses import dataclass, field 

5from enum import IntEnum 

6from io import BytesIO 

7from operator import attrgetter 

8from typing import TYPE_CHECKING, Any, NamedTuple, cast 

9 

10from .._codecs import encoding_dict_from_named_encoding 

11from .._codecs.core_font_metrics import CORE_FONT_METRICS 

12from .._page import Transformation 

13from .._utils import is_char_rtl, logger_warning 

14from ..constants import AnnotationDictionaryAttributes, BorderStyles, FieldDictionaryAttributes, PageAttributes 

15from ..errors import PdfReadError 

16from ..generic import ( 

17 ArrayObject, 

18 ContentStream, 

19 DecodedStreamObject, 

20 DictionaryObject, 

21 FloatObject, 

22 IndirectObject, 

23 NameObject, 

24 NumberObject, 

25 RectangleObject, 

26 StreamObject, 

27) 

28from ..generic._base import ByteStringObject, TextStringObject 

29from ._color import Color, DeviceGray 

30from ._font import Font 

31 

32if TYPE_CHECKING: 

33 from pypdf._writer import PdfWriter 

34 

35 from .._page import PageObject 

36 

37try: 

38 import arabic_reshaper 

39 from bidi.algorithm import get_display 

40 HAS_RTL_SUPPORT = True 

41except ImportError: 

42 HAS_RTL_SUPPORT = False 

43 

44DEFAULT_FONT_SIZE_IN_MULTILINE = 12 

45 

46# "The glyph widths shall be measured in units in which 1000 units correspond to 1 unit in text space" 

47# (Table 111, PDF Specification 2.0) 

48TEXT_SPACE_TO_GLYPH_SPACE_FACTOR = 1000 

49 

50 

51@dataclass 

52class BaseStreamConfig: 

53 """A container representing the basic layout of an appearance stream.""" 

54 rectangle: RectangleObject = field(default_factory=lambda: RectangleObject((0.0, 0.0, 0.0, 0.0))) 

55 border_width: int = 1 # The width of the border in points 

56 border_style: str = BorderStyles.SOLID 

57 border_color: Color | None = None 

58 background_color: Color | None = None 

59 rotation: int = 0 

60 

61 

62class BaseStreamAppearance(DecodedStreamObject): 

63 """A class representing the very base of an appearance stream, that is, a rectangle and a border.""" 

64 

65 def _add_matrix(self, rotation: int) -> None: 

66 # We need to rotate our rectangle while keeping its origin to (0, 0). 

67 # Rotation goes counterclockwise. We want to know the furthest points to which we rotated left and down. 

68 # These will serve as our X and Y offsets to translate the entire object origin back to (0, 0). 

69 # If a corner rotates into negative space, that is our offset. If none does, the minimum is 0.0. 

70 matrix = Transformation().rotate(rotation) 

71 bottom_right_corner = (self._layout.rectangle.width, 0.0) 

72 top_left_corner = (0.0, self._layout.rectangle.height) 

73 top_right_corner = (self._layout.rectangle.width, self._layout.rectangle.height) 

74 rotated_bottom_right_corner = matrix.apply_on(bottom_right_corner) 

75 rotated_top_left_corner = matrix.apply_on(top_left_corner) 

76 rotated_top_right_corner = matrix.apply_on(top_right_corner) 

77 translation_x_offset = -min( 

78 0.0, rotated_bottom_right_corner[0], rotated_top_left_corner[0], rotated_top_right_corner[0] 

79 ) 

80 translation_y_offset = -min( 

81 0.0, rotated_bottom_right_corner[1], rotated_top_left_corner[1], rotated_top_right_corner[1] 

82 ) 

83 matrix = matrix.translate(translation_x_offset, translation_y_offset) 

84 self[NameObject("/Matrix")] = ArrayObject([FloatObject(round(i, 3)) for i in matrix.ctm]) 

85 

86 def __init__(self, layout: BaseStreamConfig | None) -> None: 

87 """ 

88 Takes the appearance stream layout as an argument. 

89 

90 Args: 

91 layout: The basic layout parameters. 

92 """ 

93 super().__init__() 

94 self._layout = layout or BaseStreamConfig() 

95 self[NameObject("/Type")] = NameObject("/XObject") 

96 self[NameObject("/Subtype")] = NameObject("/Form") 

97 self[NameObject("/BBox")] = self._layout.rectangle 

98 

99 # Define the rotation matrix 

100 rotation = self._layout.rotation % 360 

101 if rotation: 

102 self._add_matrix(rotation) 

103 

104 ap_stream_parts = [] 

105 # Only add a background color when color is defined and not transparent 

106 if isinstance(self._layout.background_color, Color): 

107 ap_stream_parts.append( 

108 f"0 0 {self._layout.rectangle.width} {self._layout.rectangle.height} re\n" 

109 f"{self._layout.background_color.as_operator()}\n" 

110 "f\n" 

111 ) 

112 # Only add a border when border width is larger than 0, border 

113 # color is defined, and border color is not set to transparent. 

114 if self._layout.border_width > 0: 

115 if isinstance(self._layout.border_color, Color): 

116 border_width_string = f"{self._layout.border_width} w\n" if self._layout.border_width != 1 else "" 

117 ap_stream_parts.append( 

118 f"{self._layout.border_width} " 

119 f"{self._layout.border_width} " 

120 f"{self._layout.rectangle.width - 2 * self._layout.border_width} " 

121 f"{self._layout.rectangle.height - 2 * self._layout.border_width} re\n" 

122 f"{border_width_string}" 

123 f"{self._layout.border_color.as_operator(stroke=True)}\n" 

124 "s\n" 

125 ) 

126 else: 

127 # If we aren't drawing a border, then set border_width to 0. This means less margin to 

128 # take into account and results in larger font sizes. 

129 self._layout.border_width = 0 

130 if ap_stream_parts: 

131 ap_stream_parts.insert(0, "q\n") 

132 ap_stream_parts.append("Q\n") 

133 self._ap_stream_data = "".join(ap_stream_parts).encode() 

134 

135 

136class TextAlignment(IntEnum): 

137 """Defines the alignment options for text within a form field's appearance stream.""" 

138 

139 LEFT = 0 

140 CENTER = 1 

141 RIGHT = 2 

142 

143 

144class WidthWordGlyphs(NamedTuple): 

145 """A tuple of the unscaled width of a word (unencoded text) and the font-encoded glyphs that represent it.""" 

146 

147 width: float 

148 word: str 

149 glyphs: str 

150 

151 

152class TextStreamAppearance(BaseStreamAppearance): 

153 """ 

154 A class representing the appearance stream for a text-based form field. 

155 

156 This class generates the content stream (the `ap_stream_data`) that dictates 

157 how text is rendered within a form field's bounding box. It handles properties 

158 like font, font size, color, multiline text, and text selection highlighting. 

159 """ 

160 

161 def _scale_text( 

162 self, 

163 font: Font, 

164 font_size: float, 

165 leading_factor: float, 

166 field_width: float, 

167 field_height: float, 

168 paragraphs: list[list[WidthWordGlyphs]], 

169 min_font_size: float, 

170 font_size_step: float = 0.2 

171 ) -> tuple[list[WidthWordGlyphs], float]: 

172 """ 

173 Takes a piece of text and scales it to field_width or field_height, given font_name 

174 and font_size. Wraps text where necessary. 

175 

176 Args: 

177 font: The font to be used. 

178 font_size: The font size in points. 

179 leading_factor: The line distance. 

180 field_width: The width of the field in which to fit the text. 

181 field_height: The height of the field in which to fit the text. 

182 paragraphs: The list of text paragraphs to fit with the field, where each paragraph is a list 

183 of tuples of unscaled width, unencoded text, and glyphs (font-encoded text). 

184 min_font_size: The minimum font size at which to scale the text. 

185 font_size_step: The amount by which to decrement font size per step while scaling. 

186 

187 Returns: 

188 The text in the form of list of tuples, each tuple containing the length of a line 

189 and its contents, and the font_size for these lines and lengths. 

190 """ 

191 wrapped_lines = [] 

192 current_line_words: list[WidthWordGlyphs] = [] 

193 current_line_width: float = 0 

194 space_width = font.space_width * font_size / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR 

195 for paragraph in paragraphs: 

196 for i, width_word_glyphs in enumerate(paragraph): 

197 word_width = width_word_glyphs.width * font_size 

198 test_width = current_line_width + word_width + (space_width if i else 0) 

199 if test_width > field_width and current_line_words: 

200 wrapped_lines.append( 

201 WidthWordGlyphs( 

202 width=current_line_width, 

203 word=" ".join(map(attrgetter("word"), current_line_words)), 

204 glyphs=font.space_char.join(map(attrgetter("glyphs"), current_line_words)) 

205 ) 

206 ) 

207 current_line_words = [width_word_glyphs] 

208 current_line_width = word_width 

209 elif not current_line_words and word_width > field_width: 

210 wrapped_lines.append( 

211 WidthWordGlyphs( 

212 width=word_width, 

213 word=width_word_glyphs.word, 

214 glyphs=width_word_glyphs.glyphs 

215 ) 

216 ) 

217 current_line_words = [] 

218 current_line_width = 0 

219 else: 

220 if current_line_words: 

221 current_line_width += space_width 

222 current_line_words.append(width_word_glyphs) 

223 current_line_width += word_width 

224 if current_line_words: 

225 wrapped_lines.append(WidthWordGlyphs( 

226 width=current_line_width, 

227 word=" ".join(map(attrgetter("word"), current_line_words)), 

228 glyphs=font.space_char.join(map(attrgetter("glyphs"), current_line_words)) 

229 )) 

230 current_line_words = [] 

231 current_line_width = 0 

232 # Estimate total height. 

233 estimated_total_height = font_size + (len(wrapped_lines) - 1) * leading_factor * font_size 

234 if estimated_total_height > field_height: 

235 # Text overflows height; Retry with smaller font size. 

236 new_font_size = font_size - font_size_step 

237 if new_font_size >= min_font_size: 

238 return self._scale_text( 

239 font, 

240 new_font_size, 

241 leading_factor, 

242 field_width, 

243 field_height, 

244 paragraphs, 

245 min_font_size, 

246 font_size_step 

247 ) 

248 return wrapped_lines, round(font_size, 1) 

249 

250 def _generate_appearance_stream_data( 

251 self, 

252 text: str, 

253 selection: list[str] | None , 

254 font: Font, 

255 font_name: str = "/Helv", 

256 font_size: float = 0.0, 

257 font_color: Color | None = None, 

258 is_multiline: bool = False, 

259 alignment: TextAlignment = TextAlignment.LEFT, 

260 is_comb: bool = False, 

261 max_length: int | None = None 

262 ) -> bytes: 

263 """ 

264 Generates the raw bytes of the PDF appearance stream for a text field. 

265 

266 This private method assembles the PDF content stream operators to draw 

267 the provided text within the specified rectangle. It handles text positioning, 

268 font application, color, and special formatting like selected text. 

269 

270 Args: 

271 text: The text to be rendered in the form field. 

272 selection: An optional list of strings that should be highlighted as selected. 

273 font: The font to use. 

274 font_name: The name of the font resource to use (e.g., "/Helv"). 

275 font_size: The font size. If 0, it is automatically calculated 

276 based on whether the field is multiline or not. 

277 font_color: The color to apply to the font, represented as a class Color 

278 is_multiline: A boolean indicating if the text field is multiline. 

279 alignment: Text alignment, can be TextAlignment.LEFT, .RIGHT, or .CENTER. 

280 is_comb: Boolean that designates fixed-length fields, where every character 

281 fills one "cell", such as in a postcode. 

282 max_length: Used if is_comb is set. The maximum number of characters for a fixed- 

283 length field. 

284 

285 Returns: 

286 A byte string containing the PDF content stream data. 

287 

288 """ 

289 font_color = font_color or DeviceGray() 

290 rectangle = self._layout.rectangle 

291 leading_factor = ( 

292 (font.font_descriptor.bbox[3] - font.font_descriptor.bbox[1]) / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR 

293 ) 

294 

295 # Set margins based on border width and style 

296 factor = 2 if self._layout.border_style in {"/B", "/I"} else 1 

297 margin = self._layout.border_width * factor 

298 field_height = rectangle.height - 2 * margin 

299 field_width = rectangle.width - 4 * max(margin, 1) 

300 

301 reverse_cmap, encoding_cmap = font._get_typographic_maps() 

302 

303 def _unicode_to_glyph_id(text: str, reverse_cmap: dict[str, str]) -> str: 

304 if HAS_RTL_SUPPORT: 

305 # Use arabic-reshaper and python-bidi to rearrange and shape text for the PDF engine 

306 reshaped_text = arabic_reshaper.reshape(text) 

307 visual_text = get_display(reshaped_text, base_dir="L") 

308 return "".join(reverse_cmap.get(char, char) for char in visual_text) 

309 

310 return "".join(reverse_cmap.get(char, char) for char in text) 

311 

312 

313 def _glyph_id_to_bytes(glyphs: str, encoding_cmap: dict[str, bytes]) -> list[bytes]: 

314 return [encoding_cmap.get( 

315 glyph_id, bytes((ord(glyph_id),)) if ord(glyph_id) < 256 else b"?" 

316 ) for glyph_id in glyphs] 

317 

318 # If font_size is 0, apply the logic for multiline or large-as-possible font 

319 if font_size == 0: 

320 min_font_size = 4.0 # The minimum font size 

321 if selection: # Don't wrap text when dealing with a /Ch field, in order to prevent problems 

322 is_multiline = False # with matching "selection" with "line" later on. 

323 if is_multiline: 

324 font_size = DEFAULT_FONT_SIZE_IN_MULTILINE 

325 # We create a list of paragraphs, here each paragraph is a list of tuples, where each WidthWordGlyphs 

326 # tuple signifies an unscaled word width, the word itself, and the glyphs that encode it. 

327 paragraphs: list[list[WidthWordGlyphs]] = [] 

328 for line in text.splitlines(): 

329 if not line.strip(): 

330 paragraphs.append([WidthWordGlyphs(width=0.0, word="", glyphs="")]) 

331 continue 

332 line_by_widths_words_glyphs: list[WidthWordGlyphs] = [] 

333 words = line.split(" ") 

334 for word in words: 

335 glyph_word = _unicode_to_glyph_id(word, reverse_cmap) 

336 line_by_widths_words_glyphs.append( 

337 WidthWordGlyphs( 

338 width=font.get_text_width(word) / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR, 

339 word=word, 

340 glyphs=glyph_word 

341 ) 

342 ) 

343 paragraphs.append(line_by_widths_words_glyphs) 

344 lines, font_size = self._scale_text( 

345 font, 

346 font_size, 

347 leading_factor, 

348 field_width, 

349 field_height, 

350 paragraphs, 

351 min_font_size 

352 ) 

353 else: 

354 max_vertical_size = field_height / leading_factor 

355 glyphs = _unicode_to_glyph_id(text, reverse_cmap) 

356 text_width_unscaled = font.get_text_width(glyphs) / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR 

357 max_horizontal_size = field_width / (text_width_unscaled or 1) 

358 font_size = round(max(min(max_vertical_size, max_horizontal_size), min_font_size), 1) 

359 lines = [WidthWordGlyphs(width=text_width_unscaled * font_size, word=text, glyphs=glyphs)] 

360 elif is_comb: 

361 if max_length and len(text) > max_length: 

362 logger_warning( 

363 ( 

364 "Length of text %(text)s exceeds maximum length (%(max_length)d) " 

365 "of field, input truncated." 

366 ), 

367 source=__name__, 

368 text=text, 

369 max_length=max_length, 

370 ) 

371 # We act as if each character is one line, because we draw it separately later on 

372 lines = [] 

373 for index, char in enumerate(text): 

374 if index < (max_length or len(text)): 

375 glyphs = _unicode_to_glyph_id(char, reverse_cmap) 

376 lines.append( 

377 WidthWordGlyphs( 

378 width=font.get_text_width(glyphs) * font_size / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR, 

379 word=char, 

380 glyphs=glyphs 

381 ) 

382 ) 

383 else: 

384 lines = [] 

385 for line in text.splitlines(): 

386 glyphs = _unicode_to_glyph_id(line, reverse_cmap) 

387 lines.append( 

388 WidthWordGlyphs( 

389 width=font.get_text_width(glyphs) * font_size / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR, 

390 word=line, 

391 glyphs=glyphs 

392 ) 

393 ) 

394 

395 # Set the vertical offset 

396 if is_multiline: 

397 y_offset = ( 

398 field_height + margin - font.font_descriptor.bbox[3] * font_size / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR 

399 ) 

400 else: 

401 y_offset = margin + ( 

402 (field_height - font.font_descriptor.ascent * font_size / TEXT_SPACE_TO_GLYPH_SPACE_FACTOR) / 2 

403 ) 

404 default_appearance = f"{font_name} {font_size} Tf {font_color.as_operator()}" 

405 

406 ap_stream = bytearray() 

407 ap_stream += ( 

408 f"q\n/Tx BMC \nq\n" 

409 f"{2 * max(margin, 1)} {margin} " 

410 f"{round(field_width - 2 * max(margin, 1), 3)} {round(field_height - margin, 3)} re\n" 

411 f"W\nBT\n{default_appearance}\n" 

412 ).encode() 

413 current_x_pos: float = 0 # Initial virtual position within the text object. 

414 

415 selection_glyphs = _unicode_to_glyph_id("".join(selection), reverse_cmap) if selection else "" 

416 for line_number, (line_width, original_text, line) in enumerate(lines): 

417 if selection_glyphs and line in selection_glyphs: 

418 # Might be improved, but cannot find how to get fill working => replaced with lined box 

419 ap_stream += ( 

420 f"1 {round(y_offset - (line_number * font_size * leading_factor) - 1, 3)} " 

421 f"{rectangle.width - 2} {font_size + 2} re\n" 

422 f"0.5 0.5 0.5 rg s\n{default_appearance}\n" 

423 ).encode() 

424 

425 # Calculate the desired absolute starting X for the current line 

426 desired_abs_x_start: float = 0 

427 if is_comb and max_length: 

428 # Calculate the width of a cell for one character 

429 cell_width = rectangle.width / max_length 

430 # Space from the left edge of the cell to the character's baseline start 

431 # line_width here is the *actual* character width in points for the single character 'line' 

432 centering_offset_in_cell = (cell_width - line_width) / 2 

433 # Absolute start X = (Cell Index, i.e., line_number * Cell Width) + Centering Offset 

434 desired_abs_x_start = (line_number * cell_width) + centering_offset_in_cell 

435 elif alignment == TextAlignment.RIGHT: 

436 desired_abs_x_start = rectangle.width - max(margin, 1) * 2 - line_width 

437 elif alignment == TextAlignment.CENTER: 

438 desired_abs_x_start = (rectangle.width - line_width) / 2 

439 else: # Left aligned; default 

440 desired_abs_x_start = max(margin, 1) * 2 

441 # Calculate x_rel_offset: how much to move from the current_x_pos 

442 # to reach the desired_abs_x_start. 

443 x_rel_offset = desired_abs_x_start - current_x_pos 

444 

445 # Y-offset: 

446 y_rel_offset: float = 0 

447 if line_number == 0: 

448 y_rel_offset = y_offset # Initial vertical position 

449 elif is_comb: 

450 y_rel_offset = 0.0 # DO NOT move vertically for subsequent characters 

451 else: 

452 y_rel_offset = - font_size * leading_factor # Move down by line height 

453 

454 # Td is a relative translation (Tx and Ty). 

455 # It updates the current text position. 

456 ap_stream += f"{round(x_rel_offset, 3)} {round(y_rel_offset, 3)} Td\n".encode() 

457 # Update current_x_pos based on the Td operation for the next iteration. 

458 # This is the X position where the *current line* will start. 

459 current_x_pos = desired_abs_x_start 

460 

461 is_rtl = any(is_char_rtl(char) for char in line) 

462 

463 encoded_line = _glyph_id_to_bytes(line, encoding_cmap) 

464 if is_rtl: 

465 # Encode input text as UTF-16BE with a BOM, so that the input text is returned 

466 # in the right direction when copying text from the resulting PDF 

467 bom_text = b"\xfe\xff" + original_text.encode("utf-16-be") 

468 hex_original_text = bom_text.hex().upper() 

469 ap_stream += f"/Span << /ActualText <{hex_original_text}> >> BDC\n".encode() 

470 if font.sub_type == "Type0": # 16-bit font 

471 ap_stream += b"<" + (b"".join(encoded_line)).hex().encode() + b"> Tj\n" 

472 else: # Simple font, 8-bit encoded. 

473 # Escape parentheses (PDF 1.7 reference, table 3.2, Literal Strings) 

474 line_as_bytes = ( 

475 b"".join(encoded_line) 

476 .replace(b"\\", b"\\\\") 

477 .replace(b"(", br"\(") 

478 .replace(b")", br"\)") 

479 ) 

480 ap_stream += b"(" + line_as_bytes + b") Tj\n" 

481 if is_rtl: 

482 ap_stream += b"EMC\n" 

483 ap_stream += b"ET\nQ\nEMC\nQ\n" 

484 

485 return bytes(ap_stream) 

486 

487 def __init__( 

488 self, 

489 layout: BaseStreamConfig | None = None, 

490 text: str = "", 

491 selection: list[str] | None = None, 

492 font: Font | None = None, 

493 font_resource: DictionaryObject | IndirectObject | None = None, 

494 font_name: str = "/Helv", 

495 font_size: float = 0.0, 

496 font_color: Color | None = None, 

497 is_multiline: bool = False, 

498 alignment: TextAlignment = TextAlignment.LEFT, 

499 is_comb: bool = False, 

500 max_length: int | None = None 

501 ) -> None: 

502 """ 

503 Initializes a TextStreamAppearance object. 

504 

505 This constructor creates a new PDF stream object configured as an XObject 

506 of subtype Form. It uses the `_generate_appearance_stream_data` method to 

507 generate the content for the stream. 

508 

509 Args: 

510 layout: The basic layout parameters. 

511 text: The text to be rendered in the form field. 

512 selection: An optional list of strings that should be highlighted as selected. 

513 font: A Font object. Falls back to Type 1 Helvetica if not given. 

514 font_resource: An optional variable that represents a PDF font dictionary. Falls back 

515 to Type 1 Helvetica if not given. 

516 font_name: The name of the font resource, e.g., "/Helv". 

517 font_size: The font size. If 0, it's auto-calculated. 

518 font_color: The font color string. 

519 is_multiline: A boolean indicating if the text field is multiline. 

520 alignment: Text alignment, can be TextAlignment.LEFT, .RIGHT, or .CENTER. 

521 is_comb: Boolean that designates fixed-length fields, where every character 

522 fills one "cell", such as in a postcode. 

523 max_length: Used if is_comb is set. The maximum number of characters for a fixed- 

524 length field. 

525 

526 """ 

527 super().__init__(layout) 

528 

529 if not font or not font_resource: 

530 font_name = "/Helv" 

531 font = Font.from_core_font_name() 

532 font_resource = font.as_font_resource() 

533 

534 self._ap_stream_data += self._generate_appearance_stream_data( 

535 text, 

536 selection, 

537 font, 

538 font_name=font_name, 

539 font_size=font_size, 

540 font_color=font_color or DeviceGray(), 

541 is_multiline=is_multiline, 

542 alignment=alignment, 

543 is_comb=is_comb, 

544 max_length=max_length 

545 ) 

546 

547 self.set_data(ByteStringObject(self._ap_stream_data)) 

548 self[NameObject("/Length")] = NumberObject(len(self._ap_stream_data)) 

549 # Update Resources with font information 

550 self[NameObject("/Resources")] = DictionaryObject({ 

551 NameObject("/Font"): DictionaryObject({ 

552 NameObject(font_name): getattr(font_resource, "indirect_reference", font_resource) 

553 }) 

554 }) 

555 

556 @staticmethod 

557 def _find_annotation_font_resource( 

558 font_name: str, 

559 annotation: DictionaryObject, 

560 acro_form: DictionaryObject, 

561 text: str 

562 ) -> tuple[str, Font]: 

563 # Try to find a resource dictionary for the font by examining the annotation and, if that fails, 

564 # the AcroForm resources dictionary 

565 acro_form_resources: Any = cast( 

566 DictionaryObject, 

567 annotation.get_inherited( 

568 "/DR", 

569 acro_form.get("/DR", DictionaryObject()), 

570 ), 

571 ) 

572 acro_form_font_resources = acro_form_resources.get("/Font", DictionaryObject()) 

573 font_resource = acro_form_font_resources.get(font_name, None) 

574 if font_resource: 

575 font = Font.from_font_resource(font_resource.get_object()) 

576 else: 

577 # Normally, we should have found a font resource by now. However, when a user has provided a specific 

578 # font name, we may not have found the associated font resource among the AcroForm resources. Also, in 

579 # case of the 14 Adobe Core fonts, we may be expected to construct a font resource ourselves. 

580 if font_name.removeprefix("/") not in CORE_FONT_METRICS: 

581 # Default to Helvetica if we haven't found a font resource and cannot construct one ourselves. 

582 logger_warning( 

583 "Font dictionary for %(font_name)s not found; defaulting to Helvetica.", 

584 source=__name__, 

585 font_name=font_name, 

586 ) 

587 font_name = "/Helvetica" 

588 font = Font.from_core_font_name(font_name) 

589 

590 # If we have found a font resource, it still might not be able to encode the text value we received. 

591 encodable = font.can_encode(text) 

592 

593 if not encodable: 

594 # If we have a font file, we can try to produce a new font resource with an encoding 

595 # that does include the necessary characters. We only try this for a TrueType font, meaning 

596 # that, in PDF terms, it is a simple, 8-bit encoded font. 

597 if font.font_descriptor.font_file and font.sub_type == "TrueType": 

598 try: 

599 font = font.from_truetype_font_file(BytesIO(font.font_descriptor.font_file.get_data())) 

600 font_name = "/PYPDF1" # This means we most probably do not clash with an existing font name 

601 encodable = font.can_encode(text) 

602 except (ImportError, PdfReadError) as exception: 

603 logger_warning( 

604 "Unable to use embedded font for encoding: %(exception)s", 

605 source=__name__, 

606 exception=exception, 

607 ) 

608 

609 # If it's one of the unembedded 14 Adobe Core Fonts, we can test other supported encodings 

610 elif font.sub_type == "Type1" and font.name in CORE_FONT_METRICS: 

611 core_font_metrics = CORE_FONT_METRICS[font.name] 

612 test_encodings = { 

613 "cp1250", # Central / Eastern European 

614 "cp1252", # Western European 

615 "cp1254", # Turkish 

616 "cp1257", # Baltic Rim 

617 "iso8859_15" # Western European ISO Alternate 

618 } 

619 for encoding in test_encodings: 

620 test_font = copy.copy(font) 

621 test_font.encoding = encoding_dict_from_named_encoding(encoding) 

622 encodable = test_font.can_encode(text) 

623 if encodable: 

624 font = test_font 

625 font.character_widths.clear() 

626 for code, character in test_font.encoding.items(): 

627 # Look up the width using the glyph name from the encoding 

628 if character in core_font_metrics.character_widths: 

629 font.character_widths[chr(code)] = core_font_metrics.character_widths[character] 

630 font.character_widths["default"] = core_font_metrics.character_widths["default"] 

631 font_name = "/PYPDF1" + encoding 

632 break 

633 

634 if not encodable: 

635 logger_warning( 

636 ( 

637 "Text string '%(text)s' contains characters not supported by font encoding. " 

638 "This may result in text corruption. " 

639 "Consider calling writer.update_page_form_field_values with auto_regenerate=True." 

640 ), 

641 source=__name__, 

642 text=text, 

643 ) 

644 

645 return font_name, font 

646 

647 @staticmethod 

648 def _sync_appearance_stream_font_resources( 

649 writer: PdfWriter, 

650 font_name: str, 

651 font: Font, 

652 target_resource_dict: DictionaryObject, 

653 page: PageObject | None = None 

654 ) -> IndirectObject: 

655 """ 

656 Unified helper to sync fonts from an AP stream to a target resource dictionary (e.g., AcroForm /DR). 

657 Will sync to page resources as well when page is added to the arguments. 

658 """ 

659 target_fonts = target_resource_dict.setdefault(NameObject("/Font"), DictionaryObject()).get_object() 

660 if font_name not in target_fonts: 

661 font_resource_reference = font._add_to_writer( 

662 writer, 

663 target_fonts, 

664 NameObject(font_name) 

665 ) 

666 else: 

667 font_resource_reference = target_fonts[font_name] 

668 

669 if page: 

670 page_fonts_resource = cast(DictionaryObject, page[PageAttributes.RESOURCES]).setdefault( 

671 NameObject("/Font"), DictionaryObject() 

672 ).get_object() 

673 if font_name not in page_fonts_resource: 

674 page_fonts_resource[NameObject(font_name)] = getattr( 

675 font_resource_reference, "indirect_reference", font_resource_reference 

676 ) 

677 

678 return font_resource_reference 

679 

680 @staticmethod 

681 def _parse_default_appearance( 

682 default_appearance: TextStringObject | ByteStringObject, 

683 ) -> tuple[str | None, float, Color | None]: 

684 """ 

685 Read the font name, font size and font color from a default appearance string. 

686 

687 A default appearance is a content stream fragment of graphics and text state operators, such as 

688 `/a1.0 gs 0 0 0 rg /Helv 10 Tf` (Section 12.7.4.3 "Variable text" of the PDF 2.0 specification). 

689 Where an operator occurs more than once, the last one is in effect. Operators other than `Tf` and 

690 the non-stroking color operators are ignored. 

691 

692 Args: 

693 default_appearance: The /DA string of a variable text field. 

694 

695 Returns: 

696 The font name and font size of the last complete Tf operator, or None and 0 if there is none, 

697 and the color of the last complete color operator, or None if there is none. 

698 """ 

699 stream = ContentStream(None, None) 

700 stream.set_data(default_appearance.original_bytes) 

701 try: 

702 operations = stream.operations 

703 except PdfReadError: 

704 # Ignore a malformed default appearance altogether. 

705 return None, 0.0, None 

706 

707 font_name: str | None = None 

708 font_size = 0.0 

709 font_color: Color | None = None 

710 for operands, operator in operations: 

711 if operator == b"Tf": 

712 if len(operands) == 2 and isinstance(operands[0], NameObject) and isinstance(operands[1], (int, float)): 

713 font_name, font_size = str(operands[0]), float(operands[1]) 

714 elif (color := Color.from_normalized_values(operands, operator.decode("latin-1"))) is not None: 

715 font_color = color 

716 return font_name, font_size, font_color 

717 

718 @classmethod 

719 def from_text_annotation( 

720 cls, 

721 writer: PdfWriter, 

722 page: PageObject, 

723 flatten: bool, 

724 acro_form: DictionaryObject, # _root_object[CatalogAttributes.ACRO_FORM]) 

725 field: DictionaryObject, 

726 annotation: DictionaryObject, 

727 user_font_name: str = "", 

728 user_font_size: float = -1, 

729 ) -> TextStreamAppearance: 

730 """ 

731 Creates a TextStreamAppearance object from a text field annotation. 

732 

733 This class method is a factory for creating a `TextStreamAppearance` 

734 instance by extracting all necessary information (bounding box, font, 

735 text content, etc.) from the PDF field and annotation dictionaries. 

736 It respects inheritance for properties like default appearance (`/DA`). 

737 

738 Args: 

739 writer: The PdfWriter instance that we are creating text stream appearances for. 

740 page: The page that we are processing annotations for. 

741 flatten: Whether we flatten text annotations or not. If true, add new font resource 

742 to the page font resources. Otherwise, add them to the AcroForm resources. 

743 acro_form: The root AcroForm dictionary from the PDF catalog. 

744 field: The field dictionary object. 

745 annotation: The widget annotation dictionary object associated with the field. 

746 user_font_name: An optional user-provided font name to override the 

747 default. Defaults to an empty string. 

748 user_font_size: An optional user-provided font size to override the 

749 default. A value of -1 indicates no override. 

750 

751 Returns: 

752 A new `TextStreamAppearance` instance configured for the given field. 

753 

754 """ 

755 # Calculate rectangle dimensions 

756 _rectangle = cast(RectangleObject, annotation[AnnotationDictionaryAttributes.Rect]) 

757 # Normalize the rectangle, apply page rotation if applicable 

758 if page.get_inherited("/Rotate") in {90, 270}: 

759 rectangle = RectangleObject((0, 0, abs(_rectangle[3] - _rectangle[1]), abs(_rectangle[2] - _rectangle[0]))) 

760 else: 

761 rectangle = RectangleObject((0, 0, abs(_rectangle[2] - _rectangle[0]), abs(_rectangle[3] - _rectangle[1]))) 

762 

763 # Get default appearance dictionary from annotation 

764 default_appearance = annotation.get_inherited( 

765 AnnotationDictionaryAttributes.DA, 

766 acro_form.get(AnnotationDictionaryAttributes.DA, None), 

767 ) 

768 if not default_appearance: 

769 # Create a default appearance if none was found in the annotation 

770 default_appearance = TextStringObject("/Helv 0 Tf 0 g") 

771 else: 

772 default_appearance = default_appearance.get_object() 

773 

774 # Retrieve field text and selected values 

775 field_flags = field.get(FieldDictionaryAttributes.Ff, 0) 

776 if ( 

777 field.get(FieldDictionaryAttributes.FT, "/Tx") == "/Ch" and 

778 field_flags & FieldDictionaryAttributes.FfBits.Combo == 0 

779 ): 

780 text = "\n".join(annotation.get_inherited(FieldDictionaryAttributes.Opt, [])) 

781 selection = field.get("/V", []) 

782 if not isinstance(selection, list): 

783 selection = [selection] 

784 else: # /Tx 

785 text = field.get("/V", "") 

786 selection = [] 

787 

788 # Derive font name, size and color from the default appearance. Also set 

789 # user-provided font name and font size in the default appearance, if given. 

790 # For a font name, this presumes that we can find an associated font resource 

791 # dictionary. 

792 # As per the PDF spec: 

793 # "At a minimum, the string [that is, default_appearance] shall include a Tf (text 

794 # font) operator along with its two operands, font and size" (Section 12.7.4.3 

795 # "Variable text" of the PDF 2.0 specification). 

796 da_font_name, font_size, font_color = cls._parse_default_appearance(default_appearance) 

797 if da_font_name is None: 

798 logger_warning( 

799 ( 

800 "Could not read a complete Tf operator from the default appearance %(default_appearance)r; " 

801 "defaulting to /Helv 0 Tf." 

802 ), 

803 source=__name__, 

804 default_appearance=str(default_appearance), 

805 ) 

806 da_font_name, font_size = "/Helv", 0.0 

807 # Determine the font name to use, prioritizing the user's input 

808 if user_font_name: 

809 font_name = user_font_name 

810 else: 

811 font_name = da_font_name 

812 # Determine the font size to use, prioritizing the user's input 

813 if user_font_size > 0: 

814 font_size = user_font_size 

815 

816 font_name, font = cls._find_annotation_font_resource(font_name, annotation, acro_form, text) 

817 

818 # Change the /DA information if we changed the font name 

819 if font_name != da_font_name: 

820 annotation[NameObject("/DA")] = TextStringObject(default_appearance.replace(da_font_name, font_name)) 

821 

822 # Synchronise font resources 

823 font_resource_reference = cls._sync_appearance_stream_font_resources( 

824 writer, 

825 font_name, 

826 font, 

827 acro_form.setdefault(NameObject("/DR"), DictionaryObject()), 

828 page if flatten else None, 

829 ) 

830 

831 # Retrieve formatting information 

832 is_comb = False 

833 max_length = None 

834 if field_flags & FieldDictionaryAttributes.FfBits.Comb: 

835 is_comb = True 

836 max_length = annotation.get("/MaxLen") 

837 is_multiline = False 

838 if field_flags & FieldDictionaryAttributes.FfBits.Multiline: 

839 is_multiline = True 

840 alignment = field.get("/Q", TextAlignment.LEFT) 

841 border_width = 1 

842 border_style = BorderStyles.SOLID 

843 if "/BS" in field: 

844 border_width = cast(DictionaryObject, field["/BS"]).get("/W", border_width) 

845 border_style = cast(DictionaryObject, field["/BS"]).get("/S", border_style) 

846 

847 rotation = 0 

848 border_color: Color | None = None 

849 background_color: Color | None = None 

850 appearance_characteristics = field.get_inherited("/MK", None) 

851 if isinstance(appearance_characteristics, DictionaryObject): 

852 rotation = int(appearance_characteristics.get("/R", 0)) 

853 # Color.from_normalized_values([]) results in None for a "/BC" or "/BG" value of []