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 = self.font.getvarnames() 

679 return [name.replace(b"\x00", b"") for name in names] 

680 

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

682 """ 

683 :param name: The name of the style. 

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

685 """ 

686 names = self.get_variation_names() 

687 if not isinstance(name, bytes): 

688 name = name.encode() 

689 index = names.index(name) + 1 

690 

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

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

693 # there is an 'unknown freetype error' 

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

695 return 

696 self._last_variation_index = index 

697 

698 self.font.setvarname(index) 

699 

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

701 """ 

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

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

704 """ 

705 axes = self.font.getvaraxes() 

706 for axis in axes: 

707 if axis["name"]: 

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

709 return axes 

710 

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

712 """ 

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

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

715 """ 

716 self.font.setvaraxes(axes) 

717 

718 

719class TransposedFont: 

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

721 

722 def __init__( 

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

724 ): 

725 """ 

726 Wrapper that creates a transposed font from any existing font 

727 object. 

728 

729 :param font: A font object. 

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

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

732 Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_180, or 

733 Image.Transpose.ROTATE_270. 

734 """ 

735 self.font = font 

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

737 

738 def getmask( 

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

740 ) -> Image.core.ImagingCore: 

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

742 if self.orientation is not None: 

743 return im.transpose(self.orientation) 

744 return im 

745 

