Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/PIL/ImageFont.py: 37%

1# 

2# The Python Imaging Library. 

3# $Id$ 

4# 

5# PIL raster font management 

6# 

7# History: 

8# 1996-08-07 fl created (experimental) 

9# 1997-08-25 fl minor adjustments to handle fonts from pilfont 0.3 

10# 1999-02-06 fl rewrote most font management stuff in C 

11# 1999-03-17 fl take pth files into account in load_path (from Richard Jones) 

12# 2001-02-17 fl added freetype support 

13# 2001-05-09 fl added TransposedFont wrapper class 

14# 2002-03-04 fl make sure we have a "L" or "1" font 

15# 2002-12-04 fl skip non-directory entries in the system path 

16# 2003-04-29 fl add embedded default font 

17# 2003-09-27 fl added support for truetype charmap encodings 

18# 

19# Todo: 

20# Adapt to PILFONT2 format (16-bit fonts, compressed, single file) 

21# 

22# Copyright (c) 1997-2003 by Secret Labs AB 

23# Copyright (c) 1996-2003 by Fredrik Lundh 

24# 

25# See the README file for information on usage and redistribution. 

26# 

27 

28from __future__ import annotations 

29 

30import base64 

31import os 

32import sys 

33import warnings 

34from enum import IntEnum 

35from io import BytesIO 

36from types import ModuleType 

37from typing import IO, Any, BinaryIO, TypedDict, cast 

38 

39from . import Image 

40from ._typing import StrOrBytesPath 

41from ._util import DeferredError, is_path 

42 

43TYPE_CHECKING = False 

44if TYPE_CHECKING: 

45 from . import ImageFile 

46 from ._imaging import ImagingFont 

47 from ._imagingft import Font 

48 

49 

50class Axis(TypedDict): 

51 minimum: int | None 

52 default: int | None 

53 maximum: int | None 

54 name: bytes | None 

55 

56 

57class Layout(IntEnum): 

58 BASIC = 0 

59 RAQM = 1 

60 

61 

62MAX_STRING_LENGTH = 1_000_000 

63 

64 

65core: ModuleType | DeferredError 

66try: 

67 from . import _imagingft as core 

68except ImportError as ex: 

69 core = DeferredError.new(ex) 

70 

71 

72def _string_length_check(text: str | bytes | bytearray) -> None: 

73 if MAX_STRING_LENGTH is not None and len(text) > MAX_STRING_LENGTH: 

74 msg = "too many characters in string" 

75 raise ValueError(msg) 

76 

77 

78# FIXME: add support for pilfont2 format (see FontFile.py) 

79 

80# -------------------------------------------------------------------- 

81# Font metrics format: 

82# "PILfont" LF 

83# fontdescriptor LF 

84# (optional) key=value... LF 

85# "DATA" LF 

86# binary data: 256*10*2 bytes (dx, dy, dstbox, srcbox) 

87# 

88# To place a character, cut out srcbox and paste at dstbox, 

89# relative to the character position. Then move the character 

90# position according to dx, dy. 

91# -------------------------------------------------------------------- 

92 

93 

94class ImageFont: 

95 """PIL font wrapper""" 

96 

97 font: ImagingFont 

98 

99 def _load_pilfont(self, filename: str) -> None: 

100 with open(filename, "rb") as fp: 

101 image: ImageFile.ImageFile | None = None 

102 root = os.path.splitext(filename)[0] 

103 

104 for ext in (".png", ".gif", ".pbm"): 

105 if image: 

106 image.close() 

107 try: 

108 fullname = root + ext 

109 image = Image.open(fullname) 

110 except Exception: 

111 pass 

112 else: 

113 if image and image.mode in ("1", "L"): 

114 break 

115 else: 

116 if image: 

117 image.close() 

118 

119 msg = f"cannot find glyph data file {root}.{{gif|pbm|png}}" 

120 raise OSError(msg) 

121 

122 self.file = fullname 

123 

124 self._load_pilfont_data(fp, image) 

125 image.close() 

126 

127 def _load_pilfont_data(self, file: IO[bytes], image: Image.Image) -> None: 

128 # check image 

129 if image.mode not in ("1", "L"): 

130 image.close() 

131 

132 msg = "invalid font image mode" 

133 raise TypeError(msg) 

134 

135 # read PILfont header 

136 if file.read(8) != b"PILfont\n": 

137 image.close() 

138 

139 msg = "Not a PILfont file" 

140 raise SyntaxError(msg) 

141 file.readline() 

142 self.info = [] # FIXME: should be a dictionary 

143 while True: 

144 s = file.readline() 

145 if not s or s == b"DATA\n": 

146 break 

147 self.info.append(s) 

148 

149 # read PILfont metrics 

150 data = file.read(256 * 20) 

151 

152 image.load() 

153 

154 self.font = Image.core.font(image.im, data) 

155 

156 def getmask( 

157 self, text: str | bytes, mode: str = "", *args: Any, **kwargs: Any 

158 ) -> Image.core.ImagingCore: 

