pyhanko.pdf_utils.font package

Submodules

pyhanko.pdf_utils.font.api module

class pyhanko.pdf_utils.font.api.FontEngine(writer: BasePdfFileWriter, base_postscript_name: str, embedded_subset: bool, obj_stream=None)

Bases: object

General interface for text shaping and font metrics.

property uses_complex_positioning

If True, this font engine expects the line matrix to always be equal to the text matrix when exiting and entering shape(). In other words, the current text position is where 0 0 Td would move to.

If False, this method does not use any text positioning operators, and therefore uses the PDF standard’s ‘natural’ positioning rules for text showing operators.

The default is True unless overridden.

shape(txt: str) → ShapeResult

Render a string to a format suitable for inclusion in a content stream and measure its total cursor advancement vector in em units.

Parameters:

txt – String to shape.

Returns:

A shaping result.

as_resource() → PdfObject

Convert a FontEngine to a PDF object suitable for embedding inside a resource dictionary.

Note

If the PDF object is an indirect reference, the caller must not attempt to dereference it. In other words, implementations can use preallocated references to delay subsetting until the last possible moment (this is even encouraged, see prepare_write()).

Returns:

A PDF dictionary.

prepare_write()

Called by the writer that manages this font resource before the PDF content is written to a stream.

Subsetting operations and the like should be carried out as part of this method.

class pyhanko.pdf_utils.font.api.FontEngineFactory

Bases: object

create_font_engine(writer: BasePdfFileWriter, obj_stream=None) → FontEngine
class pyhanko.pdf_utils.font.api.FontSubsetCollection(base_postscript_name: str, subsets: Dict[Optional[str], ForwardRef('FontEngine')] = <factory>)

Bases: object

base_postscript_name: str

Base postscript name of the font.

subsets: Dict[str | None, FontEngine]

Dictionary mapping prefixes to subsets. None represents the full font.

add_subset() → str
class pyhanko.pdf_utils.font.api.ShapeResult(graphics_ops: bytes, x_advance: float, y_advance: float)

Bases: object

Result of shaping a Unicode string.

graphics_ops: bytes

PDF graphics operators to render the glyphs.

x_advance: float

Total horizontal advance in em units.

y_advance: float

Total vertical advance in em units.

pyhanko.pdf_utils.font.basic module

class pyhanko.pdf_utils.font.basic.SimpleFontEngine(writer: BasePdfFileWriter, name: str, avg_width: float, meta: SimpleFontMeta | None = None)

Bases: FontEngine

Simplistic font engine that effectively only works with PDF standard fonts, and does not care about font metrics. Best used with monospaced fonts such as Courier.

property uses_complex_positioning

If True, this font engine expects the line matrix to always be equal to the text matrix when exiting and entering shape(). In other words, the current text position is where 0 0 Td would move to.

If False, this method does not use any text positioning operators, and therefore uses the PDF standard’s ‘natural’ positioning rules for text showing operators.

The default is True unless overridden.

shape(txt) → ShapeResult

Render a string to a format suitable for inclusion in a content stream and measure its total cursor advancement vector in em units.

Parameters:

txt – String to shape.

Returns:

A shaping result.

as_resource()

Convert a FontEngine to a PDF object suitable for embedding inside a resource dictionary.

Note

If the PDF object is an indirect reference, the caller must not attempt to dereference it. In other words, implementations can use preallocated references to delay subsetting until the last possible moment (this is even encouraged, see prepare_write()).

Returns:

A PDF dictionary.

class pyhanko.pdf_utils.font.basic.SimpleFontEngineFactory(name: str, avg_width: float, meta: SimpleFontMeta | None = None)

Bases: FontEngineFactory

create_font_engine(writer: BasePdfFileWriter, obj_stream=None)
static default_factory()
Returns:

A FontEngineFactory instance representing the Courier standard font.

class pyhanko.pdf_utils.font.basic.SimpleFontMeta(first_char: int, last_char: int, widths: List[int], descriptor: pyhanko.pdf_utils.generic.DictionaryObject)

