feaLib: Read and write OpenType feature files

Overview

fontTools’ feaLib allows for the creation and parsing of Adobe Font Development Kit for OpenType feature (.fea) files. The syntax of these files is described here.

.fea files are primarily used for writing human-readable definitions for the OpenType features stored in a font’s GSUB and GPOS tables.

Supporting modules

feaLib contains modules for parsing and inspecting .fea files as well as utilities for converting .fea rules into GSUB and GPOS tables and inserting them into fonts.

• parser: Lexing and parsing OpenType feature files
• ast: Interrogate and generate OpenType feature files

The fontTools.feaLib.parser.Parser class can be used to parse files into an abstract syntax tree, and from there the fontTools.feaLib.builder.Builder class can add features to an existing font file. You can inspect the parsed syntax tree, walk the tree and do clever things with it, and also generate your own feature files programmatically, by using the classes in the fontTools.feaLib.ast module.

fontTools.feaLib.builder

fontTools.feaLib.builder.addOpenTypeFeatures(font, featurefile, tables=None, debug=False)

Add features from a file to a font. Note that this replaces any features currently present.

Parameters:

• font (feaLib.ttLib.TTFont) – The font object.

• featurefile – Either a path or file object (in which case we parse it into an AST), or a pre-parsed AST instance.

• tables – If passed, restrict the set of affected tables to those in the list.

• debug – Whether to add source debugging information to the font in the Debg table

fontTools.feaLib.builder.addOpenTypeFeaturesFromString(font, features, filename=None, tables=None, debug=False)

Add features from a string to a font. Note that this replaces any features currently present.

Parameters:

• font (feaLib.ttLib.TTFont) – The font object.

• features – A string containing feature code.

• filename – The directory containing filename is used as the root of relative include() paths; if None is provided, the current directory is assumed.

• tables – If passed, restrict the set of affected tables to those in the list.

• debug – Whether to add source debugging information to the font in the Debg table

class fontTools.feaLib.builder.Builder(font, featurefile)

Bases: object

supportedTables = frozenset({'BASE', 'GDEF', 'GPOS', 'GSUB', 'OS/2', 'STAT', 'head', 'hhea', 'name', 'vhea'})

build(tables=None, debug=False)

get_chained_lookup_(location, builder_class)

add_lookup_to_feature_(lookup, feature_name)

get_lookup_(location, builder_class, mapping=None)

build_feature_aalt_()

build_head()

build_hhea()

build_vhea()

get_user_name_id(table)

buildFeatureParams(tag)

build_name()

build_OS_2()

setElidedFallbackName(value, location)

addDesignAxis(designAxis, location)

addAxisValueRecord(axisValueRecord, location)

build_STAT()

build_codepages_(pages)

buildBASE()

buildBASECoord(c)

buildBASEAxis(axis)

buildGDEF()

buildGDEFGlyphClassDef_()

buildGDEFMarkAttachClassDef_()

buildGDEFMarkGlyphSetsDef_()

buildDebg()

buildLookups_(tag)

makeTable(tag)

makeFeatureVariations(table, table_tag)

any_feature_variations(feature_tag, table_tag)

get_lookup_name_(lookup)

add_language_system(location, script, language)

get_default_language_systems_()

start_feature(location, name, use_extension=False)

end_feature()

start_lookup_block(location, name, use_extension=False)

end_lookup_block()

add_lookup_call(lookup_name)

set_font_revision(location, revision)

set_language(location, language, include_default, required)

getMarkAttachClass_(location, glyphs)

getMarkFilterSet_(location, glyphs)

set_lookup_flag(location, value, markAttach, markFilter)

set_script(location, script)

find_lookup_builders_(lookups)

Helper for building chain contextual substitutions

Given a list of lookup names, finds the LookupBuilder for each name. If an input name is None, it gets mapped to a None LookupBuilder.

add_attach_points(location, glyphs, contourPoints)

add_feature_reference(location, featureName)

add_featureName(tag)

add_cv_parameter(tag)

add_to_cv_num_named_params(tag)

Adds new items to self.cv_num_named_params_ or increments the count of existing items.

add_cv_character(character, tag)

set_base_axis(bases, scripts, vertical, minmax=[])

set_size_parameters(location, DesignSize, SubfamilyID, RangeStart, RangeEnd)

add_any_subst_(location, mapping)

add_single_subst(location, prefix, suffix, mapping, forceChain)

add_multiple_subst(location, prefix, glyph, suffix, replacements, forceChain=False)

add_alternate_subst(location, prefix, glyph, suffix, replacement)

add_ligature_subst(location, prefix, glyphs, suffix, replacement, forceChain)

add_chain_context_subst(location, prefix, glyphs, suffix, lookups)

add_single_subst_chained_(location, prefix, suffix, mapping)

add_multi_subst_chained_(location, prefix, glyph, suffix, replacements)

add_ligature_subst_chained_(location, prefix, glyphs, suffix, replacement)

add_reverse_chain_single_subst(location, old_prefix, old_suffix, mapping)

add_single_pos(location, prefix, suffix, pos, forceChain)

add_class_pair_pos(location, glyphclass1, value1, glyphclass2, value2)

add_specific_pair_pos(location, glyph1, value1, glyph2, value2)

add_cursive_pos(location, glyphclass, entryAnchor, exitAnchor)

add_mark_base_pos(location, bases, marks)

add_mark_lig_pos(location, ligatures, components)

add_mark_mark_pos(location, baseMarks, marks)

add_chain_context_pos(location, prefix, glyphs, suffix, lookups)

add_single_pos_chained_(location, prefix, suffix, pos)

add_marks_(location, lookupBuilder, marks)

Helper for add_mark_{base,liga,mark}_pos.

add_subtable_break(location)

setGlyphClass_(location, glyph, glyphClass)

add_glyphClassDef(location, baseGlyphs, ligatureGlyphs, markGlyphs, componentGlyphs)

add_ligatureCaretByIndex_(location, glyphs, carets)

makeLigCaret(location, caret)

add_ligatureCaretByPos_(location, glyphs, carets)

add_name_record(location, nameID, platformID, platEncID, langID, string)

add_os2_field(key, value)

add_hhea_field(key, value)

add_vhea_field(key, value)

add_conditionset(location, key, value)

makeVariablePos(location, varscalar: VariableScalar) → tuple[int, int | None]

Make a pos statement from a VariableScalar, returning the default value, and optionally the variation index if the scalar genuinely requires variation too.

makeAnchorPos(varscalar, deviceTable, location)

makeOpenTypeAnchor(location, anchor)

ast.Anchor –> otTables.Anchor

makeOpenTypeValueRecord(location, v, pairPosContext)

ast.ValueRecord –> otBase.ValueRecord

fontTools.feaLib.lookupDebugInfo

class fontTools.feaLib.lookupDebugInfo.LookupDebugInfo(location: str, name: str, feature: list)

Bases: NamedTuple

Information about where a lookup came from, to be embedded in a font

location: str

Alias for field number 0

name: str

Alias for field number 1

feature: list

Alias for field number 2

fontTools.feaLib.error

exception fontTools.feaLib.error.FeatureLibError(message, location=None)

Bases: Exception

exception fontTools.feaLib.error.IncludedFeaNotFound(message, location=None)

Bases: FeatureLibError