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

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 

30__lazy_modules__ = {"base64", "io", "types", "warnings"} 

31 

32import abc 

33import base64 

34import os 

35import sys 

36import warnings 

37from enum import IntEnum 

38from io import BytesIO 

39from types import ModuleType 

40from typing import TypedDict, cast 

41 

42from . import Image 

43from ._util import DeferredError, is_path 

44 

45TYPE_CHECKING = False 

46if TYPE_CHECKING: 

47 from typing import IO, Any, BinaryIO, NotRequired 

48 

49 from . import ImageFile 

50 from ._imaging import ImagingFont 

51 from ._imagingft import Font 

52 from ._typing import StrOrBytesPath 

53 

54 

55class Axis(TypedDict): 

56 minimum: int | None 

57 default: int | None 

58 maximum: int | None 

59 name: NotRequired[bytes] 

60 

61 

62class Layout(IntEnum): 

63 BASIC = 0 

64 RAQM = 1 

65 

66 

67MAX_STRING_LENGTH = 1_000_000 

68 

69# From raqm.c's _raqm_is_paragraph_separator() 

70_separators = ( 

71 "\r\n", # Windows 

72 "\n", # 0x000A 

73 "\r", # 0x000D 

74 "\u001c", 

75 "\u001d", 

76 "\u001e", 

77 "\u0085", 

78 "\u2029", 

79) 

80 

81core: ModuleType | DeferredError 

82try: 

83 from . import _imagingft as core 

84except ImportError as ex: 

85 core = DeferredError.new(ex) 

86 

87 

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

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

90 msg = "too many characters in string" 

91 raise ValueError(msg) 

92 

93 

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

95 

96# -------------------------------------------------------------------- 

97# Font metrics format: 

98# "PILfont" LF 

99# fontdescriptor LF 

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

101# "DATA" LF 

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

103# 

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

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

106# position according to dx, dy. 

107# -------------------------------------------------------------------- 

108 

109 

110class BaseImageFont(abc.ABC): 

111 """Used by ImageDraw and ImageText""" 

112 

113 @abc.abstractmethod 

