Module fpdf.fonts

Font-related classes & constants. Includes the definition of the character widths of all PDF standard fonts.

The contents of this module are internal to fpdf2, and not part of the public API. They may change at any time without prior warning or any deprecation period, in non-backward-compatible ways.

Classes

class CoreFont (fpdf, fontkey, style)

Expand source code Browse git

class CoreFont:
    # RAM usage optimization:
    __slots__ = ("i", "type", "name", "up", "ut", "cw", "fontkey", "emphasis")

    def __init__(self, fpdf, fontkey, style):
        self.i = len(fpdf.fonts) + 1
        self.type = "core"
        self.name = CORE_FONTS[fontkey]
        self.up = -100
        self.ut = 50
        self.cw = CORE_FONTS_CHARWIDTHS[fontkey]
        self.fontkey = fontkey
        self.emphasis = TextEmphasis.coerce(style)

    def get_text_width(self, text, font_size_pt, _):
        return (len(text), sum(self.cw[c] for c in text) * font_size_pt * 0.001)

    # Disabling this check - method kept as is to have same method/signature on CoreConf and TTFFont:
    # pylint: disable=no-self-use
    def encode_text(self, text):
        return f"({escape_parens(text)}) Tj"

    def __repr__(self):
        return f"CoreFont(i={self.i}, fontkey={self.fontkey})"

Instance variables

var cw

var emphasis

var fontkey

var i

var name

var type

var up

var ut

Methods

def encode_text(self, text)

def get_text_width(self, text, font_size_pt, _)

class FontFace (family=None, emphasis=None, size_pt=None, color=None, fill_color=None)

Represent basic font styling properties. This is a subset of GraphicsStateMixin properties.

Expand source code Browse git

@dataclass
class FontFace:
    """
    Represent basic font styling properties.
    This is a subset of `fpdf.graphics_state.GraphicsStateMixin` properties.
    """

    __slots__ = (  # RAM usage optimization
        "family",
        "emphasis",
        "size_pt",
        "color",
        "fill_color",
    )
    family: Optional[str]
    emphasis: Optional[TextEmphasis]  # None means "no override"
    #                                   Whereas "" means "no emphasis"
    #                                   This can be a combination: B | U
    size_pt: Optional[int]
    # Colors are single number grey scales or (red, green, blue) tuples:
    color: Optional[Union[DeviceGray, DeviceRGB]]
    fill_color: Optional[Union[DeviceGray, DeviceRGB]]

    def __init__(
        self, family=None, emphasis=None, size_pt=None, color=None, fill_color=None
    ):
        self.family = family
        self.emphasis = None if emphasis is None else TextEmphasis.coerce(emphasis)
        self.size_pt = size_pt
        self.color = None if color is None else convert_to_device_color(color)
        self.fill_color = (
            None if fill_color is None else convert_to_device_color(fill_color)
        )

    replace = replace

    @staticmethod
    def _override(current_value, override_value):
        """Override the current value if an override value is provided"""
        return current_value if override_value is None else override_value

    @staticmethod
    def combine(default_style, override_style):
        """
        Create a combined FontFace with all the supplied features of the two styles. When both
        the default and override styles provide a feature, prefer the override style.
        Override specified FontFace style features
        Override this FontFace's values with the values of `other`.
        Values of `other` that are None in this FontFace will be kept unchanged.
        """
        if override_style is None:
            return default_style
        if default_style is None:
            return override_style
        if not isinstance(override_style, FontFace):
            raise TypeError(f"Cannot combine FontFace with {type(override_style)}")
        if not isinstance(default_style, FontFace):
            raise TypeError(f"Cannot combine FontFace with {type(default_style)}")
        return FontFace(
            family=FontFace._override(default_style.family, override_style.family),
            emphasis=FontFace._override(
                default_style.emphasis,
                override_style.emphasis,
            ),
            size_pt=FontFace._override(default_style.size_pt, override_style.size_pt),
            color=FontFace._override(default_style.color, override_style.color),
            fill_color=FontFace._override(
                default_style.fill_color, override_style.fill_color
            ),
        )

