1|CI Build Status| |Coverage Status| |PyPI| |Gitter Chat|
2
3What is this?
4~~~~~~~~~~~~~
5
6| fontTools is a library for manipulating fonts, written in Python. The
7 project includes the TTX tool, that can convert TrueType and OpenType
8 fonts to and from an XML text format, which is also called TTX. It
9 supports TrueType, OpenType, AFM and to an extent Type 1 and some
10 Mac-specific formats. The project has an `MIT open-source
11 licence <LICENSE>`__.
12| Among other things this means you can use it free of charge.
13
14`User documentation <https://fonttools.readthedocs.io/en/latest/>`_ and
15`developer documentation <https://fonttools.readthedocs.io/en/latest/developer.html>`_
16are available at `Read the Docs <https://fonttools.readthedocs.io/>`_.
17
18Installation
19~~~~~~~~~~~~
20
21FontTools requires `Python <http://www.python.org/download/>`__ 3.7
22or later.
23
24The package is listed in the Python Package Index (PyPI), so you can
25install it with `pip <https://pip.pypa.io>`__:
26
27.. code:: sh
28
29 pip install fonttools
30
31If you would like to contribute to its development, you can clone the
32repository from GitHub, install the package in 'editable' mode and
33modify the source code in place. We recommend creating a virtual
34environment, using `virtualenv <https://virtualenv.pypa.io>`__ or
35Python 3 `venv <https://docs.python.org/3/library/venv.html>`__ module.
36
37.. code:: sh
38
39 # download the source code to 'fonttools' folder
40 git clone https://github.com/fonttools/fonttools.git
41 cd fonttools
42
43 # create new virtual environment called e.g. 'fonttools-venv', or anything you like
44 python -m virtualenv fonttools-venv
45
46 # source the `activate` shell script to enter the environment (Un*x); to exit, just type `deactivate`
47 . fonttools-venv/bin/activate
48
49 # to activate the virtual environment in Windows `cmd.exe`, do
50 fonttools-venv\Scripts\activate.bat
51
52 # install in 'editable' mode
53 pip install -e .
54
55Optional Requirements
56---------------------
57
58The ``fontTools`` package currently has no (required) external dependencies
59besides the modules included in the Python Standard Library.
60However, a few extra dependencies are required by some of its modules, which
61are needed to unlock optional features.
62The ``fonttools`` PyPI distribution also supports so-called "extras", i.e. a
63set of keywords that describe a group of additional dependencies, which can be
64used when installing via pip, or when specifying a requirement.
65For example:
66
67.. code:: sh
68
69 pip install fonttools[ufo,lxml,woff,unicode]
70
71This command will install fonttools, as well as the optional dependencies that
72are required to unlock the extra features named "ufo", etc.
73
74- ``Lib/fontTools/misc/etree.py``
75
76 The module exports a ElementTree-like API for reading/writing XML files, and
77 allows to use as the backend either the built-in ``xml.etree`` module or
78 `lxml <https://lxml.de>`__. The latter is preferred whenever present,
79 as it is generally faster and more secure.
80
81 *Extra:* ``lxml``
82
83- ``Lib/fontTools/ufoLib``
84
85 Package for reading and writing UFO source files; it requires:
86
87 * `fs <https://pypi.org/pypi/fs>`__: (aka ``pyfilesystem2``) filesystem
88 abstraction layer.
89
90 * `enum34 <https://pypi.org/pypi/enum34>`__: backport for the built-in ``enum``
91 module (only required on Python < 3.4).
92
93 *Extra:* ``ufo``
94
95- ``Lib/fontTools/ttLib/woff2.py``
96
97 Module to compress/decompress WOFF 2.0 web fonts; it requires:
98
99 * `brotli <https://pypi.python.org/pypi/Brotli>`__: Python bindings of
100 the Brotli compression library.
101
102 *Extra:* ``woff``
103
104- ``Lib/fontTools/ttLib/sfnt.py``
105
106 To better compress WOFF 1.0 web fonts, the following module can be used
107 instead of the built-in ``zlib`` library:
108
109 * `zopfli <https://pypi.python.org/pypi/zopfli>`__: Python bindings of
110 the Zopfli compression library.
111
112 *Extra:* ``woff``
113
114- ``Lib/fontTools/unicode.py``
115
116 To display the Unicode character names when dumping the ``cmap`` table
117 with ``ttx`` we use the ``unicodedata`` module in the Standard Library.
118 The version included in there varies between different Python versions.
119 To use the latest available data, you can install:
120
121 * `unicodedata2 <https://pypi.python.org/pypi/unicodedata2>`__:
122 ``unicodedata`` backport for Python 3.x updated to the latest Unicode
123 version 14.0. Note this is not necessary if you use Python 3.11
124 as the latter already comes with an up-to-date ``unicodedata``.
125
126 *Extra:* ``unicode``
127
128- ``Lib/fontTools/varLib/interpolatable.py``
129
130 Module for finding wrong contour/component order between different masters.
131 It requires one of the following packages in order to solve the so-called
132 "minimum weight perfect matching problem in bipartite graphs", or
133 the Assignment problem:
134
135 * `scipy <https://pypi.python.org/pypi/scipy>`__: the Scientific Library
136 for Python, which internally uses `NumPy <https://pypi.python.org/pypi/numpy>`__
137 arrays and hence is very fast;
138 * `munkres <https://pypi.python.org/pypi/munkres>`__: a pure-Python
139 module that implements the Hungarian or Kuhn-Munkres algorithm.
140
141 *Extra:* ``interpolatable``
142
143- ``Lib/fontTools/varLib/plot.py``
144
145 Module for visualizing DesignSpaceDocument and resulting VariationModel.
146
147 * `matplotlib <https://pypi.org/pypi/matplotlib>`__: 2D plotting library.
148
149 *Extra:* ``plot``
150
151- ``Lib/fontTools/misc/symfont.py``
152
153 Advanced module for symbolic font statistics analysis; it requires:
154
155 * `sympy <https://pypi.python.org/pypi/sympy>`__: the Python library for
156 symbolic mathematics.
157
158 *Extra:* ``symfont``
159
160- ``Lib/fontTools/t1Lib.py``
161
162 To get the file creator and type of Macintosh PostScript Type 1 fonts
163 on Python 3 you need to install the following module, as the old ``MacOS``
164 module is no longer included in Mac Python:
165
166 * `xattr <https://pypi.python.org/pypi/xattr>`__: Python wrapper for
167 extended filesystem attributes (macOS platform only).
168
169 *Extra:* ``type1``
170
171- ``Lib/fontTools/ttLib/removeOverlaps.py``
172
173 Simplify TrueType glyphs by merging overlapping contours and components.
174
175 * `skia-pathops <https://pypi.python.org/pypy/skia-pathops>`__: Python
176 bindings for the Skia library's PathOps module, performing boolean
177 operations on paths (union, intersection, etc.).
178
179 *Extra:* ``pathops``
180
181- ``Lib/fontTools/pens/cocoaPen.py`` and ``Lib/fontTools/pens/quartzPen.py``
182
183 Pens for drawing glyphs with Cocoa ``NSBezierPath`` or ``CGPath`` require:
184
185 * `PyObjC <https://pypi.python.org/pypi/pyobjc>`__: the bridge between
186 Python and the Objective-C runtime (macOS platform only).
187
188- ``Lib/fontTools/pens/qtPen.py``
189
190 Pen for drawing glyphs with Qt's ``QPainterPath``, requires:
191
192 * `PyQt5 <https://pypi.python.org/pypi/PyQt5>`__: Python bindings for
193 the Qt cross platform UI and application toolkit.
194
195- ``Lib/fontTools/pens/reportLabPen.py``
196
197 Pen to drawing glyphs as PNG images, requires:
198
199 * `reportlab <https://pypi.python.org/pypi/reportlab>`__: Python toolkit
200 for generating PDFs and graphics.
201
202- ``Lib/fontTools/pens/freetypePen.py``
203
204 Pen to drawing glyphs with FreeType as raster images, requires:
205
206 * `freetype-py <https://pypi.python.org/pypi/freetype-py>`__: Python binding
207 for the FreeType library.
208
209How to make a new release
210~~~~~~~~~~~~~~~~~~~~~~~~~
211
2121) Update ``NEWS.rst`` with all the changes since the last release. Write a
213 changelog entry for each PR, with one or two short sentences summarizing it,
214 as well as links to the PR and relevant issues addressed by the PR.
2152) Use semantic versioning to decide whether the new release will be a 'major',
216 'minor' or 'patch' release. It's usually one of the latter two, depending on
217 whether new backward compatible APIs were added, or simply some bugs were fixed.
2183) Run ``python setup.py release`` command from the tip of the ``main`` branch.
219 By default this bumps the third or 'patch' digit only, unless you pass ``--major``
220 or ``--minor`` to bump respectively the first or second digit.
221 This bumps the package version string, extracts the changes since the latest
222 version from ``NEWS.rst``, and uses that text to create an annotated git tag
223 (or a signed git tag if you pass the ``--sign`` option and your git and Github
224 account are configured for `signing commits <https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits>`__
225 using a GPG key).
226 It also commits an additional version bump which opens the main branch for
227 the subsequent developmental cycle
2284) Push both the tag and commit to the upstream repository, by running the command
229 ``git push --follow-tags``.
2305) Let the CI build the wheel and source distribution packages and verify both
231 get uploaded to the Python Package Index (PyPI).
2326) [Optional] Go to fonttools `Github Releases <https://github.com/fonttools/fonttools/releases>`__
233 page and create a new release, copy-pasting the content of the git tag
234 message. This way, the release notes are nicely formatted as markdown, and
235 users watching the repo will get an email notification. One day we shall
236 automate that too.
237
238
239Acknowledgements
240~~~~~~~~~~~~~~~~
241
242In alphabetical order:
243
244aschmitz, Olivier Berten, Samyak Bhuta, Erik van Blokland, Petr van Blokland,
245Jelle Bosma, Sascha Brawer, Tom Byrer, Antonio Cavedoni, Frédéric
246Coiffier, Vincent Connare, David Corbett, Simon Cozens, Dave Crossland,
247Simon Daniels, Peter Dekkers, Behdad Esfahbod, Behnam Esfahbod, Hannes
248Famira, Sam Fishman, Matt Fontaine, Takaaki Fuji, Yannis Haralambous, Greg
249Hitchcock, Jeremie Hornus, Khaled Hosny, John Hudson, Denis Moyogo Jacquerye,
250Jack Jansen, Tom Kacvinsky, Jens Kutilek, Antoine Leca, Werner Lemberg, Tal
251Leming, Peter Lofting, Cosimo Lupo, Olli Meier, Masaya Nakamura, Dave Opstad,
252Laurence Penney, Roozbeh Pournader, Garret Rieger, Read Roberts, Guido
253van Rossum, Just van Rossum, Andreas Seidel, Georg Seifert, Chris
254Simpkins, Miguel Sousa, Adam Twardoch, Adrien Tétar, Vitaly Volkov,
255Paul Wise.
256
257Copyrights
258~~~~~~~~~~
259
260| Copyright (c) 1999-2004 Just van Rossum, LettError
261 (just@letterror.com)
262| See `LICENSE <LICENSE>`__ for the full license.
263
264Copyright (c) 2000 BeOpen.com. All Rights Reserved.
265
266Copyright (c) 1995-2001 Corporation for National Research Initiatives.
267All Rights Reserved.
268
269Copyright (c) 1991-1995 Stichting Mathematisch Centrum, Amsterdam. All
270Rights Reserved.
271
272Have fun!
273
274.. |CI Build Status| image:: https://github.com/fonttools/fonttools/workflows/Test/badge.svg
275 :target: https://github.com/fonttools/fonttools/actions?query=workflow%3ATest
276.. |Coverage Status| image:: https://codecov.io/gh/fonttools/fonttools/branch/master/graph/badge.svg
277 :target: https://codecov.io/gh/fonttools/fonttools
278.. |PyPI| image:: https://img.shields.io/pypi/v/fonttools.svg
279 :target: https://pypi.org/project/FontTools
280.. |Gitter Chat| image:: https://badges.gitter.im/fonttools-dev/Lobby.svg
281 :alt: Join the chat at https://gitter.im/fonttools-dev/Lobby
282 :target: https://gitter.im/fonttools-dev/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
283