Bases: object

first_char: int
last_char: int
widths: List[int]
descriptor: DictionaryObject
pyhanko.pdf_utils.font.basic.get_courier(pdf_writer: BasePdfFileWriter)

Quick-and-dirty way to obtain a Courier font resource.

Parameters:

pdf_writer – A PDF writer.

Returns:

A resource dictionary representing the standard Courier font (or one of its metric equivalents).

pyhanko.pdf_utils.font.opentype module

Basic support for OpenType/TrueType font handling & subsetting.

This module relies on fontTools for OTF parsing and subsetting, and on HarfBuzz (via uharfbuzz) for shaping.

class pyhanko.pdf_utils.font.opentype.GlyphAccumulator(writer: BasePdfFileWriter, font_handle, font_size, features=None, ot_language_tag=None, ot_script_tag=None, writing_direction=None, bcp47_lang_code=None, obj_stream=None)

Bases: FontEngine

Utility to collect & measure glyphs from OpenType/TrueType fonts.

Parameters:

  • writer – A PDF writer.

  • font_handle – File-like object

  • font_size –

    Font size in pt units.

    Note

    This is only relevant for some positioning intricacies (or hacks, depending on your perspective) that may not matter for your use case.

  • features – Features to use. If None, use HarfBuzz defaults.

  • ot_script_tag – OpenType script tag to use. Will be guessed by HarfBuzz if not specified.

  • ot_language_tag – OpenType language tag to use. Defaults to the default language system for the current script.

  • writing_direction – Writing direction, one of ‘ltr’, ‘rtl’, ‘ttb’ or ‘btt’. Will be guessed by HarfBuzz if not specified.

  • bcp47_lang_code – BCP 47 language code. Used to mark the text’s language in the PDF content stream, if specified.

  • obj_stream – Try to put font-related objects into a particular object stream, if specified.

marked_content_property_list(txt) → DictionaryObject
shape(txt: str, with_actual_text: bool = True) → ShapeResult

Render a string to a format suitable for inclusion in a content stream and measure its total cursor advancement vector in em units.

Parameters:

txt – String to shape.

Returns:

A shaping result.

prepare_write()

This implementation of prepare_write will embed a subset of this glyph accumulator’s font into the PDF writer it belongs to. Said subset will include all glyphs necessary to render the strings provided to the accumulator via feed_string().

Danger

Due to the way fontTools handles subsetting, this is a destructive operation. The in-memory representation of the original font will be overwritten by the generated subset.

as_resource() → IndirectObject

Convert a FontEngine to a PDF object suitable for embedding inside a resource dictionary.

Note

If the PDF object is an indirect reference, the caller must not attempt to dereference it. In other words, implementations can use preallocated references to delay subsetting until the last possible moment (this is even encouraged, see prepare_write()).

Returns:

A PDF dictionary.

class pyhanko.pdf_utils.font.opentype.GlyphAccumulatorFactory(font_file: str, font_size: int = 10, ot_script_tag: str | None = None, ot_language_tag: str | None = None, writing_direction: str | None = None, bcp47_lang_code: str | None = None, create_objstream_if_needed: bool = True)

Bases: FontEngineFactory

Stateless callable helper class to instantiate GlyphAccumulator objects.

font_file: str

Path to the OTF/TTF font to load.

font_size: int = 10

Font size.

ot_script_tag: str | None = None

OpenType script tag to use. Will be guessed by HarfBuzz if not specified.

ot_language_tag: str | None = None

OpenType language tag to use. Defaults to the default language system for the current script.

writing_direction: str | None = None

Writing direction, one of ‘ltr’, ‘rtl’, ‘ttb’ or ‘btt’. Will be guessed by HarfBuzz if not specified.

bcp47_lang_code: str | None = None

BCP 47 language code to tag strings with.

create_objstream_if_needed: bool = True

Create an object stream to hold this glyph accumulator’s assets if no object stream is passed in, and the writer supports object streams.

create_font_engine(writer: BasePdfFileWriter, obj_stream=None) → GlyphAccumulator