Subclasses

• TextStyle

Static methods

def combine(default_style, override_style)

Create a combined FontFace with all the supplied features of the two styles. When both the default and override styles provide a feature, prefer the override style. Override specified FontFace style features Override this FontFace's values with the values of other. Values of other that are None in this FontFace will be kept unchanged.

Instance variables

var color : Union[DeviceGray, DeviceRGB, ForwardRef(None)]

var emphasis : Optional[TextEmphasis]

var family : Optional[str]

var fill_color : Union[DeviceGray, DeviceRGB, ForwardRef(None)]

var size_pt : Optional[int]

Methods

def replace(obj, /, **changes)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage::

@dataclass(frozen=True) class C: x: int y: int

c = C(1, 2) c1 = replace(c, x=3) assert c1.x == 3 and c1.y == 2

class Glyph (glyph_id: int, unicode: Tuple, glyph_name: str, glyph_width: int)

This represents one glyph on the font Unicode is a tuple because ligatures or character substitution can map a sequence of unicode characters to a single glyph

Expand source code Browse git

@dataclass(order=True)
class Glyph:
    """
    This represents one glyph on the font
    Unicode is a tuple because ligatures or character substitution
    can map a sequence of unicode characters to a single glyph
    """

    # RAM usage optimization:
    __slots__ = ("glyph_id", "unicode", "glyph_name", "glyph_width")
    glyph_id: int
    unicode: Tuple
    glyph_name: str
    glyph_width: int

    def __hash__(self):
        return self.glyph_id

Instance variables

var glyph_id : int

var glyph_name : str

var glyph_width : int

var unicode : Tuple

class HarfBuzzFont (...)

uharfbuzz.Font than can be deepcopied

Expand source code Browse git

class HarfBuzzFont(hb.Font):
    "uharfbuzz.Font than can be deepcopied"

    # cf. issue #1075, avoids: TypeError: no default __reduce__ due to non-trivial __cinit__
    def __deepcopy__(self, _memo):
        return self

Ancestors

• uharfbuzz._harfbuzz.Font

class PDFFontDescriptor (ascent, descent, cap_height, flags, font_b_box, italic_angle, stem_v, missing_width)

Main features of this class: * delay ID assignement * implement serializing

Expand source code Browse git

class PDFFontDescriptor(PDFObject):
    def __init__(
        self,
        ascent,
        descent,
        cap_height,
        flags,
        font_b_box,
        italic_angle,
        stem_v,
        missing_width,
    ):
        super().__init__()
        self.type = Name("FontDescriptor")
        self.ascent = ascent
        self.descent = descent
        self.cap_height = cap_height
        self.flags = flags
        self.font_b_box = font_b_box
        self.italic_angle = italic_angle
        self.stem_v = stem_v
        self.missing_width = missing_width
        self.font_name = None

Ancestors

• PDFObject

Inherited members

• PDFObject:
  • content_stream
  • serialize

class SubsetMap (font: TTFFont, identities: List[int])

Holds a mapping of used characters and their position in the font's subset

Characters that must be mapped on their actual unicode must be part of the identities list during object instanciation. These non-negative values should only appear once in the list. pick() can be used to get the characters corresponding position in the subset. If it's not yet part of the object, a new position is acquired automatically. This implementation always tries to return the lowest possible representation.

Expand source code Browse git

