# 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)

  Bases: `object`

  dependencies = []
  decompile(data, ttFont)
  compile(ttFont)
  toXML(writer, ttFont, **kwargs)
  fromXML(name, attrs, content, ttFont)
  merge(m, tables)

## fontTools.ttLib.tables.asciiTable

class fontTools.ttLib.tables.asciiTable.asciiTable(tag=None)

  Bases: `DefaultTable`

  toXML(writer, ttFont)
  fromXML(name, attrs, content, ttFont)

## fontTools.ttLib.tables.otBase

class fontTools.ttLib.tables.otBase.OverflowErrorRecord(overflowTuple)

  Bases: `object`

exception fontTools.ttLib.tables.otBase.OTLOffsetOverflowError(overflowErrorRecord)

  Bases: `Exception`

class fontTools.ttLib.tables.otBase.RepackerState(*values)

  Bases: `IntEnum`

  PURE_FT = 1
  HB_FT = 2
  FT_FALLBACK = 3

class fontTools.ttLib.tables.otBase.BaseTTXConverter(tag=None)

  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)

    Create an object from the binary data. Called automatically on access.

  compile(font)

    Compiles the table into binary. Called automatically on save.

  tryPackingHarfbuzz(writer, hb_first_error_logged)
  tryPackingFontTools(writer)
  tryResolveOverflow(font, e, lastOverflowRecord)
  toXML(writer, font)
  fromXML(name, attrs, content, font)
  ensureDecompiled(recurse=True)

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

  Bases: `object`

  Helper class to retrieve data from an OpenType table.

  data
  offset
  pos
  localState
  tableTag
  advance(count)
  seek(pos)
  copy()
  getSubReader(offset)
  readValue(typecode, staticSize)
  readArray(typecode, staticSize, count)
  readInt8()
  readInt8Array(count)
  readShort()
  readShortArray(count)
  readLong()
  readLongArray(count)
  readUInt8()
  readUInt8Array(count)
  readUShort()
  readUShortArray(count)
  readULong()
  readULongArray(count)
  readUInt24()
  readUInt24Array(count)
  readTag()
  readData(count)

class fontTools.ttLib.tables.otBase.OffsetToWriter(subWriter, offsetSize)

  Bases: `object`

class fontTools.ttLib.tables.otBase.OTTableWriter(localState=None, tableTag=None)

  Bases: `object`

  Helper class to gather and assemble data for OpenType tables.

  getDataLength()

    Return the length of this table in bytes, without subtables.

  getData()

    Assemble the data for this writer/table, without subtables.

  getDataForHarfbuzz()

    Assemble the data for this writer/table with all offset field set to 0

  getAllDataUsingHarfbuzz(tableTag)

    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)

    Assemble all data, including all subtables.

  getSubWriter()
  writeValue(typecode, value)
  writeArray(typecode, values)
  writeInt8(value)
  writeInt8Array(values)
  writeShort(value)
  writeShortArray(values)
  writeLong(value)
  writeLongArray(values)
  writeUInt8(value)
  writeUInt8Array(values)
  writeUShort(value)
  writeUShortArray(values)
  writeULong(value)
  writeULongArray(values)
  writeUInt24(value)
  writeUInt24Array(values)
  writeTag(tag)
  writeSubTable(subWriter, offsetSize)
  writeCountReference(table, name, size=2, value=None)
  writeStruct(format, values)
  writeData(data)
  getOverflowErrorRecord(item)

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

  Bases: `object`

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

  setValue(value)
  getValue()
  getCountData()

fontTools.ttLib.tables.otBase.packUInt8(value)

fontTools.ttLib.tables.otBase.packUShort(value)

fontTools.ttLib.tables.otBase.packULong(value)

fontTools.ttLib.tables.otBase.packUInt24(value)

class fontTools.ttLib.tables.otBase.BaseTable

  Bases: `object`

  Generic base class for all OpenType (sub)tables.

  ensureDecompiled(recurse=False)
  classmethod getRecordSize(reader)
  getConverters()
  getConverterByName(name)
  populateDefaults(propagator=None)
  decompile(reader, font)
  compile(writer, font)
  readFormat(reader)
  writeFormat(writer)
  toXML(xmlWriter, font, attrs=None, name=None)
  toXML2(xmlWriter, font)
  fromXML(name, attrs, content, font)
  class SubTableEntry(name: str, value: BaseTable, index: int | None = None)

    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]

    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()

class fontTools.ttLib.tables.otBase.FormatSwitchingBaseTable

  Bases: `BaseTable`

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

  classmethod getRecordSize(reader)
  getConverters()
  getConverterByName(name)
  readFormat(reader)
  writeFormat(writer)
  toXML(xmlWriter, font, attrs=None, name=None)
  getVariableAttrs()

class fontTools.ttLib.tables.otBase.UInt8FormatSwitchingBaseTable

  Bases: `FormatSwitchingBaseTable`

  readFormat(reader)
  writeFormat(writer)

fontTools.ttLib.tables.otBase.getFormatSwitchingBaseTableClass(formatType)

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

  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)

  Bases: `object`

  Given a format code, this object convert ValueRecords.

  readValueRecord(reader, font)
  writeValueRecord(writer, font, valueRecord)

class fontTools.ttLib.tables.otBase.ValueRecord(valueFormat=None, src=None)

  Bases: `object`

  getFormat()
  getEffectiveFormat()
  toXML(xmlWriter, font, valueName, attrs=None)
  fromXML(name, attrs, content, font)
  prune_hints()