pdftools_toolbox.pdf.content.font

Classes

Font(handle)

class pdftools_toolbox.pdf.content.font.Font(handle)

Bases: _NativeObject

static create(target_document: Document, stream: IOBase, embedded: bool) → Font

Create a new font object from font file data.

Supported formats are:

• Type1

• CFF

• TrueType

• OpenType

The returned font object is not yet used on any page, but it is associated with the given target document.

Parameters:

• targetDocument (pdftools_toolbox.pdf.document.Document) – the output document with which the returned object is associated

• stream (io.IOBase) – the font file data stream

• embedded (bool) – True if the font shall be embedded in the document. Note that this parameter must be True for PDF/A documents.

Returns:

the newly created font object

Return type:

pdftools_toolbox.pdf.content.font.Font

Raises:

• OSError – Error reading from the font file or writing to the document

• pdftools_toolbox.unknown_format_error.UnknownFormatError – The font data has an unknown format

• pdftools_toolbox.corrupt_error.CorruptError – The font data is corrupt

• pdftools_toolbox.conformance_error.ConformanceError – Parameter embedded is False for PDF/A document

• ValueError – if the targetDocument argument has already been closed

• ValueError – if the targetDocument argument is read-only

• ValueError – if the stream argument is None

static create_from_system(target_document: Document, family: str | None, style: str | None, embedded: bool) → Font

Create a new font object from an installed font.

The returned font object is not yet used on any page, but it is associated with the given target document.

Parameters:

• targetDocument (pdftools_toolbox.pdf.document.Document) – the output document with which the returned object is associated

• family (Optional[str]) – the font family name (e.g. “Arial”)

• style (Optional[str]) – the font style (e.g. “Bold”)

• embedded (bool) – True if the font shall be embedded in the document. Note that this parameter must be True for PDF/A documents.

Returns:

the newly created font object

Return type:

pdftools_toolbox.pdf.content.font.Font

Raises:

• pdftools_toolbox.not_found_error.NotFoundError – There is no such font installed

• OSError – Error reading the font file or writing to the document

• pdftools_toolbox.unknown_format_error.UnknownFormatError – The font data has an unknown format

• pdftools_toolbox.corrupt_error.CorruptError – The font data is corrupt

• pdftools_toolbox.conformance_error.ConformanceError – Parameter embedded is False for PDF/A document

• ValueError – if the targetDocument argument has already been closed

• ValueError – if the targetDocument argument is read-only

• ValueError – if the family argument is None

get_character_width(character: int) → float

the width of a single glyph.

The width of a unicode character (in pt) relative to a font size of 1 pt.

If an error occurs (because the font or the owning document has already been closed) this method returns 0. But a return value of 0 is not generally an indication for failure.

Parameters:

character (int) – the unicode character code.

Returns:

the width of the character

Return type:

float

property base_font: str | None

the PostScript name of the font

Returns:

Optional[str]

Raises:

• StateError – if the font has already been closed

• pdftools_toolbox.corrupt_error.CorruptError – if the font’s base name is missing or cannot be decoded

property weight: FontWeight | None

the visual weight of the font.

Indicates the visual weight (degree of blackness or thickness of strokes) of the characters in the font. If the font does not define this value, None is returned.

Returns:

Optional[pdftools_toolbox.pdf.content.font_weight.FontWeight]

Raises:

StateError – if the font has already been closed

property italic_angle: float

the italic angle of the font.

The angle is expressed in degrees counterclockwise from the vertical, of the dominant vertical strokes of the font. (For example, the 9-o’clock position is 90 degrees, and the 3-o’clock position is –90 degrees.) The value is negative for fonts that slope to the right, as almost all italic fonts do.

Returns:

float

Raises:

StateError – if the font has already been closed

property ascent: float

the ascent of the font.

The maximum height above the baseline reached by glyphs in this font, excluding the height of glyphs for accented characters.

Returns:

float

Raises:

StateError – if the font has already been closed

property descent: float

the descent of the font.

The maximum depth below the baseline reached by glyphs in this font. The value is a negative number.

Returns:

float

Raises:

StateError – if the font has already been closed

property cap_height: float

the cap height of the font.

The vertical coordinate of the top of flat capital letters, measured from the baseline.

Returns:

float

Raises:

StateError – if the font has already been closed

property leading: float | None

the leading of the font.

The vertical distance between two adjacent base lines in multiline text.

This is a recomended value when generating several lines of text. If the font does not define this value, None is returned.

Note that pdftools_toolbox.pdf.content.text_generator.TextGenerator.__init__ uses a fixed value of 1.2 instead of this property to initialize the pdftools_toolbox.pdf.content.text_generator.TextGenerator.leading in order to maintain backward compatibility with earlier versions.

Returns:

Optional[float]

Raises:

StateError – if the font has already been closed

property is_embedded: bool

Specifies whether the font is embedded.

Returns:

bool

Raises:

StateError – if the font has already been closed