class SubsetMap:
    """
    Holds a mapping of used characters and their position in the font's subset

    Characters that must be mapped on their actual unicode must be part of the
    `identities` list during object instanciation. These non-negative values should
    only appear once in the list. `pick()` can be used to get the characters
    corresponding position in the subset. If it's not yet part of the object, a new
    position is acquired automatically. This implementation always tries to return
    the lowest possible representation.
    """

    def __init__(self, font: TTFFont, identities: List[int]):
        super().__init__()
        self.font = font
        self._next = 0

        # sort list to ease deletion once _next
        # becomes higher than first reservation
        self._reserved = sorted(identities)

        # Maps Glyph instances to character IDs (integers):
        self._char_id_per_glyph = {}
        for x in self._reserved:
            glyph = self.get_glyph(unicode=x)
            if glyph:
                self._char_id_per_glyph[glyph] = int(x)

    def __repr__(self):
        return (
            f"SubsetMap(font={self.font}, _next={self._next},"
            f" _reserved={self._reserved}, _char_id_per_glyph={self._char_id_per_glyph})"
        )

    def __len__(self):
        return len(self._char_id_per_glyph)

    def items(self):
        for glyph, char_id in self._char_id_per_glyph.items():
            yield glyph, char_id

    # pylint: disable=method-cache-max-size-none
    @lru_cache(maxsize=None)
    def pick(self, unicode: int):
        glyph = self.get_glyph(unicode=unicode)
        if glyph is None and unicode not in self.font.missing_glyphs:
            self.font.missing_glyphs.append(unicode)
        return self.pick_glyph(glyph)

    def pick_glyph(self, glyph):
        char_id = self._char_id_per_glyph.get(glyph)
        if glyph and char_id is None:
            while self._next in self._reserved:
                self._next += 1
                if self._next > self._reserved[0]:
                    del self._reserved[0]
            char_id = self._next
            self._char_id_per_glyph[glyph] = char_id
            self._next += 1
        return char_id

    # pylint: disable=method-cache-max-size-none
    @lru_cache(maxsize=None)
    def get_glyph(
        self, glyph=None, unicode=None, glyph_name=None, glyph_width=None
    ) -> Glyph:
        if glyph:
            return Glyph(glyph, tuple(unicode), glyph_name, glyph_width)
        glyph_id = self.font.glyph_ids.get(unicode)
        if isinstance(unicode, int) and glyph_id is not None:
            return Glyph(
                glyph_id,
                (unicode,),
                self.font.cmap[unicode],
                self.font.cw[unicode],
            )
        if unicode == 0x00:
            glyph_id = next(iter(self.font.cmap))
            return Glyph(glyph_id, (0x00,), ".notdef", 0)
        return None

    def get_all_glyph_names(self):
        return [glyph.glyph_name for glyph in self._char_id_per_glyph]

Methods

def get_all_glyph_names(self)

def get_glyph(self, glyph=None, unicode=None, glyph_name=None, glyph_width=None) ‑> Glyph

def items(self)

def pick(self, unicode: int)

def pick_glyph(self, glyph)

class TTFFont (fpdf, font_file_path, fontkey, style)

Expand source code Browse git

