Base table classes and API

Overview:

The modules documented on this page are the base classes on which the fontTools.ttLib table converters are built. The DefaultTable is the most general; asciiTable is a simpler option for storing text-based data. For OpenType and TrueType fonts, the otBase.BaseTTXConverter leverages the model used by the majority of existing OpenType/TrueType converters.

Contributing your own table convertors 

To add support for a new font table that fontTools does not currently implement, you must subclass from fontTools.ttLib.tables.DefaultTable.DefaultTable. It provides some default behavior, as well as a constructor method (__init__) that you don’t need to override.

Your converter should minimally provide two methods:

class table_F_O_O_(DefaultTable.DefaultTable): # converter for table 'FOO '

    def decompile(self, data, ttFont):
        # 'data' is the raw table data. Unpack it into a
        # Python data structure.
        # 'ttFont' is a ttLib.TTfile instance, enabling you to
        # refer to other tables. Do ***not*** keep a reference to
        # it: it will cause a circular reference (ttFont saves
        # a reference to us), and that means we'll be leaking
        # memory. If you need to use it in other methods, just
        # pass it around as a method argument.

    def compile(self, ttFont):
        # Return the raw data, as converted from the Python
        # data structure.
        # Again, 'ttFont' is there so you can access other tables.
        # Same warning applies.

If you want to support TTX import/export as well, you need to provide two additional methods:

def toXML(self, writer, ttFont):
   # XXX

def fromXML(self, (name, attrs, content), ttFont):
   # XXX

fontTools.ttLib.tables.DefaultTable 

class fontTools.ttLib.tables.DefaultTable.DefaultTable(tag=None)[source]

Bases: object

dependencies = []

decompile(data, ttFont)[source]

compile(ttFont)[source]

toXML(writer, ttFont, **kwargs)[source]

fromXML(name, attrs, content, ttFont)[source]

merge(m, tables)

fontTools.ttLib.tables.asciiTable 

class fontTools.ttLib.tables.asciiTable.asciiTable(tag=None)[source]

Bases: DefaultTable

toXML(writer, ttFont)[source]

fromXML(name, attrs, content, ttFont)[source]

fontTools.ttLib.tables.otBase 

class fontTools.ttLib.tables.otBase.OverflowErrorRecord(overflowTuple)[source]: Bases: object

exception fontTools.ttLib.tables.otBase.OTLOffsetOverflowError(overflowErrorRecord)[source]: Bases: Exception

class fontTools.ttLib.tables.otBase.RepackerState(value)[source]

Bases: IntEnum

An enumeration.

PURE_FT = 1

HB_FT = 2

FT_FALLBACK = 3

class fontTools.ttLib.tables.otBase.BaseTTXConverter(tag=None)[source]

Bases: DefaultTable

Generic base class for TTX table converters. It functions as an adapter between the TTX (ttLib actually) table model and the model we use for OpenType tables, which is necessarily subtly different.

decompile(data, font)[source]: Create an object from the binary data. Called automatically on access.

compile(font)[source]: Compiles the table into binary. Called automatically on save.

tryPackingHarfbuzz(writer, hb_first_error_logged)[source]

tryPackingFontTools(writer)[source]

tryResolveOverflow(font, e, lastOverflowRecord)[source]

toXML(writer, font)[source]

fromXML(name, attrs, content, font)[source]

ensureDecompiled(recurse=True)[source]

class fontTools.ttLib.tables.otBase.OTTableReader(data, localState=None, offset=0, tableTag=None)[source]

Bases: object

Helper class to retrieve data from an OpenType table.

data

offset

pos

localState

tableTag

advance(count)[source]

seek(pos)[source]

copy()[source]

getSubReader(offset)[source]

readValue(typecode, staticSize)[source]

readArray(typecode, staticSize, count)[source]

readInt8()[source]

readInt8Array(count)[source]

readShort()[source]

readShortArray(count)[source]

readLong()[source]

readLongArray(count)[source]

readUInt8()[source]

readUInt8Array(count)[source]

readUShort()[source]

readUShortArray(count)[source]

readULong()[source]

readULongArray(count)[source]

readUInt24()[source]

readUInt24Array(count)[source]

readTag()[source]

readData(count)[source]

class fontTools.ttLib.tables.otBase.OffsetToWriter(subWriter, offsetSize)[source]: Bases: object

class fontTools.ttLib.tables.otBase.OTTableWriter(localState=None, tableTag=None)[source]

Bases: object

Helper class to gather and assemble data for OpenType tables.

getDataLength()[source]: Return the length of this table in bytes, without subtables.

getData()[source]: Assemble the data for this writer/table, without subtables.

getDataForHarfbuzz()[source]: Assemble the data for this writer/table with all offset field set to 0

getAllDataUsingHarfbuzz(tableTag)[source]: The Whole table is represented as a Graph. Assemble graph data and call Harfbuzz repacker to pack the table. Harfbuzz repacker is faster and retain as much sub-table sharing as possible, see also: https://github.com/harfbuzz/harfbuzz/blob/main/docs/repacker.md The input format for hb.repack() method is explained here: https://github.com/harfbuzz/uharfbuzz/blob/main/src/uharfbuzz/_harfbuzz.pyx#L1149