159 """ 

160 Create a bitmap for the text. 

161 

162 If the font uses antialiasing, the bitmap should have mode ``L`` and use a 

163 maximum value of 255. Otherwise, it should have mode ``1``. 

164 

165 :param text: Text to render. 

166 :param mode: Used by some graphics drivers to indicate what mode the 

167 driver prefers; if empty, the renderer may return either 

168 mode. Note that the mode is always a string, to simplify 

169 C-level implementations. 

170 

171 .. versionadded:: 1.1.5 

172 

173 :return: An internal PIL storage memory instance as defined by the 

174 :py:mod:`PIL.Image.core` interface module. 

175 """ 

176 _string_length_check(text) 

177 Image._decompression_bomb_check(self.font.getsize(text)) 

178 return self.font.getmask(text, mode) 

179 

180 def getbbox( 

181 self, text: str | bytes | bytearray, *args: Any, **kwargs: Any 

182 ) -> tuple[int, int, int, int]: 

183 """ 

184 Returns bounding box (in pixels) of given text. 

185 

186 .. versionadded:: 9.2.0 

187 

188 :param text: Text to render. 

189 

190 :return: ``(left, top, right, bottom)`` bounding box 

191 """ 

192 _string_length_check(text) 

193 width, height = self.font.getsize(text) 

194 return 0, 0, width, height 

195 

196 def getlength( 

197 self, text: str | bytes | bytearray, *args: Any, **kwargs: Any 

198 ) -> int: 

199 """ 

200 Returns length (in pixels) of given text. 

201 This is the amount by which following text should be offset. 

202 

203 .. versionadded:: 9.2.0 

204 """ 

205 _string_length_check(text) 

206 width, height = self.font.getsize(text) 

207 return width 

208 

209 

210## 

211# Wrapper for FreeType fonts. Application code should use the 

212# <b>truetype</b> factory function to create font objects. 

213 

214 

215class FreeTypeFont: 

216 """FreeType font wrapper (requires _imagingft service)""" 

217 

218 font: Font 

219 font_bytes: bytes 

220 

221 def __init__( 

222 self, 

223 font: StrOrBytesPath | BinaryIO, 

224 size: float = 10, 

225 index: int = 0, 

226 encoding: str = "", 

227 layout_engine: Layout | None = None, 

228 ) -> None: 

229 # FIXME: use service provider instead 

230 

231 if isinstance(core, DeferredError): 

232 raise core.ex 

233 

234 if size <= 0: 

235 msg = f"font size must be greater than 0, not {size}" 

236 raise ValueError(msg) 

237 

238 self.path = font 

239 self.size = size 

240 self.index = index 

241 self.encoding = encoding 

242 

243 if layout_engine not in (Layout.BASIC, Layout.RAQM): 

244 layout_engine = Layout.BASIC 

245 if core.HAVE_RAQM: 

246 layout_engine = Layout.RAQM 

247 elif layout_engine == Layout.RAQM and not core.HAVE_RAQM: 

248 warnings.warn( 

249 "Raqm layout was requested, but Raqm is not available. " 

250 "Falling back to basic layout." 

251 ) 

252 layout_engine = Layout.BASIC 

253 

254 self.layout_engine = layout_engine 

255 

256 def load_from_bytes(f: IO[bytes]) -> None: 

257 self.font_bytes = f.read() 

258 self.font = core.getfont( 

259 "", size, index, encoding, self.font_bytes, layout_engine 

260 ) 

261 

262 if is_path(font): 

263 font = os.fspath(font) 

264 if sys.platform == "win32": 

265 font_bytes_path = font if isinstance(font, bytes) else font.encode() 

266 try: 

267 font_bytes_path.decode("ascii") 

268 except UnicodeDecodeError: 

269 # FreeType cannot load fonts with non-ASCII characters on Windows 

270 # So load it into memory first 

271 with open(font, "rb") as f: 

272 load_from_bytes(f) 

273 return 

274 self.font = core.getfont( 

275 font, size, index, encoding, layout_engine=layout_engine 

276 ) 

277 else: 

278 load_from_bytes(cast(IO[bytes], font)) 

279 

280 def __getstate__(self) -> list[Any]: 

281 return [self.path, self.size, self.index, self.encoding, self.layout_engine] 

282 

283 def __setstate__(self, state: list[Any]) -> None: 

284 path, size, index, encoding, layout_engine = state 

285 FreeTypeFont.__init__(self, path, size, index, encoding, layout_engine) 

286 

287 def getname(self) -> tuple[str | None, str | None]: 

288 """ 

289 :return: A tuple of the font family (e.g. Helvetica) and the font style 

290 (e.g. Bold) 

291 """ 

292 return self.font.family, self.font.style 

293 

294 def getmetrics(self) -> tuple[int, int]: 