class TTFFont:
    __slots__ = (  # RAM usage optimization
        "i",
        "type",
        "name",
        "desc",
        "glyph_ids",
        "hbfont",
        "up",
        "ut",
        "cw",
        "ttffile",
        "fontkey",
        "emphasis",
        "scale",
        "subset",
        "cmap",
        "ttfont",
        "missing_glyphs",
    )

    def __init__(self, fpdf, font_file_path, fontkey, style):
        self.i = len(fpdf.fonts) + 1
        self.type = "TTF"
        self.ttffile = font_file_path
        self.fontkey = fontkey

        # recalcTimestamp=False means that it doesn't modify the "modified" timestamp in head table
        # if we leave recalcTimestamp=True the tests will break every time
        self.ttfont = ttLib.TTFont(
            self.ttffile, recalcTimestamp=False, fontNumber=0, lazy=True
        )

        self.scale = 1000 / self.ttfont["head"].unitsPerEm
        default_width = round(self.scale * self.ttfont["hmtx"].metrics[".notdef"][0])

        try:
            cap_height = self.ttfont["OS/2"].sCapHeight
        except AttributeError:
            cap_height = self.ttfont["hhea"].ascent

        # entry for the PDF font descriptor specifying various characteristics of the font
        flags = FontDescriptorFlags.SYMBOLIC
        if self.ttfont["post"].isFixedPitch:
            flags |= FontDescriptorFlags.FIXED_PITCH
        if self.ttfont["post"].italicAngle != 0:
            flags |= FontDescriptorFlags.ITALIC
        if self.ttfont["OS/2"].usWeightClass >= 600:
            flags |= FontDescriptorFlags.FORCE_BOLD

        self.desc = PDFFontDescriptor(
            ascent=round(self.ttfont["hhea"].ascent * self.scale),
            descent=round(self.ttfont["hhea"].descent * self.scale),
            cap_height=round(cap_height * self.scale),
            flags=flags,
            font_b_box=(
                f"[{self.ttfont['head'].xMin * self.scale:.0f} {self.ttfont['head'].yMin * self.scale:.0f}"
                f" {self.ttfont['head'].xMax * self.scale:.0f} {self.ttfont['head'].yMax * self.scale:.0f}]"
            ),
            italic_angle=int(self.ttfont["post"].italicAngle),
            stem_v=round(50 + int(pow((self.ttfont["OS/2"].usWeightClass / 65), 2))),
            missing_width=default_width,
        )

        # a map unicode_char -> char_width
        self.cw = defaultdict(lambda: default_width)

        # fonttools cmap = unicode char to glyph name
        # saving only the keys we have a tuple with
        # the unicode characters available on the font
        self.cmap = self.ttfont.getBestCmap()

        # saving a list of glyph ids to char to allow
        # subset by unicode (regular) and by glyph
        # (shaped with harfbuz)
        self.glyph_ids = {}

        for char in self.cmap:
            # take glyph associated to char
            glyph = self.cmap[char]

            # take width associated to glyph
            w = self.ttfont["hmtx"].metrics[glyph][0]

            # probably this check could be deleted
            if w == 65535:
                w = 0

            self.cw[char] = round(self.scale * w + 0.001)  # ROUND_HALF_UP

            self.glyph_ids[char] = self.ttfont.getGlyphID(glyph)

        self.missing_glyphs = []

        # include numbers in the subset! (if alias present)
        # ensure that alias is mapped 1-by-1 additionally (must be replaceable)
        sbarr = "\x00 \r\n"
        if fpdf.str_alias_nb_pages:
            sbarr += "0123456789"
            sbarr += fpdf.str_alias_nb_pages

        self.name = re.sub("[ ()]", "", self.ttfont["name"].getBestFullName())
        self.up = round(self.ttfont["post"].underlinePosition * self.scale)
        self.ut = round(self.ttfont["post"].underlineThickness * self.scale)
        self.emphasis = TextEmphasis.coerce(style)
        self.subset = SubsetMap(self, [ord(char) for char in sbarr])

    def __repr__(self):
        return f"TTFFont(i={self.i}, fontkey={self.fontkey})"

    def close(self):
        self.ttfont.close()
        self.hbfont = None

    def get_text_width(self, text, font_size_pt, text_shaping_parms):
        if text_shaping_parms:
            return self.shaped_text_width(text, font_size_pt, text_shaping_parms)
        return (len(text), sum(self.cw[ord(c)] for c in text) * font_size_pt * 0.001)

    def shaped_text_width(self, text, font_size_pt, text_shaping_parms):
        """
        When texts are shaped, the length of a string is not always the sum of all individual character widths
        This method will invoke harfbuzz to perform the text shaping and return the sum of "x_advance"
        and "x_offset" for each glyph. This method works for "left to right" or "right to left" texts.
        """
        _, glyph_positions = self.perform_harfbuzz_shaping(
            text, font_size_pt, text_shaping_parms
        )

        # If there is nothing to render (harfbuzz returns None), we return 0 text width
        if glyph_positions is None:
            return (0, 0)

        text_width = 0
        for pos in glyph_positions:
            text_width += (
                round(self.scale * pos.x_advance + 0.001) * font_size_pt * 0.001
            )
        return (len(glyph_positions), text_width)

    # Disabling this check - looks like cython confuses pylint:
    # pylint: disable=no-member
    def perform_harfbuzz_shaping(self, text, font_size_pt, text_shaping_parms):
        """
        This method invokes Harfbuzz to perform text shaping of the input string
        """
        if not hasattr(self, "hbfont"):
            self.hbfont = HarfBuzzFont(hb.Face(hb.Blob.from_file_path(self.ttffile)))
        self.hbfont.ptem = font_size_pt
        buf = hb.Buffer()
        buf.cluster_level = 1
        buf.add_str("".join(text))
        buf.guess_segment_properties()
        features = text_shaping_parms["features"]
        if text_shaping_parms["fragment_direction"]:
            buf.direction = text_shaping_parms["fragment_direction"].value
        if text_shaping_parms["script"]:
            buf.script = text_shaping_parms["script"]
        if text_shaping_parms["language"]:
            buf.language = text_shaping_parms["language"]
        hb.shape(self.hbfont, buf, features)
        return buf.glyph_infos, buf.glyph_positions

    def encode_text(self, text):
        txt_mapped = ""
        for char in text:
            uni = ord(char)
            # Instead of adding the actual character to the stream its code is
            # mapped to a position in the font's subset
            txt_mapped += chr(self.subset.pick(uni))
        return f'({escape_parens(txt_mapped.encode("utf-16-be").decode("latin-1"))}) Tj'

    def shape_text(self, text, font_size_pt, text_shaping_parms):
        """
        This method will invoke harfbuzz for text shaping, include the mapping code
        of the glyphs on the subset and map input characters to the cluster codes
        """
        if len(text) == 0:
            return []
        glyph_infos, glyph_positions = self.perform_harfbuzz_shaping(
            text, font_size_pt, text_shaping_parms
        )
        text_info = []

        # Find cluster gaps
        # Ex: text = "ABCD"
        # glyph infos has cluster: 0, 2, 3 - it means A and B are together on the first glyph
        # (ligature or substitution) - the glyph should have both unicodes and it should be translated
        # properly on the CID to GID mapping
        #
        def get_cluster_from_text_index(cluster_list, index):
            pos = bisect_left(cluster_list, index)
            if pos == 0:
                return cluster_list[0]
            if pos == len(cluster_list) or cluster_list[pos] != index:
                return cluster_list[pos - 1]
            return cluster_list[pos]

        cluster_list = list(sorted(int(gi.cluster) for gi in glyph_infos))
        cluster_mapping = {}
        for i in range(len(text)):
            cl = get_cluster_from_text_index(cluster_list, i)
            if cl in cluster_mapping:
                cluster_mapping[cl].append(i)
            else:
                cluster_mapping[cl] = [i]

        for cluster_seq, gi in enumerate(glyph_infos):
            unicode = []
            if gi.cluster in cluster_mapping:
                unicode = [ord(text[i]) for i in cluster_mapping[gi.cluster]]
                cluster_mapping.pop(gi.cluster)

            gname = self.ttfont.getGlyphName(gi.codepoint)
            gwidth = round(self.scale * self.ttfont["hmtx"].metrics[gname][0])
            glyph = self.subset.get_glyph(
                glyph=gi.codepoint,
                unicode=tuple(unicode),
                glyph_name=gname,
                glyph_width=gwidth,
            )
            force_positioning = False
            if (
                gwidth != glyph_positions[cluster_seq].x_advance
                or glyph_positions[cluster_seq].x_offset != 0
                or glyph_positions[cluster_seq].y_offset != 0
                or glyph_positions[cluster_seq].y_advance != 0
            ):
                force_positioning = True
            text_info.append(
                {
                    "mapped_char": self.subset.pick_glyph(glyph),
                    "x_advance": glyph_positions[cluster_seq].x_advance,
                    "y_advance": glyph_positions[cluster_seq].y_advance,
                    "x_offset": glyph_positions[cluster_seq].x_offset,
                    "y_offset": glyph_positions[cluster_seq].y_offset,
                    "force_positioning": force_positioning,
                }
            )
        return text_info

