0
# FontTools
1

2
FontTools is a comprehensive Python library for manipulating fonts, providing tools to work with TrueType, OpenType, AFM and Type 1 fonts. The library includes the TTX tool that can convert fonts to and from XML text format, enabling font analysis and modification. It supports font file parsing, glyph manipulation, font subsetting, and various font format conversions.
3

4
## Package Information
5

6
- **Package Name**: fonttools
7
- **Language**: Python  
8
- **Installation**: `pip install fonttools`
9

10
## Core Imports
11

12
```python
13
import fontTools
14
```
15

16
Common for font manipulation:
17

18
```python
19
from fontTools.ttLib import TTFont
20
```
21

22
For font building from scratch:
23

24
```python
25
from fontTools.fontBuilder import FontBuilder
26
```
27

28
## Basic Usage
29

30
```python
31
from fontTools.ttLib import TTFont
32

33
# Load a font file
34
font = TTFont("font.ttf")
35

36
# Access font tables
37
head_table = font['head']
38
print(f"Font revision: {head_table.fontRevision}")
39

40
# Get glyph information
41
glyph_set = font.getGlyphSet()
42
glyph_names = font.getGlyphOrder()
43
print(f"Number of glyphs: {len(glyph_names)}")
44

45
# Get character mapping
46
cmap = font.getBestCmap()
47
print(f"Unicode mappings: {len(cmap)} characters")
48

49
# Save font
50
font.save("modified_font.ttf")
51
font.close()
52
```
53

54
## Architecture
55

56
FontTools uses a modular architecture organized around OpenType table manipulation:
57

58
- **TTFont**: Central font object providing table-based access to font data
59
- **Tables**: Individual OpenType table implementations (head, glyf, cmap, etc.)
60
- **Pens**: Drawing abstraction for glyph construction and manipulation
61
- **Builders**: High-level interfaces for creating fonts from scratch
62
- **Processors**: Tools for font optimization, subsetting, and merging
63

64
This design enables both low-level font manipulation and high-level font processing workflows, making FontTools the foundation for font-related projects in the Python ecosystem.
65

66
## Capabilities
67

68
### Core Font Operations
69

70
Essential font loading, manipulation, and saving functionality using the TTFont class. Provides table-based access to all font data with lazy loading and extensive format support.
71

72
```python { .api }
73
class TTFont:
74
    def __init__(self, file=None, sfntVersion="\\000\\001\\000\\000", fontNumber=0, lazy=None, recalcBBoxes=True, recalcTimestamp=True, allowVID=False, ignoreDecompileErrors=False, transform=None, cfg=None): ...
75
    def save(self, file, reorderTables=True): ...
76
    def saveXML(self, file): ...
77
    def importXML(self, file): ...
78
    def getGlyphOrder(self): ...
79
    def setGlyphOrder(self, glyphOrder): ...
80
    def getGlyphSet(self): ...
81
    def getBestCmap(self): ...
82
    def close(self): ...
83
```
84

85
[Core Font Operations](./core-font-operations.md)
86

87
### Font Building
88

89
Build fonts from scratch using a builder pattern, supporting both TrueType and CFF/PostScript font creation with comprehensive table setup methods.
90

91
```python { .api }
92
class FontBuilder:
93
    def __init__(self, unitsPerEm=None, font=None, isTTF=True): ...
94
    def setupGlyphOrder(self, glyphOrder): ...
95
    def setupCharacterMap(self, cmap): ...
96
    def setupGlyf(self, glyphs): ...
97
    def setupCFF(self, psName, charStrings, charStringsType=2): ...
98
    def setupHorizontalMetrics(self, metrics): ...
99
    def setupNameTable(self, nameStrings, mac=True): ...
100
```
101

102
[Font Building](./font-building.md)
103

104
### Font Processing
105

106
Font optimization, subsetting, and merging tools for reducing file sizes and combining multiple fonts into collections.
107

108
```python { .api }
109
class Subsetter:
110
    def __init__(self, options=None): ...
111
    def subset(self, font): ...
112

113
class Merger:
114
    def __init__(self, options=None): ...
115
    def merge(self, fontfiles): ...
116
```
117

118
[Font Processing](./font-processing.md)
119

120
### Variable Fonts
121

122
Build and manipulate variable fonts using design space documents, supporting multi-axis font variations and instance generation.
123

124
```python { .api }
125
def build(designspace, master_finder=lambda s: s, exclude=[], optimize=True, **kwargs): ...
126
def load_designspace(designspace): ...
127
def load_masters(designspace, master_finder): ...
128

129
class DesignSpaceDocument:
130
    def read(self, path): ...
131
    def write(self, path): ...
132
    def addAxisDescriptor(self, descriptor): ...
133
```
134

135
[Variable Fonts](./variable-fonts.md)
136

137
### Drawing and Pens
138

139
Standardized drawing interface for glyph construction, manipulation, and rendering with specialized pen implementations for different use cases.
140

141
```python { .api }
142
class AbstractPen:
143
    def moveTo(self, pt): ...
144
    def lineTo(self, pt): ...
145
    def curveTo(self, *points): ...
146
    def qCurveTo(self, *points): ...
147
    def closePath(self): ...
148
    def endPath(self): ...
149

150
class TTGlyphPen(BasePen): ...
151
class BoundsPen(BasePen): ...
152
class TransformPen(BasePen): ...
153
```
154

155
[Drawing and Pens](./drawing-pens.md)
156

157
### Utilities and Tools
158

159
Miscellaneous utilities for text processing, geometric transformations, XML handling, and various font-related calculations.
160

161
```python { .api }
162
class Transform:
163
    def __init__(self, a=1, b=0, c=0, d=1, e=0, f=0): ...
164
    def transform(self, x, y): ...
165
    def scale(self, x, y=None): ...
166
    def rotate(self, angle): ...
167
    def translate(self, x, y): ...
168

169
def calcBounds(array): ...
170
def roundFunc(value, func=round): ...
171
```
172

173
[Utilities and Tools](./utilities-tools.md)
174

175
## Command-Line Interface
176

177
FontTools provides a unified command-line interface through the `fonttools` command:
178

179
```bash
180
# Convert font to TTX XML format
181
fonttools ttx font.ttf
182

183
# Subset a font to specific characters
184
fonttools subset font.ttf --text="Hello World"
185

186
# Merge multiple fonts
187
fonttools merge font1.ttf font2.ttf
188

189
# Build variable font from design space
190
fonttools varLib design.designspace
191
```
192

193
## Error Handling
194

195
FontTools defines specific exception hierarchies for different operations:
196

197
- `TTLibError`: Base exception for font loading/saving errors
198
- `SubsettingError`: Font subsetting operation failures  
199
- `FeatureLibError`: OpenType feature compilation errors
200
- `PenError`: Drawing operation errors
201
- `DesignSpaceDocumentError`: Design space processing errors
202

203
## Types
204

205
```python { .api }
206
# Core types used throughout FontTools
207
GlyphOrder = List[str]
208
CharacterMap = Dict[int, str]  # Unicode codepoint to glyph name
209
Metrics = Dict[str, Tuple[int, int]]  # glyph name to (advance width, left side bearing)
210
Point = Tuple[float, float]
211
BoundingBox = Tuple[float, float, float, float]  # xMin, yMin, xMax, yMax
212
```