295 """ 

296 :return: A tuple of the font ascent (the distance from the baseline to 

297 the highest outline point) and descent (the distance from the 

298 baseline to the lowest outline point, a negative value) 

299 """ 

300 return self.font.ascent, self.font.descent 

301 

302 def getlength( 

303 self, 

304 text: str | bytes, 

305 mode: str = "", 

306 direction: str | None = None, 

307 features: list[str] | None = None, 

308 language: str | None = None, 

309 ) -> float: 

310 """ 

311 Returns length (in pixels with 1/64 precision) of given text when rendered 

312 in font with provided direction, features, and language. 

313 

314 This is the amount by which following text should be offset. 

315 Text bounding box may extend past the length in some fonts, 

316 e.g. when using italics or accents. 

317 

318 The result is returned as a float; it is a whole number if using basic layout. 

319 

320 Note that the sum of two lengths may not equal the length of a concatenated 

321 string due to kerning. If you need to adjust for kerning, include the following 

322 character and subtract its length. 

323 

324 For example, instead of :: 

325 

326 hello = font.getlength("Hello") 

327 world = font.getlength("World") 

328 hello_world = hello + world # not adjusted for kerning 

329 assert hello_world == font.getlength("HelloWorld") # may fail 

330 

331 use :: 

332 

333 hello = font.getlength("HelloW") - font.getlength("W") # adjusted for kerning 

334 world = font.getlength("World") 

335 hello_world = hello + world # adjusted for kerning 

336 assert hello_world == font.getlength("HelloWorld") # True 

337 

338 or disable kerning with (requires libraqm) :: 

339 

340 hello = draw.textlength("Hello", font, features=["-kern"]) 

341 world = draw.textlength("World", font, features=["-kern"]) 

342 hello_world = hello + world # kerning is disabled, no need to adjust 

343 assert hello_world == draw.textlength("HelloWorld", font, features=["-kern"]) 

344 

345 .. versionadded:: 8.0.0 

346 

347 :param text: Text to measure. 

348 :param mode: Used by some graphics drivers to indicate what mode the 

349 driver prefers; if empty, the renderer may return either 

350 mode. Note that the mode is always a string, to simplify 

351 C-level implementations. 

352 

353 :param direction: Direction of the text. It can be 'rtl' (right to 

354 left), 'ltr' (left to right) or 'ttb' (top to bottom). 

355 Requires libraqm. 

356 

357 :param features: A list of OpenType font features to be used during text 

358 layout. This is usually used to turn on optional 

359 font features that are not enabled by default, 

360 for example 'dlig' or 'ss01', but can be also 

361 used to turn off default font features for 

362 example '-liga' to disable ligatures or '-kern' 

363 to disable kerning. To get all supported 

364 features, see 

365 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 

366 Requires libraqm. 

367 

368 :param language: Language of the text. Different languages may use 

369 different glyph shapes or ligatures. This parameter tells 

370 the font which language the text is in, and to apply the 

371 correct substitutions as appropriate, if available. 

372 It should be a `BCP 47 language code 

373 <https://www.w3.org/International/articles/language-tags/>`_ 

374 Requires libraqm. 

375 

376 :return: Either width for horizontal text, or height for vertical text. 

377 """ 

378 _string_length_check(text) 

379 return self.font.getlength(text, mode, direction, features, language) / 64 

380 

381 def getbbox( 

382 self, 

383 text: str | bytes, 

384 mode: str = "", 

385 direction: str | None = None, 

386 features: list[str] | None = None, 

387 language: str | None = None, 

388 stroke_width: float = 0, 

389 anchor: str | None = None, 

390 ) -> tuple[float, float, float, float]: 

391 """ 

392 Returns bounding box (in pixels) of given text relative to given anchor 

393 when rendered in font with provided direction, features, and language. 

394 

395 Use :py:meth:`getlength()` to get the offset of following text with 

396 1/64 pixel precision. The bounding box includes extra margins for 

397 some fonts, e.g. italics or accents. 

398 

399 .. versionadded:: 8.0.0 

400 

401 :param text: Text to render. 

402 :param mode: Used by some graphics drivers to indicate what mode the 

403 driver prefers; if empty, the renderer may return either 

404 mode. Note that the mode is always a string, to simplify 

405 C-level implementations. 

406 

407 :param direction: Direction of the text. It can be 'rtl' (right to 

408 left), 'ltr' (left to right) or 'ttb' (top to bottom). 

409 Requires libraqm. 

410 

411 :param features: A list of OpenType font features to be used during text 

412 layout. This is usually used to turn on optional 

413 font features that are not enabled by default, 

414 for example 'dlig' or 'ss01', but can be also 

415 used to turn off default font features for 

416 example '-liga' to disable ligatures or '-kern' 

417 to disable kerning. To get all supported 

418 features, see 

419 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 

420 Requires libraqm. 

421 

422 :param language: Language of the text. Different languages may use 

423 different glyph shapes or ligatures. This parameter tells 

424 the font which language the text is in, and to apply the 

425 correct substitutions as appropriate, if available. 

426 It should be a `BCP 47 language code 

427 <https://www.w3.org/International/articles/language-tags/>`_ 

428 Requires libraqm. 

429 

430 :param stroke_width: The width of the text stroke. 

431 

432 :param anchor: The text anchor alignment. Determines the relative location of 

433 the anchor to the text. The default alignment is top left, 

434 specifically ``la`` for horizontal text and ``lt`` for 

435 vertical text. See :ref:`text-anchors` for details. 

436 

437 :return: ``(left, top, right, bottom)`` bounding box 

438 """ 

