pyglet.font

Load fonts.

pyglet will automatically load any system-installed fonts. You can add additional fonts (for example, from your program resources) using add_file() or add_directory(). These fonts are then available in the same way as system-installed fonts:

from pyglet import font
font.add_file('action_man.ttf')
action_man = font.load('Action Man', 16)
# or
from pyglet import resource
resource.add_font('action_man.ttf')
action_man = font.load('Action Man')

See the pyglet.font.base module for documentation on the base classes used by this package.

add_directory(directory: str) → None

Add a directory of fonts to pyglet’s search path.

This function simply calls pyglet.font.add_file() for each file with a .ttf extension in the given directory. Subdirectories are not searched.

Parameters:: directory (str) – Directory that contains font files.
Return type:: None

add_file(font: str | BinaryIO) → None

Add a font to pyglet’s search path.

In order to load a font that is not installed on the system, you must call this method to tell pyglet that it exists. You can supply either a filename or any file-like object.

The font format is platform-dependent, but is typically a TrueType font file containing a single font face. Note that to use a font added with this method, you should pass the face name (not the file name) to :meth:pyglet.font.load() or any other place where you normally specify a font.

Parameters:: font (str | BinaryIO) – Filename or file-like object to load fonts from.
Return type:: None

add_user_font(font: UserDefinedFontBase) → None

Add a custom font created by the user.

A strong reference needs to be applied to the font object, otherwise pyglet may not find the font later.

Parameters:: font (UserDefinedFontBase) – A font class instance defined by user.
Raises:: Exception – If font provided is not derived from UserDefinedFontBase.
Return type:: None

have_font(name: str) → bool

Check if specified font name is available in the system database or user font database.

Return type:: bool

Load a font for rendering.

Parameters:

name (str | Iterable[str] | None) – Font family, for example, “Times New Roman”. If a list of names is provided, the first one matching a known font is used. If no font can be matched to the name(s), a default font is used. The default font will be platform dependent.
size (float | None) – Size of the font, in points. The returned font may be an exact match or the closest available.
weight (str) – If set, a specific weight variant is returned if one exists for the given font family and size. The weight is provided as a string. For example: “bold” or “light”.
italic (bool | str) – If True, an italic variant is returned, if one exists for the given family and size. For some Font renderers, italics may have an “oblique” variation which can be specified as a string.
stretch (bool | str) – If True, a stretch variant is returned, if one exists for the given family and size. Currently only supported by Windows through the DirectWrite font renderer. For example, “condensed” or “expanded”.
dpi (int | None) – int The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Defaults to 96.

Return type:

Font

pyglet.font.user

This module defines the usage and creation of user defined fonts in Pyglet.

Previously, pyglet only supported font renderers that are built into the operating system, such as FreeType, DirectWrite, or Quartz. However, there are situations in which a user may not want or need all the features a font can provide. They just need to put characters in a particular order without the hassle of exporting into a separate file.

The UserDefinedMappingFont is provided for most use cases, which will allow you to make an internal font that can be used where a font_name is required to identify a font.

A user defined font is also identified by its name. The name you choose should be unique to ensure it will not conflict with a system font. For example, do not use Arial, as that will collide with Windows systems.

With UserDefinedMappingFont you can pass a mapping of characters that point to your ImageData.

mappings={'c': my_image_data, 'b': my_image_data, 'a': my_image_data}

For more custom behavior, a dict-like object can be used, such as a class.

class MyCustomMapping:
    def get(self, char: str) -> ImageData | None:
        # return ImageData if a character is found.
        # return None if no character is found

mappings = MyCustomMapping()

Once your font is created, you also must register it within pyglet to use it. This can be done through the: add_user_font() function.

When you register a user defined font, only those parameters will used to identify the font. If you have a font, but want to have a italic enabled version. You must make a new instance of your font, but with the italic parameter set as True. Same applies to the size parameter. The weight parameter can also be provided as a string.

Scaling

By default, user font’s will not be scaled. In most use cases, you have a single font at a specific size that you want to use.