Instance variables

var cmap

var cw

var desc

var emphasis

var fontkey

var glyph_ids

var hbfont

var i

var missing_glyphs

var name

var scale

var subset

var ttffile

var ttfont

var type

var up

var ut

Methods

def close(self)

def encode_text(self, text)

def get_text_width(self, text, font_size_pt, text_shaping_parms)

def perform_harfbuzz_shaping(self, text, font_size_pt, text_shaping_parms)

This method invokes Harfbuzz to perform text shaping of the input string

def shape_text(self, text, font_size_pt, text_shaping_parms)

This method will invoke harfbuzz for text shaping, include the mapping code of the glyphs on the subset and map input characters to the cluster codes

def shaped_text_width(self, text, font_size_pt, text_shaping_parms)

When texts are shaped, the length of a string is not always the sum of all individual character widths This method will invoke harfbuzz to perform the text shaping and return the sum of "x_advance" and "x_offset" for each glyph. This method works for "left to right" or "right to left" texts.

class TextStyle (font_family: Optional[str] = None, font_style: Optional[str] = None, font_size_pt: Optional[int] = None, color: Union[int, tuple] = None, fill_color: Union[int, tuple] = None, underline: bool = False, t_margin: Optional[int] = None, l_margin: Optional[int] = None, b_margin: Optional[int] = None)