439 _string_length_check(text) 

440 size, offset = self.font.getsize( 

441 text, mode, direction, features, language, anchor 

442 ) 

443 left, top = offset[0] - stroke_width, offset[1] - stroke_width 

444 width, height = size[0] + 2 * stroke_width, size[1] + 2 * stroke_width 

445 return left, top, left + width, top + height 

446 

447 def getmask( 

448 self, 

449 text: str | bytes, 

450 mode: str = "", 

451 direction: str | None = None, 

452 features: list[str] | None = None, 

453 language: str | None = None, 

454 stroke_width: float = 0, 

455 anchor: str | None = None, 

456 ink: int = 0, 

457 start: tuple[float, float] | None = None, 

458 ) -> Image.core.ImagingCore: 

459 """ 

460 Create a bitmap for the text. 

461 

462 If the font uses antialiasing, the bitmap should have mode ``L`` and use a 

463 maximum value of 255. If the font has embedded color data, the bitmap 

464 should have mode ``RGBA``. Otherwise, it should have mode ``1``. 

465 

466 :param text: Text to render. 

467 :param mode: Used by some graphics drivers to indicate what mode the 

468 driver prefers; if empty, the renderer may return either 

469 mode. Note that the mode is always a string, to simplify 

470 C-level implementations. 

471 

472 .. versionadded:: 1.1.5 

473 

474 :param direction: Direction of the text. It can be 'rtl' (right to 

475 left), 'ltr' (left to right) or 'ttb' (top to bottom). 

476 Requires libraqm. 

477 

478 .. versionadded:: 4.2.0 

479 

480 :param features: A list of OpenType font features to be used during text 

481 layout. This is usually used to turn on optional 

482 font features that are not enabled by default, 

483 for example 'dlig' or 'ss01', but can be also 

484 used to turn off default font features for 

485 example '-liga' to disable ligatures or '-kern' 

486 to disable kerning. To get all supported 

487 features, see 

488 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 

489 Requires libraqm. 

490 

491 .. versionadded:: 4.2.0 

492 

493 :param language: Language of the text. Different languages may use 

494 different glyph shapes or ligatures. This parameter tells 

495 the font which language the text is in, and to apply the 

496 correct substitutions as appropriate, if available. 

497 It should be a `BCP 47 language code 

498 <https://www.w3.org/International/articles/language-tags/>`_ 

499 Requires libraqm. 

500 

501 .. versionadded:: 6.0.0 

502 

503 :param stroke_width: The width of the text stroke. 

504 

505 .. versionadded:: 6.2.0 

506 

507 :param anchor: The text anchor alignment. Determines the relative location of 

508 the anchor to the text. The default alignment is top left, 

509 specifically ``la`` for horizontal text and ``lt`` for 

510 vertical text. See :ref:`text-anchors` for details. 

511 

512 .. versionadded:: 8.0.0 

513 

514 :param ink: Foreground ink for rendering in RGBA mode. 

515 

516 .. versionadded:: 8.0.0 

517 

518 :param start: Tuple of horizontal and vertical offset, as text may render 

519 differently when starting at fractional coordinates. 

520 

521 .. versionadded:: 9.4.0 

522 

523 :return: An internal PIL storage memory instance as defined by the 

524 :py:mod:`PIL.Image.core` interface module. 

525 """ 

526 return self.getmask2( 

527 text, 

528 mode, 

529 direction=direction, 

530 features=features, 

531 language=language, 

532 stroke_width=stroke_width, 

533 anchor=anchor, 

534 ink=ink, 

535 start=start, 

536 )[0] 

537 

538 def getmask2( 

539 self, 

540 text: str | bytes, 

541 mode: str = "", 

542 direction: str | None = None, 

543 features: list[str] | None = None, 

544 language: str | None = None, 

545 stroke_width: float = 0, 

546 anchor: str | None = None, 

547 ink: int = 0, 

548 start: tuple[float, float] | None = None, 

549 *args: Any, 

550 **kwargs: Any, 

551 ) -> tuple[Image.core.ImagingCore, tuple[int, int]]: 