114 def getbbox( 

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

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

117 pass 

118 

119 @abc.abstractmethod 

120 def getmask( 

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

122 ) -> Image.core.ImagingCore: 

123 pass 

124 

125 @abc.abstractmethod 

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

127 pass 

128 

129 

130class ImageFont(BaseImageFont): 

131 """PIL font wrapper""" 

132 

133 font: ImagingFont 

134 

135 def _load_pilfont(self, filename: str | os.PathLike[str]) -> None: 

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

137 image: ImageFile.ImageFile | None = None 

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

139 

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

141 if image: 

142 image.close() 

143 try: 

144 fullname = root + ext 

145 image = Image.open(fullname) 

146 except Exception: 

147 pass 

148 else: 

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

150 break 

151 else: 

152 if image: 

153 image.close() 

154 

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

156 raise OSError(msg) 

157 

158 self.file = fullname 

159 

160 self._load_pilfont_data(fp, image) 

161 image.close() 

162 

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

164 # check image 

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

166 image.close() 

167 

168 msg = "invalid font image mode" 

169 raise TypeError(msg) 

170 

171 # read PILfont header 

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

173 image.close() 

174 

175 msg = "Not a PILfont file" 

176 raise SyntaxError(msg) 

177 file.readline() 

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

179 while True: 

180 s = file.readline() 

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

182 break 

183 self.info.append(s) 

184 

185 # read PILfont metrics 

186 data = file.read(256 * 20) 

187 

188 self._load(image, data) 

189 

190 def _load(self, image: Image.Image, data: bytes) -> None: 

191 image.load() 

192 

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

194 

195 def getmask( 

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

197 ) -> Image.core.ImagingCore: 

198 """ 

199 Create a bitmap for the text. 

200 

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

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

203 

204 :param text: Text to render. 

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

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

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

208 C-level implementations. 

209 

210 .. versionadded:: 1.1.5 

211 

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

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

214 """ 

215 _string_length_check(text) 

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

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

218 

219 def getbbox( 

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

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

222 """ 

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

224 

225 .. versionadded:: 9.2.0 

226 

227 :param text: Text to render. 

228 

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

230 """ 

231 _string_length_check(text) 

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

233 return 0, 0, width, height 

234 

235 def getlength( 

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

237 ) -> int: 

238 """ 

239 Returns length (in pixels) of given text. 

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

241 

242 .. versionadded:: 9.2.0 

243 """ 

244 _string_length_check(text) 

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

246 return width 

247 

248 

249## 

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

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

252 

253 

254class FreeTypeFont(BaseImageFont): 

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

256 

257 font: Font 

258 font_bytes: bytes 

259 

260 def __init__( 

261 self, 

262 font: StrOrBytesPath | BinaryIO, 

263 size: float = 10, 

264 index: int = 0, 

265 encoding: str = "", 

266 layout_engine: Layout | None = None, 

267 ) -> None: 

268 # FIXME: use service provider instead 

269 

270 if isinstance(core, DeferredError): 

271 raise core.ex 

272 

273 if size <= 0: 

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

275 raise ValueError(msg) 

276 

277 self.path = font 

278 self.size = size 

279 self.index = index 

280 self.encoding = encoding 

281 

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

283 layout_engine = Layout.BASIC 

284 if core.HAVE_RAQM: 

285 layout_engine = Layout.RAQM 

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

287 warnings.warn( 

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

289 "Falling back to basic layout." 

290 ) 

291 layout_engine = Layout.BASIC 

292 

293 self.layout_engine = layout_engine 

294 

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

296 self.font_bytes = f.read() 

297 self.font = core.getfont( 

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

299 ) 

300 

301 if is_path(font): 

302 font = os.fspath(font) 

303 if sys.platform == "win32": 

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

305 try: 

306 font_bytes_path.decode("ascii") 

307 except UnicodeDecodeError: 

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

309 # So load it into memory first 

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

311 load_from_bytes(f) 

312 return 

313 self.font = core.getfont(font, size, index, encoding, layout_engine) 

314 else: 

315 load_from_bytes(cast("IO[bytes]", font)) 

316 

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

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

319 

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

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

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

323 

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

325 """ 

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

327 (e.g. Bold) 

328 """ 

329 return self.font.family, self.font.style 

330 

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

332 """ 

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

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

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

336 """ 

337 return self.font.ascent, self.font.descent 

338 

339 def _has_separator(self, text: str | bytes | bytearray) -> bool: 

340 if self.layout_engine != Layout.RAQM: 

341 return False 

342 if isinstance(text, str): 

343 return any(separator in text for separator in _separators) 

344 return any(separator.encode() in text for separator in _separators) 

345 

346 def getlength( 

347 self, 

348 text: str | bytes, 

349 mode: str = "", 

350 direction: str | None = None, 

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

352 language: str | None = None, 

353 ) -> float: 

354 """ 

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

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

357 

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

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

360 e.g. when using italics or accents. 

361 

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

363 

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

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

366 character and subtract its length. 

367 

368 For example, instead of :: 

369 

370 hello = font.getlength("Hello") 

371 world = font.getlength("World") 

372 hello_world = hello + world # not adjusted for kerning 

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

374 

375 use :: 

376 

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

378 world = font.getlength("World") 

379 hello_world = hello + world # adjusted for kerning 

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

381 

382 or disable kerning with (requires libraqm) :: 

383 

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

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

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

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

388 

389 .. versionadded:: 8.0.0 

390 

391 :param text: Text to measure. Newlines raise an error with Raqm layout. 

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

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

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

395 C-level implementations. 

396 

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

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

399 Requires libraqm. 

400 

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

402 layout. This is usually used to turn on optional 

403 font features that are not enabled by default, 

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

405 used to turn off default font features for 

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

407 to disable kerning. To get all supported 

408 features, see 

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

410 Requires libraqm. 

411 

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

413 different glyph shapes or ligatures. This parameter tells 

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

415 correct substitutions as appropriate, if available. 

416 It should be a `BCP 47 language code 

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

418 Requires libraqm. 

419 

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

421 """ 

422 _string_length_check(text) 

423 if self._has_separator(text): 

424 msg = "can't measure length of multiline text with Raqm" 

425 raise ValueError(msg) 

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

427 

428 def getbbox( 

429 self, 

430 text: str | bytes | bytearray, 

431 mode: str = "", 

432 direction: str | None = None, 

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

434 language: str | None = None, 

435 stroke_width: float = 0, 

436 anchor: str | None = None, 

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

438 """ 

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

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

441 

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

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

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

445 

446 .. versionadded:: 8.0.0 

447 

448 :param text: Text to render. Newlines will not cause a line break with 

449 Basic layout, and will raise an error with Raqm layout. 

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

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

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

453 C-level implementations. 

454 

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

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

457 Requires libraqm. 

458 

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

460 layout. This is usually used to turn on optional 

461 font features that are not enabled by default, 

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

463 used to turn off default font features for 

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

465 to disable kerning. To get all supported 

466 features, see 

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

468 Requires libraqm. 

469 

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

471 different glyph shapes or ligatures. This parameter tells 

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

473 correct substitutions as appropriate, if available. 

474 It should be a `BCP 47 language code 

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

476 Requires libraqm. 

477 

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

479 

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

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

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

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

484 

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

486 """ 

487 _string_length_check(text) 

488 if self._has_separator(text): 

489 msg = "can't measure bounding box of multiline text with Raqm" 

490 raise ValueError(msg) 

491 size, offset = self.font.getsize( 

492 text, mode, direction, features, language, anchor 

493 ) 

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

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

496 return left, top, left + width, top + height 

497 

498 def getmask( 

499 self, 

500 text: str | bytes, 

501 mode: str = "", 

502 direction: str | None = None, 

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

504 language: str | None = None, 

505 stroke_width: float = 0, 

506 anchor: str | None = None, 

507 ink: int = 0, 

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

509 ) -> Image.core.ImagingCore: 

510 """ 

511 Create a bitmap for the text. 

512 

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

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

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

516 

517 :param text: Text to render. 

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

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

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

521 C-level implementations. 

522 

523 .. versionadded:: 1.1.5 

524 

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

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

527 Requires libraqm. 

528 

529 .. versionadded:: 4.2.0 

530 

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

532 layout. This is usually used to turn on optional 

533 font features that are not enabled by default, 

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

535 used to turn off default font features for 

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

537 to disable kerning. To get all supported 

538 features, see 

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

540 Requires libraqm. 

541 

542 .. versionadded:: 4.2.0 

543 

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

545 different glyph shapes or ligatures. This parameter tells 

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

547 correct substitutions as appropriate, if available. 

548 It should be a `BCP 47 language code 

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

550 Requires libraqm. 

551 

552 .. versionadded:: 6.0.0 

553 

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

555 

556 .. versionadded:: 6.2.0 

557 

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

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

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

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

562 

563 .. versionadded:: 8.0.0 

564 

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

566 

567 .. versionadded:: 8.0.0 

568 

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

570 differently when starting at fractional coordinates. 

571 

572 .. versionadded:: 9.4.0 

573 

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

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

576 """ 

577 return self.getmask2( 

578 text, 

579 mode, 

580 direction=direction, 

581 features=features, 

582 language=language, 

583 stroke_width=stroke_width, 

584 anchor=anchor, 

585 ink=ink, 

586 start=start, 

587 )[0] 

588 

589 def getmask2( 

590 self, 

591 text: str | bytes, 

592 mode: str = "", 

593 direction: str | None = None, 

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

595 language: str | None = None, 

596 stroke_width: float = 0, 

597 anchor: str | None = None, 

598 ink: int = 0, 

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

600 *args: Any, 

601 **kwargs: Any, 

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

603 """ 

604 Create a bitmap for the text. 

605 

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

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

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

609 

610 :param text: Text to render. 

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

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

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

614 C-level implementations. 

615 

616 .. versionadded:: 1.1.5 

617 

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

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

620 Requires libraqm. 

621 

622 .. versionadded:: 4.2.0 

623 

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

625 layout. This is usually used to turn on optional 

626 font features that are not enabled by default, 

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

628 used to turn off default font features for 

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

630 to disable kerning. To get all supported 

631 features, see 

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

633 Requires libraqm. 

634 

635 .. versionadded:: 4.2.0 

636 

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

638 different glyph shapes or ligatures. This parameter tells 

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

640 correct substitutions as appropriate, if available. 

641 It should be a `BCP 47 language code 

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

643 Requires libraqm. 

644 

645 .. versionadded:: 6.0.0 

646 

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

648 

649 .. versionadded:: 6.2.0 

650 

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

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

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

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

655 

656 .. versionadded:: 8.0.0 

657 

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

659 

660 .. versionadded:: 8.0.0 

661 

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

663 differently when starting at fractional coordinates. 

664 

665 .. versionadded:: 9.4.0 

666 

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

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

669 gap between the starting coordinate and the first marking 

670 """ 

671 _string_length_check(text) 

672 if start is None: 

673 start = (0, 0) 

674 

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

676 size = (width, height) 

677 Image._decompression_bomb_check(size) 

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

679 

680 return self.font.render( 

681 text, 

682 fill, 

683 mode, 

684 direction, 

685 features, 

686 language, 

687 stroke_width, 

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

689 anchor, 

690 ink, 

691 start, 

692 ) 

693 

694 def font_variant( 

695 self, 

696 font: StrOrBytesPath | BinaryIO | None = None, 

697 size: float | None = None, 

698 index: int | None = None, 

699 encoding: str | None = None, 

700 layout_engine: Layout | None = None, 

701 ) -> FreeTypeFont: 

702 """ 

703 Create a copy of this FreeTypeFont object, 

704 using any specified arguments to override the settings. 

705 

706 Parameters are identical to the parameters used to initialize this 

707 object. 

708 

709 :return: A FreeTypeFont object. 

710 """ 

711 if font is None: 

712 try: 

713 font = BytesIO(self.font_bytes) 

714 except AttributeError: 

715 font = self.path 

716 return FreeTypeFont( 

717 font=font, 

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

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

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

721 layout_engine=( 

722 layout_engine if layout_engine is not None else self.layout_engine 

723 ), 

724 ) 

725 

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

727 """ 

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

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

730 """ 

731 names = [] 

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

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

734 if name not in names: 

735 names.append(name) 

736 return names 

737 

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

739 """ 

740 :param name: The name of the style. 

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

742 """ 

743 names = self.get_variation_names() 

744 if not isinstance(name, bytes): 

745 name = name.encode() 

746 index = names.index(name) + 1 

747 

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

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

750 # there is an 'unknown freetype error' 

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

752 return 

753 self._last_variation_index = index 

754 

755 self.font.setvarname(index) 

756 

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

758 """ 

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

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

761 """ 

762 axes = self.font.getvaraxes() 

763 for axis in axes: 

764 if "name" in axis: 

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

766 return axes 

767 

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

769 """ 

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

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

772 """ 

773 self.font.setvaraxes(axes) 

774 

775 

776class TransposedFont(BaseImageFont): 

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

778 

779 def __init__( 

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

781 ): 

782 """ 

783 Wrapper that creates a transposed font from any existing font 

784 object. 

785 

786 :param font: A font object. 

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

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

789 Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_180, or 

790 Image.Transpose.ROTATE_270. 

791 """ 

792 self.font = font 

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

794 

795 def getmask( 

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

797 ) -> Image.core.ImagingCore: 

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

799 if self.orientation is not None: 

800 return im.transpose(self.orientation) 

801 return im 

802 

803 def getbbox( 

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

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

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

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

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

809 width = right - left 

810 height = bottom - top 

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

812 return 0, 0, height, width 

813 return 0, 0, width, height 

814 

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

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

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

818 raise ValueError(msg) 

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

820 

821 

822def load(filename: str | os.PathLike[str]) -> ImageFont: 

823 """ 

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

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

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

827 

828 :param filename: Name of font file. 

829 :return: A font object. 

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

831 """ 

832 f = ImageFont() 

833 f._load_pilfont(filename) 

834 return f 

835 

836 

837def truetype( 

838 font: StrOrBytesPath | BinaryIO, 

839 size: float = 10, 

840 index: int = 0, 

841 encoding: str = "", 

842 layout_engine: Layout | None = None, 

843) -> FreeTypeFont: 

844 """ 

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

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

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

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

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

850 

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

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

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

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

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

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

857 

858 This function requires the _imagingft service. 

859 

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

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

862 search in other directories, such as: 

863 

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

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

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

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

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

869 the ``XDG_DATA_HOME`` and ``XDG_DATA_DIRS`` environment variables 

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

871 

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

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

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

875 encodings include (see the FreeType documentation for more 

876 information): 

877 

878 * "unic" (Unicode) 

879 * "symb" (Microsoft Symbol) 

880 * "ADOB" (Adobe Standard) 

881 * "ADBE" (Adobe Expert) 

882 * "ADBC" (Adobe Custom) 

883 * "armn" (Apple Roman) 

884 * "sjis" (Shift JIS) 

885 * "gb " (PRC) 

886 * "big5" 

887 * "wans" (Extended Wansung) 

888 * "joha" (Johab) 

889 * "lat1" (Latin-1) 

890 

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

892 encoding of any text provided in subsequent operations. 

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

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

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

896 Otherwise, basic layout will be used. 

897 

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

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

900 

901 You can check support for Raqm layout using 

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

903 

904 .. versionadded:: 4.2.0 

905 :return: A font object. 

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

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

908 """ 

909 

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

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

912 

913 try: 

914 return freetype(font) 

915 except OSError: 

916 if not is_path(font): 

917 raise 

918 ttf_filename = os.path.basename(font) 

919 

920 dirs = [] 

921 if sys.platform == "win32": 

922 # check the windows font repository 

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

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

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

926 if windir: 

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

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

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

930 if not data_home: 

931 # The freedesktop spec defines the following default directory for 

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

933 # takes precedence over system-level directories. 

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

935 xdg_dirs = [data_home] 

936 

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

938 if not data_dirs: 

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

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

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

942 

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

944 elif sys.platform == "darwin": 

945 dirs += [ 

946 "/Library/Fonts", 

947 "/System/Library/Fonts", 

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

949 ] 

950 

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

952 first_font_with_a_different_extension = None 

953 for directory in dirs: 

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

955 for walkfilename in walkfilenames: 

956 if ext and walkfilename == ttf_filename: 

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

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