746 def getbbox( 

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

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

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

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

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

752 width = right - left 

753 height = bottom - top 

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

755 return 0, 0, height, width 

756 return 0, 0, width, height 

757 

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

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

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

761 raise ValueError(msg) 

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

763 

764 

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

766 """ 

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

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

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

770 

771 :param filename: Name of font file. 

772 :return: A font object. 

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

774 """ 

775 f = ImageFont() 

776 f._load_pilfont(filename) 

777 return f 

778 

779 

780def truetype( 

781 font: StrOrBytesPath | BinaryIO, 

782 size: float = 10, 

783 index: int = 0, 

784 encoding: str = "", 

785 layout_engine: Layout | None = None, 

786) -> FreeTypeFont: 

787 """ 

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

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

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

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

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

793 

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

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

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

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

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

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

800 

801 This function requires the _imagingft service. 

802 

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

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

805 search in other directories, such as: 

806 

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

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

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

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

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

812 the ``XDG_DATA_HOME`` and ``XDG_DATA_DIRS`` environment variables 

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

814 

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

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

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

818 encodings include (see the FreeType documentation for more 

819 information): 

820 

821 * "unic" (Unicode) 

822 * "symb" (Microsoft Symbol) 

823 * "ADOB" (Adobe Standard) 

824 * "ADBE" (Adobe Expert) 

825 * "ADBC" (Adobe Custom) 

826 * "armn" (Apple Roman) 

827 * "sjis" (Shift JIS) 

828 * "gb " (PRC) 

829 * "big5" 

830 * "wans" (Extended Wansung) 

831 * "joha" (Johab) 

832 * "lat1" (Latin-1) 

833 

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

835 encoding of any text provided in subsequent operations. 

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

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

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

839 Otherwise, basic layout will be used. 

840 

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

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

843 

844 You can check support for Raqm layout using 

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

846 

847 .. versionadded:: 4.2.0 

848 :return: A font object. 

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

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

851 """ 

852 

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

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

855 

856 try: 

857 return freetype(font) 

858 except OSError: 

859 if not is_path(font): 

860 raise 

861 ttf_filename = os.path.basename(font) 

862 

863 dirs = [] 

864 if sys.platform == "win32": 

865 # check the windows font repository 

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

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

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

869 if windir: 

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

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

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

873 if not data_home: 

874 # The freedesktop spec defines the following default directory for 

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

876 # takes precedence over system-level directories. 

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

878 xdg_dirs = [data_home] 

879 

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

881 if not data_dirs: 

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

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

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

885 

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

887 elif sys.platform == "darwin": 

888 dirs += [ 

889 "/Library/Fonts", 

890 "/System/Library/Fonts", 

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

892 ] 

893 

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

895 first_font_with_a_different_extension = None 

896 for directory in dirs: 

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

898 for walkfilename in walkfilenames: 

899 if ext and walkfilename == ttf_filename: 

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

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

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

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

904 return freetype(fontpath) 

905 if not ext and first_font_with_a_different_extension is None: 

906 first_font_with_a_different_extension = fontpath 

907 if first_font_with_a_different_extension: 

908 return freetype(first_font_with_a_different_extension) 

909 raise 

910 

911 

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

913 """ 

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

915 bitmap font along the Python path. 

916 

917 :param filename: Name of font file. 

918 :return: A font object. 

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

920 """ 

921 if not isinstance(filename, str): 

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

923 for directory in sys.path: 

924 try: 

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

926 except OSError: 

927 pass 

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

929 if os.path.exists(filename): 

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

931 

932 raise OSError(msg) 

933 

934 

935def load_default_imagefont() -> ImageFont: 

936 f = ImageFont() 

937 f._load_pilfont_data( 

938 # courB08 

939 BytesIO( 

940 base64.b64decode( 

941 b""" 

942UElMZm9udAo7Ozs7OzsxMDsKREFUQQoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

943AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

944AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

945AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

946AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

947AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

948AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

949AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

950AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

951AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

952AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 

953AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYAAAAA//8AAQAAAAAAAAABAAEA 

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

955AAgABgAAAAD/+AAFAAEACwAAABAACQAGAAAAAP/5AAUAAAAQAAAAFQAHAAYAAP////oABQAAABUA 

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

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

958BAACAC0AAAAwAAMABgAAAAD//AAF//0AMAAAADUAAQAGAAAAAf//AAMAAAA1AAAANwABAAYAAAAB 

959//kABQABADcAAAA7AAgABgAAAAD/+QAFAAAAOwAAAEAABwAGAAAAAP/5AAYAAABAAAAARgAHAAYA 

960AAAA//kABQAAAEYAAABLAAcABgAAAAD/+QAFAAAASwAAAFAABwAGAAAAAP/5AAYAAABQAAAAVgAH 

961AAYAAAAA//kABQAAAFYAAABbAAcABgAAAAD/+QAFAAAAWwAAAGAABwAGAAAAAP/5AAUAAABgAAAA 

962ZQAHAAYAAAAA//kABQAAAGUAAABqAAcABgAAAAD/+QAFAAAAagAAAG8ABwAGAAAAAf/8AAMAAABv 

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

964/gB4AAAAfAADAAYAAAAB//oABf//AHwAAACAAAUABgAAAAD/+gAFAAAAgAAAAIUABgAGAAAAAP/5 

965AAYAAQCFAAAAiwAIAAYAAP////oABgAAAIsAAACSAAYABgAA////+gAFAAAAkgAAAJgABgAGAAAA 

966AP/6AAUAAACYAAAAnQAGAAYAAP////oABQAAAJ0AAACjAAYABgAA////+gAFAAAAowAAAKkABgAG 

967AAD////6AAUAAACpAAAArwAGAAYAAAAA//oABQAAAK8AAAC0AAYABgAA////+gAGAAAAtAAAALsA 

968BgAGAAAAAP/6AAQAAAC7AAAAvwAGAAYAAP////oABQAAAL8AAADFAAYABgAA////+gAGAAAAxQAA 

969AMwABgAGAAD////6AAUAAADMAAAA0gAGAAYAAP////oABQAAANIAAADYAAYABgAA////+gAGAAAA 

9702AAAAN8ABgAGAAAAAP/6AAUAAADfAAAA5AAGAAYAAP////oABQAAAOQAAADqAAYABgAAAAD/+gAF 

971AAEA6gAAAO8ABwAGAAD////6AAYAAADvAAAA9gAGAAYAAAAA//oABQAAAPYAAAD7AAYABgAA//// 

972+gAFAAAA+wAAAQEABgAGAAD////6AAYAAAEBAAABCAAGAAYAAP////oABgAAAQgAAAEPAAYABgAA 

973////+gAGAAABDwAAARYABgAGAAAAAP/6AAYAAAEWAAABHAAGAAYAAP////oABgAAARwAAAEjAAYA 

974BgAAAAD/+gAFAAABIwAAASgABgAGAAAAAf/5AAQAAQEoAAABKwAIAAYAAAAA//kABAABASsAAAEv 

975AAgABgAAAAH/+QAEAAEBLwAAATIACAAGAAAAAP/5AAX//AEyAAABNwADAAYAAAAAAAEABgACATcA 

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

977AUYAAAFMAAcABgAAAAD/+wAFAAABTAAAAVEABQAGAAAAAP/5AAYAAAFRAAABVwAHAAYAAAAA//sA 

978BQAAAVcAAAFcAAUABgAAAAD/+QAFAAABXAAAAWEABwAGAAAAAP/7AAYAAgFhAAABZwAHAAYAAP// 

979//kABQAAAWcAAAFtAAcABgAAAAD/+QAGAAABbQAAAXMABwAGAAAAAP/5AAQAAgFzAAABdwAJAAYA 

980AP////kABgAAAXcAAAF+AAcABgAAAAD/+QAGAAABfgAAAYQABwAGAAD////7AAUAAAGEAAABigAF 

981AAYAAP////sABQAAAYoAAAGQAAUABgAAAAD/+wAFAAABkAAAAZUABQAGAAD////7AAUAAgGVAAAB 

982mwAHAAYAAAAA//sABgACAZsAAAGhAAcABgAAAAD/+wAGAAABoQAAAacABQAGAAAAAP/7AAYAAAGn