552 """ 

553 Create a bitmap for the text. 

554 

555 If the font uses antialiasing, the bitmap should have mode ``L`` and use a 

556 maximum value of 255. If the font has embedded color data, the bitmap 

557 should have mode ``RGBA``. Otherwise, it should have mode ``1``. 

558 

559 :param text: Text to render. 

560 :param mode: Used by some graphics drivers to indicate what mode the 

561 driver prefers; if empty, the renderer may return either 

562 mode. Note that the mode is always a string, to simplify 

563 C-level implementations. 

564 

565 .. versionadded:: 1.1.5 

566 

567 :param direction: Direction of the text. It can be 'rtl' (right to 

568 left), 'ltr' (left to right) or 'ttb' (top to bottom). 

569 Requires libraqm. 

570 

571 .. versionadded:: 4.2.0 

572 

573 :param features: A list of OpenType font features to be used during text 

574 layout. This is usually used to turn on optional 

575 font features that are not enabled by default, 

576 for example 'dlig' or 'ss01', but can be also 

577 used to turn off default font features for 

578 example '-liga' to disable ligatures or '-kern' 

579 to disable kerning. To get all supported 

580 features, see 

581 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 

582 Requires libraqm. 

583 

584 .. versionadded:: 4.2.0 

585 

586 :param language: Language of the text. Different languages may use 

587 different glyph shapes or ligatures. This parameter tells 

588 the font which language the text is in, and to apply the 

589 correct substitutions as appropriate, if available. 

590 It should be a `BCP 47 language code 

591 <https://www.w3.org/International/articles/language-tags/>`_ 

592 Requires libraqm. 

593 

594 .. versionadded:: 6.0.0 

595 

596 :param stroke_width: The width of the text stroke. 

597 

598 .. versionadded:: 6.2.0 

599 

600 :param anchor: The text anchor alignment. Determines the relative location of 

601 the anchor to the text. The default alignment is top left, 

602 specifically ``la`` for horizontal text and ``lt`` for 

603 vertical text. See :ref:`text-anchors` for details. 

604 

605 .. versionadded:: 8.0.0 

606 

607 :param ink: Foreground ink for rendering in RGBA mode. 

608 

609 .. versionadded:: 8.0.0 

610 

611 :param start: Tuple of horizontal and vertical offset, as text may render 

612 differently when starting at fractional coordinates. 

613 

614 .. versionadded:: 9.4.0 

615 

616 :return: A tuple of an internal PIL storage memory instance as defined by the 

617 :py:mod:`PIL.Image.core` interface module, and the text offset, the 

618 gap between the starting coordinate and the first marking 

619 """ 

620 _string_length_check(text) 

621 if start is None: 

622 start = (0, 0) 

623 

624 def fill(width: int, height: int) -> Image.core.ImagingCore: 

625 size = (width, height) 

626 Image._decompression_bomb_check(size) 

627 return Image.core.fill("RGBA" if mode == "RGBA" else "L", size) 

628 

629 return self.font.render( 

630 text, 

631 fill, 

632 mode, 

633 direction, 

634 features, 

635 language, 

636 stroke_width, 

637 kwargs.get("stroke_filled", False), 

638 anchor, 

639 ink, 

640 start, 

641 ) 

642 

643 def font_variant( 

644 self, 

645 font: StrOrBytesPath | BinaryIO | None = None, 

646 size: float | None = None, 

647 index: int | None = None, 

648 encoding: str | None = None, 

649 layout_engine: Layout | None = None, 

650 ) -> FreeTypeFont: 

651 """ 

652 Create a copy of this FreeTypeFont object, 

653 using any specified arguments to override the settings. 

654 

655 Parameters are identical to the parameters used to initialize this 

656 object. 

657 

658 :return: A FreeTypeFont object. 

659 """ 

660 if font is None: 

661 try: 

662 font = BytesIO(self.font_bytes) 

663 except AttributeError: 

664 font = self.path 

665 return FreeTypeFont( 

666 font=font, 

667 size=self.size if size is None else size, 

668 index=self.index if index is None else index, 

669 encoding=self.encoding if encoding is None else encoding, 

670 layout_engine=layout_engine or self.layout_engine, 

671 ) 

672 

673 def get_variation_names(self) -> list[bytes]: 

674 """ 

675 :returns: A list of the named styles in a variation font. 

676 :exception OSError: If the font is not a variation font. 

677 """ 

678 names = [] 

679 for name in self.font.getvarnames(): 

680 name = name.replace(b"\x00", b"") 

681 if name not in names: 

682 names.append(name) 

683 return names 

684 

685 def set_variation_by_name(self, name: str | bytes) -> None: 

686 """ 

687 :param name: The name of the style. 

688 :exception OSError: If the font is not a variation font. 

689 """ 

690 names = self.get_variation_names() 

691 if not isinstance(name, bytes): 

692 name = name.encode() 

693 index = names.index(name) + 1 

694 

695 if index == getattr(self, "_last_variation_index", None): 

696 # When the same name is set twice in a row, 

697 # there is an 'unknown freetype error' 

698 # https://savannah.nongnu.org/bugs/?56186 

699 return 

700 self._last_variation_index = index 

701 

702 self.font.setvarname(index) 

703 