getAllData(remove_duplicate=True)[source]: Assemble all data, including all subtables.

getSubWriter()[source]

writeValue(typecode, value)[source]

writeArray(typecode, values)[source]

writeInt8(value)[source]

writeInt8Array(values)[source]

writeShort(value)[source]

writeShortArray(values)[source]

writeLong(value)[source]

writeLongArray(values)[source]

writeUInt8(value)[source]

writeUInt8Array(values)[source]

writeUShort(value)[source]

writeUShortArray(values)[source]

writeULong(value)[source]

writeULongArray(values)[source]

writeUInt24(value)[source]

writeUInt24Array(values)[source]

writeTag(tag)[source]

writeSubTable(subWriter, offsetSize)[source]

writeCountReference(table, name, size=2, value=None)[source]

writeStruct(format, values)[source]

writeData(data)[source]

getOverflowErrorRecord(item)[source]

class fontTools.ttLib.tables.otBase.CountReference(table, name, size=None, value=None)[source]

Bases: object

A reference to a Count value, not a count of references.

setValue(value)[source]

getValue()[source]

getCountData()[source]

fontTools.ttLib.tables.otBase.packUInt8(value)[source]

fontTools.ttLib.tables.otBase.packUShort(value)[source]

fontTools.ttLib.tables.otBase.packULong(value)[source]

fontTools.ttLib.tables.otBase.packUInt24(value)[source]

class fontTools.ttLib.tables.otBase.BaseTable[source]

Bases: object

Generic base class for all OpenType (sub)tables.

ensureDecompiled(recurse=False)[source]

classmethod getRecordSize(reader)[source]

getConverters()[source]

getConverterByName(name)[source]

populateDefaults(propagator=None)[source]

decompile(reader, font)[source]

compile(writer, font)[source]

readFormat(reader)[source]

writeFormat(writer)[source]

toXML(xmlWriter, font, attrs=None, name=None)[source]

toXML2(xmlWriter, font)[source]

fromXML(name, attrs, content, font)[source]

class SubTableEntry(name: str, value: BaseTable, index: int | None = None)[source]

Bases: NamedTuple

See BaseTable.iterSubTables()

name: str: Alias for field number 0

value: BaseTable: Alias for field number 1

index: int | None: Alias for field number 2

iterSubTables() → Iterator[SubTableEntry][source]

Yield (name, value, index) namedtuples for all subtables of current table.

A sub-table is an instance of BaseTable (or subclass thereof) that is a child of self, the current parent table. The tuples also contain the attribute name (str) of the of parent table to get a subtable, and optionally, for lists of subtables (i.e. attributes associated with a converter that has a ‘repeat’), an index into the list containing the given subtable value. This method can be useful to traverse trees of otTables.

getVariableAttrs()[source]

class fontTools.ttLib.tables.otBase.FormatSwitchingBaseTable[source]

Bases: BaseTable

Minor specialization of BaseTable, for tables that have multiple formats, eg. CoverageFormat1 vs. CoverageFormat2.

classmethod getRecordSize(reader)[source]

getConverters()[source]

getConverterByName(name)[source]

readFormat(reader)[source]

writeFormat(writer)[source]

toXML(xmlWriter, font, attrs=None, name=None)[source]

getVariableAttrs()[source]

class fontTools.ttLib.tables.otBase.UInt8FormatSwitchingBaseTable[source]

Bases: FormatSwitchingBaseTable

readFormat(reader)[source]

writeFormat(writer)[source]

fontTools.ttLib.tables.otBase.getFormatSwitchingBaseTableClass(formatType)[source]

fontTools.ttLib.tables.otBase.getVariableAttrs(cls: BaseTable, fmt: int | None = None) → Tuple[str][source]

Return sequence of variable table field names (can be empty).

Attributes are deemed “variable” when their otData.py’s description contain ‘VarIndexBase + {offset}’, e.g. COLRv1 PaintVar* tables.

class fontTools.ttLib.tables.otBase.ValueRecordFactory(valueFormat)[source]

Bases: object

Given a format code, this object convert ValueRecords.

readValueRecord(reader, font)[source]

writeValueRecord(writer, font, valueRecord)[source]

class fontTools.ttLib.tables.otBase.ValueRecord(valueFormat=None, src=None)[source]

Bases: object

getFormat()[source]

getEffectiveFormat()[source]

toXML(xmlWriter, font, valueName, attrs=None)[source]

fromXML(name, attrs, content, font)[source]

prune_hints()

Base table classes and API

Overview:

Contributing your own table convertors

fontTools.ttLib.tables.DefaultTable

fontTools.ttLib.tables.asciiTable

fontTools.ttLib.tables.otBase

Contributing your own table convertors 

fontTools.ttLib.tables.DefaultTable 

fontTools.ttLib.tables.asciiTable 

fontTools.ttLib.tables.otBase 