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 

30import abc 

31import base64 

32import os 

33import sys 

34import warnings 

35from enum import IntEnum 

36from io import BytesIO 

37from types import ModuleType 

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

39 

40from . import Image 

41from ._typing import StrOrBytesPath 

42from ._util import DeferredError, is_path 

43 

44TYPE_CHECKING = False 

45if TYPE_CHECKING: 

46 from . import ImageFile 

47 from ._imaging import ImagingFont 

48 from ._imagingft import Font 

49 

50 

51class Axis(TypedDict): 

52 minimum: int | None 

53 default: int | None 

54 maximum: int | None 

55 name: bytes | None 

56 

57 

58class Layout(IntEnum): 

59 BASIC = 0 

60 RAQM = 1 

61 

62 

63MAX_STRING_LENGTH = 1_000_000 

64 

65 

66core: ModuleType | DeferredError 

67try: 

68 from . import _imagingft as core 

69except ImportError as ex: 

70 core = DeferredError.new(ex) 

71 

72 

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

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

75 msg = "too many characters in string" 

76 raise ValueError(msg) 

77 

78 

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

80 

81# -------------------------------------------------------------------- 

82# Font metrics format: 

83# "PILfont" LF 

84# fontdescriptor LF 

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

86# "DATA" LF 

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

88# 

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

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

91# position according to dx, dy. 

92# -------------------------------------------------------------------- 

93 

94 

95class BaseImageFont(abc.ABC): 

96 """Used by ImageDraw and ImageText""" 

97 

98 @abc.abstractmethod 