704 def get_variation_axes(self) -> list[Axis]: 

705 """ 

706 :returns: A list of the axes in a variation font. 

707 :exception OSError: If the font is not a variation font. 

708 """ 

709 axes = self.font.getvaraxes() 

710 for axis in axes: 

711 if axis["name"]: 

712 axis["name"] = axis["name"].replace(b"\x00", b"") 

713 return axes 

714 

715 def set_variation_by_axes(self, axes: list[float]) -> None: 

716 """ 

717 :param axes: A list of values for each axis. 

718 :exception OSError: If the font is not a variation font. 

719 """ 

720 self.font.setvaraxes(axes) 

721 

722 

723class TransposedFont: 

724 """Wrapper for writing rotated or mirrored text""" 

725 

726 def __init__( 

727 self, font: ImageFont | FreeTypeFont, orientation: Image.Transpose | None = None 

728 ): 

729 """ 

730 Wrapper that creates a transposed font from any existing font 

731 object. 

732 

733 :param font: A font object. 

734 :param orientation: An optional orientation. If given, this should 

735 be one of Image.Transpose.FLIP_LEFT_RIGHT, Image.Transpose.FLIP_TOP_BOTTOM, 

736 Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_180, or 

737 Image.Transpose.ROTATE_270. 

738 """ 

739 self.font = font 

740 self.orientation = orientation # any 'transpose' argument, or None 

741 

742 def getmask( 

743 self, text: str | bytes, mode: str = "", *args: Any, **kwargs: Any 

744 ) -> Image.core.ImagingCore: 

745 im = self.font.getmask(text, mode, *args, **kwargs) 

746 if self.orientation is not None: 

747 return im.transpose(self.orientation) 

748 return im 

749 

750 def getbbox( 

751 self, text: str | bytes, *args: Any, **kwargs: Any 

752 ) -> tuple[int, int, float, float]: 

753 # TransposedFont doesn't support getmask2, move top-left point to (0, 0) 

754 # this has no effect on ImageFont and simulates anchor="lt" for FreeTypeFont 

755 left, top, right, bottom = self.font.getbbox(text, *args, **kwargs) 

756 width = right - left 

757 height = bottom - top 

758 if self.orientation in (Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_270): 

759 return 0, 0, height, width 

760 return 0, 0, width, height 

761 

762 def getlength(self, text: str | bytes, *args: Any, **kwargs: Any) -> float: 

763 if self.orientation in (Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_270): 

764 msg = "text length is undefined for text rotated by 90 or 270 degrees" 

765 raise ValueError(msg) 

766 return self.font.getlength(text, *args, **kwargs) 

767 

768 

769def load(filename: str) -> ImageFont: 

770 """ 

771 Load a font file. This function loads a font object from the given 

772 bitmap font file, and returns the corresponding font object. For loading TrueType 

773 or OpenType fonts instead, see :py:func:`~PIL.ImageFont.truetype`. 

774 

775 :param filename: Name of font file. 

776 :return: A font object. 

777 :exception OSError: If the file could not be read. 

778 """ 

779 f = ImageFont() 

780 f._load_pilfont(filename) 

781 return f 

782 

783 

784def truetype( 

785 font: StrOrBytesPath | BinaryIO, 

786 size: float = 10, 

787 index: int = 0, 

788 encoding: str = "", 

789 layout_engine: Layout | None = None, 

790) -> FreeTypeFont: 

791 """ 

792 Load a TrueType or OpenType font from a file or file-like object, 

793 and create a font object. This function loads a font object from the given 

794 file or file-like object, and creates a font object for a font of the given 

795 size. For loading bitmap fonts instead, see :py:func:`~PIL.ImageFont.load` 

796 and :py:func:`~PIL.ImageFont.load_path`. 

797 

798 Pillow uses FreeType to open font files. On Windows, be aware that FreeType 

799 will keep the file open as long as the FreeTypeFont object exists. Windows 

800 limits the number of files that can be open in C at once to 512, so if many 

801 fonts are opened simultaneously and that limit is approached, an 

802 ``OSError`` may be thrown, reporting that FreeType "cannot open resource". 

803 A workaround would be to copy the file(s) into memory, and open that instead. 

804 

805 This function requires the _imagingft service. 

806 

807 :param font: A filename or file-like object containing a TrueType font. 

808 If the file is not found in this filename, the loader may also 

809 search in other directories, such as: 

810 

811 * The :file:`fonts/` directory on Windows, 

812 * :file:`/Library/Fonts/`, :file:`/System/Library/Fonts/` 

813 and :file:`~/Library/Fonts/` on macOS. 

814 * :file:`~/.local/share/fonts`, :file:`/usr/local/share/fonts`, 

815 and :file:`/usr/share/fonts` on Linux; or those specified by 

816 the ``XDG_DATA_HOME`` and ``XDG_DATA_DIRS`` environment variables 

817 for user-installed and system-wide fonts, respectively. 

818 

819 :param size: The requested size, in pixels. 

820 :param index: Which font face to load (default is first available face). 

821 :param encoding: Which font encoding to use (default is Unicode). Possible 

822 encodings include (see the FreeType documentation for more 

823 information): 

824 

825 * "unic" (Unicode) 

826 * "symb" (Microsoft Symbol) 

827 * "ADOB" (Adobe Standard) 

828 * "ADBE" (Adobe Expert) 

829 * "ADBC" (Adobe Custom) 

830 * "armn" (Apple Roman) 

831 * "sjis" (Shift JIS) 

832 * "gb " (PRC) 

833 * "big5" 

834 * "wans" (Extended Wansung) 

835 * "joha" (Johab) 

836 * "lat1" (Latin-1) 

837 

838 This specifies the character set to use. It does not alter the 

839 encoding of any text provided in subsequent operations. 

840 :param layout_engine: Which layout engine to use, if available: 

841 :attr:`.ImageFont.Layout.BASIC` or :attr:`.ImageFont.Layout.RAQM`. 

842 If it is available, Raqm layout will be used by default. 

843 Otherwise, basic layout will be used. 

844 

845 Raqm layout is recommended for all non-English text. If Raqm layout 

846 is not required, basic layout will have better performance. 

847 

848 You can check support for Raqm layout using 

849 :py:func:`PIL.features.check_feature` with ``feature="raqm"``. 

850 

851 .. versionadded:: 4.2.0 

852 :return: A font object. 

853 :exception OSError: If the file could not be read. 

854 :exception ValueError: If the font size is not greater than zero. 

855 """ 