Subclass of FontFace that allows to specify vertical & horizontal spacing

Expand source code Browse git

class TextStyle(FontFace):
    """
    Subclass of `FontFace` that allows to specify vertical & horizontal spacing
    """

    def __init__(
        self,
        font_family: Optional[str] = None,  # None means "no override"
        #                                     Whereas "" means "no emphasis"
        font_style: Optional[str] = None,
        font_size_pt: Optional[int] = None,
        color: Union[int, tuple] = None,  # grey scale or (red, green, blue),
        fill_color: Union[int, tuple] = None,  # grey scale or (red, green, blue),
        underline: bool = False,
        t_margin: Optional[int] = None,
        l_margin: Optional[int] = None,
        b_margin: Optional[int] = None,
    ):
        super().__init__(
            font_family,
            ((font_style or "") + "U") if underline else font_style,
            font_size_pt,
            color,
            fill_color,
        )
        self.t_margin = t_margin or 0
        self.l_margin = l_margin or 0
        self.b_margin = b_margin or 0

    def __repr__(self):
        return (
            super().__repr__()[:-1]
            + f", t_margin={self.t_margin}, l_margin={self.l_margin}, b_margin={self.b_margin})"
        )

    def replace(
        self,
        /,
        font_family=None,
        emphasis=None,
        font_size_pt=None,
        color=None,
        fill_color=None,
        t_margin=None,
        l_margin=None,
        b_margin=None,
    ):
        return TextStyle(
            font_family=font_family or self.family,
            font_style=self.emphasis if emphasis is None else emphasis.style,
            font_size_pt=font_size_pt or self.size_pt,
            color=color or self.color,
            fill_color=fill_color or self.fill_color,
            t_margin=self.t_margin if t_margin is None else t_margin,
            l_margin=self.l_margin if l_margin is None else l_margin,
            b_margin=self.b_margin if b_margin is None else b_margin,
        )

Ancestors

• FontFace

Subclasses

• fpdf.fonts.TitleStyle

Inherited members

• FontFace:
  • combine
  • replace