There are cases where a user may want to scale their font to be used at any size. We provide the following function: get_scaled_user_font(). By providing the user defined font instance, and a new size, you will get back a new font instance that is scaled to the new size. This new instance must also be registered the same way as the base font.

When specifying the size parameter, that value is used to determine the ratio of scaling between the new size. So if your base font is a size of 12, creating a scaled version at size 24 will be double the size of the base.

Warning

The PIL library is a required dependency to use the scaling functionality.

New in version 2.0.15.

exception UserDefinedFontException: An exception related to user font creation.

class UserDefinedFontBase

Used as a base for all user defined fonts.

New in version 2.0.15.

glyph_renderer_class: alias of UserDefinedGlyphRenderer

__init__( name: str, default_char: str, size: int, ascent: int | None = None, descent: int | None = None, weight: str = 'normal', italic: bool = False, stretch: bool = False, dpi: int = 96, locale: str | None = None, ) → None

Initialize a user defined font.

Parameters:

name (str) – Name of the font. Used to identify the font. Must be unique to ensure it does not collide with any system fonts.
default_char (str) – If a character in a string is not found in the font, it will use this as fallback.
size (int) – Font size, usually in pixels.
ascent (int | None) – Maximum ascent above the baseline, in pixels. If None, the image height is used.
descent (int | None) – Maximum descent below the baseline, in pixels. Usually negative.
weight (str) – The font weight, as a string. Defaults to “normal”.
italic (bool) – If True, this font will be used when italic is enabled for the font name.
stretch (bool) – If True, this font will be used when stretch is enabled for the font name.
dpi (int) – The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Use a default of 96 for standard sizing.
locale (str | None) – Used to specify the locale of this font.

enable_scaling(base_size: int) → None

Return type:: None

property name: str: Return the Family Name of the font as a string.

class UserDefinedMappingFont

The class allows the creation of user defined fonts from a set of mappings.

New in version 2.0.15.

__init__( name: str, default_char: str, size: int, mappings: DictLikeObject, ascent: int | None = None, descent: int | None = None, weight: str = 'normal', italic: bool = False, stretch: bool = False, dpi: int = 96, locale: str | None = None, ) → None

Initialize the default parameters of your font.

Parameters:

name (str) – Name of the font. Must be unique to ensure it does not collide with any system fonts.
default_char (str) – If a character in a string is not found in the font, it will use this as fallback.
size (int) – Font size. Should be in pixels. This value will affect scaling if enabled.
mappings (DictLikeObject) – A dict or dict-like object with a get function. The get function must take a string character, and output ImageData if found. It also must return None if no character is found.
ascent (int | None) – Maximum ascent above the baseline, in pixels. If None, the image height is used.
descent (int | None) – Maximum descent below the baseline, in pixels. Usually negative.
weight (str) – The font weight, as a string. Defaults to “normal”.
italic (bool) – If True, this font will be used when italic is enabled for the font name.
stretch (bool) – If True, this font will be used when stretch is enabled for the font name.
dpi (int) – The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Use a default of 96 for standard sizing.
locale (str | None) – Used to specify the locale of this font.

enable_scaling(base_size: int) → None

Enables scaling the font size.

Parameters:: base_size (int) – The base size is used to calculate the ratio between new sizes and the original.
Return type:: None

get_glyphs(text: str) → list[pyglet.font.base.Glyph]

Create and return a list of Glyphs for text.

If any characters do not have a known glyph representation in this font, a substitution will be made with the default_char.

Return type:: list[Glyph]

get_scaled_user_font( font_base: UserDefinedMappingFont, size: int, ) → UserDefinedMappingFont

This function will return a new font instance which can scale it’s size based off the original base font.

Note

The scaling functionality requires the PIL library to be installed.

New in version 2.0.15.

Parameters:

font_base (UserDefinedMappingFont) – The base font object to create a new size from.
size (int) – The new font size. This will be scaled based on the ratio between the base size and the new size.

Return type:

UserDefinedMappingFont