856 

857 def freetype(font: StrOrBytesPath | BinaryIO) -> FreeTypeFont: 

858 return FreeTypeFont(font, size, index, encoding, layout_engine) 

859 

860 try: 

861 return freetype(font) 

862 except OSError: 

863 if not is_path(font): 

864 raise 

865 ttf_filename = os.path.basename(font) 

866 

867 dirs = [] 

868 if sys.platform == "win32": 

869 # check the windows font repository 

870 # NOTE: must use uppercase WINDIR, to work around bugs in 

871 # 1.5.2's os.environ.get() 

872 windir = os.environ.get("WINDIR") 

873 if windir: 

874 dirs.append(os.path.join(windir, "fonts")) 

875 elif sys.platform in ("linux", "linux2"): 

876 data_home = os.environ.get("XDG_DATA_HOME") 

877 if not data_home: 

878 # The freedesktop spec defines the following default directory for 

879 # when XDG_DATA_HOME is unset or empty. This user-level directory 

880 # takes precedence over system-level directories. 

881 data_home = os.path.expanduser("~/.local/share") 

882 xdg_dirs = [data_home] 

883 

884 data_dirs = os.environ.get("XDG_DATA_DIRS") 

885 if not data_dirs: 

886 # Similarly, defaults are defined for the system-level directories 

887 data_dirs = "/usr/local/share:/usr/share" 

888 xdg_dirs += data_dirs.split(":") 

889 

890 dirs += [os.path.join(xdg_dir, "fonts") for xdg_dir in xdg_dirs] 

891 elif sys.platform == "darwin": 

892 dirs += [ 

893 "/Library/Fonts", 

894 "/System/Library/Fonts", 

895 os.path.expanduser("~/Library/Fonts"), 

896 ] 

897 

898 ext = os.path.splitext(ttf_filename)[1] 

899 first_font_with_a_different_extension = None 

900 for directory in dirs: 

901 for walkroot, walkdir, walkfilenames in os.walk(directory): 

902 for walkfilename in walkfilenames: 

903 if ext and walkfilename == ttf_filename: 

904 return freetype(os.path.join(walkroot, walkfilename)) 

905 elif not ext and os.path.splitext(walkfilename)[0] == ttf_filename: 

906 fontpath = os.path.join(walkroot, walkfilename) 

907 if os.path.splitext(fontpath)[1] == ".ttf": 

908 return freetype(fontpath) 

909 if not ext and first_font_with_a_different_extension is None: 

910 first_font_with_a_different_extension = fontpath 

911 if first_font_with_a_different_extension: 

912 return freetype(first_font_with_a_different_extension) 

913 raise 

914 

915 

916def load_path(filename: str | bytes) -> ImageFont: 

917 """ 

918 Load font file. Same as :py:func:`~PIL.ImageFont.load`, but searches for a 

919 bitmap font along the Python path. 

920 

921 :param filename: Name of font file. 

922 :return: A font object. 

923 :exception OSError: If the file could not be read. 

924 """ 

925 if not isinstance(filename, str): 

926 filename = filename.decode("utf-8") 

927 for directory in sys.path: 

928 try: 

929 return load(os.path.join(directory, filename)) 

930 except OSError: 

931 pass 

932 msg = f'cannot find font file "{filename}" in sys.path' 

933 if os.path.exists(filename): 

934 msg += f', did you mean ImageFont.load("{filename}") instead?' 

935 

