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