99 def getbbox( 

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

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

102 pass 

103 

104 @abc.abstractmethod 

105 def getmask( 

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

107 ) -> Image.core.ImagingCore: 

108 pass 

109 

110 @abc.abstractmethod 

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

112 pass 

113 

114 

115class ImageFont(BaseImageFont): 

116 """PIL font wrapper""" 

117 

118 font: ImagingFont 

119 

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

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

122 image: ImageFile.ImageFile | None = None 

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

124 

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

126 if image: 

127 image.close() 

128 try: 

129 fullname = root + ext 

130 image = Image.open(fullname) 

131 except Exception: 

132 pass 

133 else: 

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

135 break 

136 else: 

137 if image: 

138 image.close() 

139 

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

141 raise OSError(msg) 

142 

143 self.file = fullname 

144 

145 self._load_pilfont_data(fp, image) 

146 image.close() 

147 

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

149 # check image 

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

151 image.close() 

152 

153 msg = "invalid font image mode" 

154 raise TypeError(msg) 

155 

156 # read PILfont header 

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

158 image.close() 

159 

160 msg = "Not a PILfont file" 

161 raise SyntaxError(msg) 

162 file.readline() 

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

164 while True: 

165 s = file.readline() 

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

167 break 

168 self.info.append(s) 

169 

170 # read PILfont metrics 

171 data = file.read(256 * 20) 

172 

173 self._load(image, data) 

174 

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

176 image.load() 

177 

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

179 

180 def getmask( 

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

182 ) -> Image.core.ImagingCore: 

183 """ 

184 Create a bitmap for the text. 

185 

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

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

188 

189 :param text: Text to render. 

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

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

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

193 C-level implementations. 

194 

195 .. versionadded:: 1.1.5 

196 

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

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

199 """ 

200 _string_length_check(text) 

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

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

203 

204 def getbbox( 

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

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

207 """ 

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

209 

210 .. versionadded:: 9.2.0 

211 

212 :param text: Text to render. 

213 

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

215 """ 

216 _string_length_check(text) 

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

218 return 0, 0, width, height 

219 

220 def getlength( 

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

222 ) -> int: 

223 """ 

224 Returns length (in pixels) of given text. 

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

226 

227 .. versionadded:: 9.2.0 

228 """ 

229 _string_length_check(text) 

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

231 return width 

232 

233 

234## 

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

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

237 

238 

239class FreeTypeFont(BaseImageFont): 

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

241 

242 font: Font 

243 font_bytes: bytes 

244 

245 def __init__( 

246 self, 

247 font: StrOrBytesPath | BinaryIO, 

248 size: float = 10, 

249 index: int = 0, 

250 encoding: str = "", 

251 layout_engine: Layout | None = None, 

252 ) -> None: 

253 # FIXME: use service provider instead 

254 

255 if isinstance(core, DeferredError): 

256 raise core.ex 

257 

258 if size <= 0: 

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

260 raise ValueError(msg) 

261 

262 self.path = font 

263 self.size = size 

264 self.index = index 

265 self.encoding = encoding 

266 

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

268 layout_engine = Layout.BASIC 

269 if core.HAVE_RAQM: 

270 layout_engine = Layout.RAQM 

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

272 warnings.warn( 

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

274 "Falling back to basic layout." 

275 ) 

276 layout_engine = Layout.BASIC 

277 

278 self.layout_engine = layout_engine 

279 

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

281 self.font_bytes = f.read() 

282 self.font = core.getfont( 

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

284 ) 

285 

286 if is_path(font): 

287 font = os.fspath(font) 

288 if sys.platform == "win32": 

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

290 try: 

291 font_bytes_path.decode("ascii") 

292 except UnicodeDecodeError: 

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

294 # So load it into memory first 

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

296 load_from_bytes(f) 

297 return 

298 self.font = core.getfont( 

299 font, size, index, encoding, layout_engine=layout_engine 

300 ) 

301 else: 

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

303 

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

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

306 

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

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

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

310 

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

312 """ 

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

314 (e.g. Bold) 

315 """ 

316 return self.font.family, self.font.style 

317 

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

319 """ 

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

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

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

323 """ 

324 return self.font.ascent, self.font.descent 

325 

326 def getlength( 

327 self, 

328 text: str | bytes, 

329 mode: str = "", 

330 direction: str | None = None, 

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

332 language: str | None = None, 

333 ) -> float: 

334 """ 

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

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

337 

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

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

340 e.g. when using italics or accents. 

341 

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

343 

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

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

346 character and subtract its length. 

347 

348 For example, instead of :: 

349 

350 hello = font.getlength("Hello") 

351 world = font.getlength("World") 

352 hello_world = hello + world # not adjusted for kerning 

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

354 

355 use :: 

356 

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

358 world = font.getlength("World") 

359 hello_world = hello + world # adjusted for kerning 

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

361 

362 or disable kerning with (requires libraqm) :: 

363 

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

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

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

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

368 

369 .. versionadded:: 8.0.0 

370 

371 :param text: Text to measure. 

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

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

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

375 C-level implementations. 

376 

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

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

379 Requires libraqm. 

380 

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

382 layout. This is usually used to turn on optional 

383 font features that are not enabled by default, 

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

385 used to turn off default font features for 

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

387 to disable kerning. To get all supported 

388 features, see 

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

390 Requires libraqm. 

391 

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

393 different glyph shapes or ligatures. This parameter tells 

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

395 correct substitutions as appropriate, if available. 

396 It should be a `BCP 47 language code 

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

398 Requires libraqm. 

399 

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

401 """ 

402 _string_length_check(text) 

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

404 

405 def getbbox( 

406 self, 

407 text: str | bytes | bytearray, 

408 mode: str = "", 

409 direction: str | None = None, 

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

411 language: str | None = None, 

412 stroke_width: float = 0, 

413 anchor: str | None = None, 

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

415 """ 

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

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

418 

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

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

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

422 

423 .. versionadded:: 8.0.0 

424 

425 :param text: Text to render. 

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

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

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

429 C-level implementations. 

430 

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

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

433 Requires libraqm. 

434 

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

436 layout. This is usually used to turn on optional 

437 font features that are not enabled by default, 

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

439 used to turn off default font features for 

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

441 to disable kerning. To get all supported 

442 features, see 

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

444 Requires libraqm. 

445 

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

447 different glyph shapes or ligatures. This parameter tells 

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

449 correct substitutions as appropriate, if available. 

450 It should be a `BCP 47 language code 

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

452 Requires libraqm. 

453 

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

455 

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

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

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

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

460 

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

462 """ 

463 _string_length_check(text) 

464 size, offset = self.font.getsize( 

465 text, mode, direction, features, language, anchor 

466 ) 

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

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

469 return left, top, left + width, top + height 

470 

471 def getmask( 

472 self, 

473 text: str | bytes, 

474 mode: str = "", 

475 direction: str | None = None, 

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

477 language: str | None = None, 

478 stroke_width: float = 0, 

479 anchor: str | None = None, 

480 ink: int = 0, 

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

482 ) -> Image.core.ImagingCore: 

483 """ 

484 Create a bitmap for the text. 

485 

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

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

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

489 

490 :param text: Text to render. 

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

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

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

494 C-level implementations. 

495 

496 .. versionadded:: 1.1.5 

497 

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

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

500 Requires libraqm. 

501 

502 .. versionadded:: 4.2.0 

503 

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

505 layout. This is usually used to turn on optional 

506 font features that are not enabled by default, 

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

508 used to turn off default font features for 

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

510 to disable kerning. To get all supported 

511 features, see 

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

513 Requires libraqm. 

514 

515 .. versionadded:: 4.2.0 

516 

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

518 different glyph shapes or ligatures. This parameter tells 

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

520 correct substitutions as appropriate, if available. 

521 It should be a `BCP 47 language code 

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

523 Requires libraqm. 

524 

525 .. versionadded:: 6.0.0 

526 

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

528 

529 .. versionadded:: 6.2.0 

530 

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

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

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

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

535 

536 .. versionadded:: 8.0.0 

537 

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

539 

540 .. versionadded:: 8.0.0 

541 

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

543 differently when starting at fractional coordinates. 

544 

545 .. versionadded:: 9.4.0 

546 

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

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

549 """ 

550 return self.getmask2( 

551 text, 

552 mode, 

553 direction=direction, 

554 features=features, 

555 language=language, 

556 stroke_width=stroke_width, 

557 anchor=anchor, 

558 ink=ink, 

559 start=start, 

560 )[0] 

561 

562 def getmask2( 

563 self, 

564 text: str | bytes, 

565 mode: str = "", 

566 direction: str | None = None, 

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

568 language: str | None = None, 

569 stroke_width: float = 0, 

570 anchor: str | None = None, 

571 ink: int = 0, 

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

573 *args: Any, 

574 **kwargs: Any, 

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

576 """ 

577 Create a bitmap for the text. 

578 

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

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

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

582 

583 :param text: Text to render. 

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

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

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

587 C-level implementations. 

588 

589 .. versionadded:: 1.1.5 

590 

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

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

593 Requires libraqm. 

594 

595 .. versionadded:: 4.2.0 

596 

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

598 layout. This is usually used to turn on optional 

599 font features that are not enabled by default, 

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

601 used to turn off default font features for 

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

603 to disable kerning. To get all supported 

604 features, see 

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

606 Requires libraqm. 

607 

608 .. versionadded:: 4.2.0 

609 

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

611 different glyph shapes or ligatures. This parameter tells 

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

613 correct substitutions as appropriate, if available. 

614 It should be a `BCP 47 language code 

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

616 Requires libraqm. 

617 

618 .. versionadded:: 6.0.0 

619 

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

621 

622 .. versionadded:: 6.2.0 

623 

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

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

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

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

628 

629 .. versionadded:: 8.0.0 

630 

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

632 

633 .. versionadded:: 8.0.0 

634 

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

636 differently when starting at fractional coordinates. 

637 

638 .. versionadded:: 9.4.0 

639 

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

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

642 gap between the starting coordinate and the first marking 

643 """ 

644 _string_length_check(text) 

645 if start is None: 

646 start = (0, 0) 

647 

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

649 size = (width, height) 

650 Image._decompression_bomb_check(size) 

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

652 

653 return self.font.render( 

654 text, 

655 fill, 

656 mode, 

657 direction, 

658 features, 

659 language, 

660 stroke_width, 

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

662 anchor, 

663 ink, 

664 start, 

665 ) 

666 

667 def font_variant( 

668 self, 

669 font: StrOrBytesPath | BinaryIO | None = None, 

670 size: float | None = None, 

671 index: int | None = None, 

672 encoding: str | None = None, 

673 layout_engine: Layout | None = None, 

674 ) -> FreeTypeFont: 

675 """ 

676 Create a copy of this FreeTypeFont object, 

677 using any specified arguments to override the settings. 

678 

679 Parameters are identical to the parameters used to initialize this 

680 object. 

681 

682 :return: A FreeTypeFont object. 

683 """ 

684 if font is None: 

685 try: 

686 font = BytesIO(self.font_bytes) 

687 except AttributeError: 

688 font = self.path 

689 return FreeTypeFont( 

690 font=font, 

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

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

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

694 layout_engine=layout_engine or self.layout_engine, 

695 ) 

696 

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

698 """ 

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

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

701 """ 

702 names = [] 

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

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

705 if name not in names: 

706 names.append(name) 

707 return names 

708 

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

710 """ 

711 :param name: The name of the style. 

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

713 """ 

714 names = self.get_variation_names() 

715 if not isinstance(name, bytes): 

716 name = name.encode() 

717 index = names.index(name) + 1 

718 

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

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

721 # there is an 'unknown freetype error' 

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

723 return 

724 self._last_variation_index = index 

725 

726 self.font.setvarname(index) 

727 

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

729 """ 

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

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

732 """ 

733 axes = self.font.getvaraxes() 

734 for axis in axes: 

735 if axis["name"]: 

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

737 return axes 

738 

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

740 """ 

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

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

743 """ 

744 self.font.setvaraxes(axes) 

745 

746 

747class TransposedFont(BaseImageFont): 

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

749 

750 def __init__( 

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

752 ): 

753 """ 

754 Wrapper that creates a transposed font from any existing font 

755 object. 

756 

757 :param font: A font object. 

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

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

760 Image.Transpose.ROTATE_90, Image.Transpose.ROTATE_180, or 

761 Image.Transpose.ROTATE_270. 

762 """ 

763 self.font = font 

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

765 

766 def getmask( 

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

768 ) -> Image.core.ImagingCore: 

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

770 if self.orientation is not None: 

771 return im.transpose(self.orientation) 

772 return im 

773 

774 def getbbox( 

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

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

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

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

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

780 width = right - left 

781 height = bottom - top 

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

783 return 0, 0, height, width 

784 return 0, 0, width, height 

785 

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

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

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

789 raise ValueError(msg) 

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

791 

792 

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

794 """ 

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

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

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

798 

799 :param filename: Name of font file. 

800 :return: A font object. 

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

802 """ 

803 f = ImageFont() 

804 f._load_pilfont(filename) 

805 return f 

806 

807 

808def truetype( 

809 font: StrOrBytesPath | BinaryIO, 

810 size: float = 10, 

811 index: int = 0, 

812 encoding: str = "", 

813 layout_engine: Layout | None = None, 

814) -> FreeTypeFont: 

815 """ 

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

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

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

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

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

821 

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

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

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

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

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

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

828 

829 This function requires the _imagingft service. 

830 

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

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

833 search in other directories, such as: 

834 

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

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

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

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

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

840 the ``XDG_DATA_HOME`` and ``XDG_DATA_DIRS`` environment variables 

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

842 

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

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

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

846 encodings include (see the FreeType documentation for more 

847 information): 

848 

849 * "unic" (Unicode) 

850 * "symb" (Microsoft Symbol) 

851 * "ADOB" (Adobe Standard) 

852 * "ADBE" (Adobe Expert) 

853 * "ADBC" (Adobe Custom) 

854 * "armn" (Apple Roman) 

855 * "sjis" (Shift JIS) 

856 * "gb " (PRC) 

857 * "big5" 

858 * "wans" (Extended Wansung) 

859 * "joha" (Johab) 

860 * "lat1" (Latin-1) 

861 

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

863 encoding of any text provided in subsequent operations. 

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

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

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

867 Otherwise, basic layout will be used. 

868 

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

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

871 

872 You can check support for Raqm layout using 

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

874 

875 .. versionadded:: 4.2.0 

876 :return: A font object. 

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

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

879 """ 

880 

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

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

883 

884 try: 

885 return freetype(font) 

886 except OSError: 

887 if not is_path(font): 

888 raise 

889 ttf_filename = os.path.basename(font) 

890 

891 dirs = [] 

892 if sys.platform == "win32": 

893 # check the windows font repository 

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

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

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

897 if windir: 

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

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

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

901 if not data_home: 

902 # The freedesktop spec defines the following default directory for 

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

904 # takes precedence over system-level directories. 

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

906 xdg_dirs = [data_home] 

907 

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

909 if not data_dirs: 

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

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

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

913 

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

915 elif sys.platform == "darwin": 

916 dirs += [ 

917 "/Library/Fonts", 

918 "/System/Library/Fonts", 

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

920 ] 

921 

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

923 first_font_with_a_different_extension = None 

924 for directory in dirs: 

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

926 for walkfilename in walkfilenames: 

927 if ext and walkfilename == ttf_filename: 

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

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

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

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

932 return freetype(fontpath) 

933 if not ext and first_font_with_a_different_extension is None: 

934 first_font_with_a_different_extension = fontpath 

935 if first_font_with_a_different_extension: 

936 return freetype(first_font_with_a_different_extension) 

937 raise 

938 

939 

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

941 """ 

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

943 bitmap font along the Python path. 

944 

945 :param filename: Name of font file. 

946 :return: A font object. 

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

948 """ 

949 if not isinstance(filename, str): 

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

951 for directory in sys.path: 

952 try: 

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

954 except OSError: # noqa: PERF203 

955 pass 

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

957 if os.path.exists(filename): 

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

959 

960 raise OSError(msg)