936 raise OSError(msg) 

937 

938 

939def load_default_imagefont() -> ImageFont: 

940 f = ImageFont() 

941 f._load_pilfont_data( 

942 # courB08 

943 BytesIO(base64.b64decode(b""" 

944UElMZm9udAo7Ozs7OzsxMDsKREFUQQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

945AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

946AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

947AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

948AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

949AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

950AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

951AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

952AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

953AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

954AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

955AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYAAAAA//8AAQAAAAAAAAABAAEA 

956BgAAAAH/+gADAAAAAQAAAAMABgAGAAAAAf/6AAT//QADAAAABgADAAYAAAAA//kABQABAAYAAAAL 

957AAgABgAAAAD/+AAFAAEACwAAABAACQAGAAAAAP/5AAUAAAAQAAAAFQAHAAYAAP////oABQAAABUA 

958AAAbAAYABgAAAAH/+QAE//wAGwAAAB4AAwAGAAAAAf/5AAQAAQAeAAAAIQAIAAYAAAAB//kABAAB 

959ACEAAAAkAAgABgAAAAD/+QAE//0AJAAAACgABAAGAAAAAP/6AAX//wAoAAAALQAFAAYAAAAB//8A 

960BAACAC0AAAAwAAMABgAAAAD//AAF//0AMAAAADUAAQAGAAAAAf//AAMAAAA1AAAANwABAAYAAAAB 

961//kABQABADcAAAA7AAgABgAAAAD/+QAFAAAAOwAAAEAABwAGAAAAAP/5AAYAAABAAAAARgAHAAYA 

962AAAA//kABQAAAEYAAABLAAcABgAAAAD/+QAFAAAASwAAAFAABwAGAAAAAP/5AAYAAABQAAAAVgAH 

963AAYAAAAA//kABQAAAFYAAABbAAcABgAAAAD/+QAFAAAAWwAAAGAABwAGAAAAAP/5AAUAAABgAAAA 

964ZQAHAAYAAAAA//kABQAAAGUAAABqAAcABgAAAAD/+QAFAAAAagAAAG8ABwAGAAAAAf/8AAMAAABv 

965AAAAcQAEAAYAAAAA//wAAwACAHEAAAB0AAYABgAAAAD/+gAE//8AdAAAAHgABQAGAAAAAP/7AAT/ 

966/gB4AAAAfAADAAYAAAAB//oABf//AHwAAACAAAUABgAAAAD/+gAFAAAAgAAAAIUABgAGAAAAAP/5 

967AAYAAQCFAAAAiwAIAAYAAP////oABgAAAIsAAACSAAYABgAA////+gAFAAAAkgAAAJgABgAGAAAA 

968AP/6AAUAAACYAAAAnQAGAAYAAP////oABQAAAJ0AAACjAAYABgAA////+gAFAAAAowAAAKkABgAG 

969AAD////6AAUAAACpAAAArwAGAAYAAAAA//oABQAAAK8AAAC0AAYABgAA////+gAGAAAAtAAAALsA 

970BgAGAAAAAP/6AAQAAAC7AAAAvwAGAAYAAP////oABQAAAL8AAADFAAYABgAA////+gAGAAAAxQAA 

971AMwABgAGAAD////6AAUAAADMAAAA0gAGAAYAAP////oABQAAANIAAADYAAYABgAA////+gAGAAAA 

9722AAAAN8ABgAGAAAAAP/6AAUAAADfAAAA5AAGAAYAAP////oABQAAAOQAAADqAAYABgAAAAD/+gAF 

973AAEA6gAAAO8ABwAGAAD////6AAYAAADvAAAA9gAGAAYAAAAA//oABQAAAPYAAAD7AAYABgAA//// 

974+gAFAAAA+wAAAQEABgAGAAD////6AAYAAAEBAAABCAAGAAYAAP////oABgAAAQgAAAEPAAYABgAA 

975////+gAGAAABDwAAARYABgAGAAAAAP/6AAYAAAEWAAABHAAGAAYAAP////oABgAAARwAAAEjAAYA 

976BgAAAAD/+gAFAAABIwAAASgABgAGAAAAAf/5AAQAAQEoAAABKwAIAAYAAAAA//kABAABASsAAAEv 

977AAgABgAAAAH/+QAEAAEBLwAAATIACAAGAAAAAP/5AAX//AEyAAABNwADAAYAAAAAAAEABgACATcA 

978AAE9AAEABgAAAAH/+QAE//wBPQAAAUAAAwAGAAAAAP/7AAYAAAFAAAABRgAFAAYAAP////kABQAA 

979AUYAAAFMAAcABgAAAAD/+wAFAAABTAAAAVEABQAGAAAAAP/5AAYAAAFRAAABVwAHAAYAAAAA//sA 

980BQAAAVcAAAFcAAUABgAAAAD/+QAFAAABXAAAAWEABwAGAAAAAP/7AAYAAgFhAAABZwAHAAYAAP//