ttfquery Package

ttfquery Package

Fonttools package for querying and sorting system fonts

_scriptregistry Module

Provides primitive font registry lookup/location for scripts

The singleton “registry” object (an instance of ttfquery.ttffiles.Registry is the only member of note). This registry with be created in a file in the user’s $HOME directory .font.cache if the $HOME environment variable is defined. Otherwise will be created in the ttfquery source code directory (which is obviously not a very good solution).

describe Module

Extract meta-data from a font-file to describe the font[source]

Get the family (and sub-family) for a font

ttfquery.describe.familyNames(familyID, subFamilyID=0)[source]

Convert family integers to human-readable names

ttfquery.describe.guessEncoding(font, given=None)[source]

Attempt to guess/retrieve an encoding from the font itself

Basically this will try to get the given encoding (unless it is None).

If given is a single integer or a single-item tuple, we will attempt scan looking for any table matching given as the platform ID and returning the first sub table.

If given is a two-value tuple, we will require explicit matching, and raise errors if the encoding cannot be retrieved.

if given is None, we will return the first encoding in the font.

XXX This needs some work, particularly for non-win32
platforms, where there is no preference embodied for the native encoding.

Get weight and italic modifiers for a font

weight is taken from the OS/2 usWeightClass field italic is taken from either OS/2 fsSelection or head macStyle, if either indicates italics we report italics


Get a new font object


Get the short name from the font’s names table


Convert integer number to a human-readable weight-name


Convert a string-name to a weight number compatible with this module

findsystem Module

Find system fonts (only works on Linux and Win32 at the moment)


Find fonts in paths, or the system paths if not given

XXX Doesn’t current support OS-X system paths


Get system font directories on Linux/Unix

Uses /usr/sbin/chkfontpath to get the list of system-font directories, note that many of these will not be truetype font directories.

If /usr/sbin/chkfontpath isn’t available, uses returns a set of common Linux/Unix paths


Get User-specific font directory on Win32


Get list of explicitly installed font names

glyph Module

Representation of a single glyph including contour extraction

class ttfquery.glyph.Glyph(glyphName)[source]

Bases: object

Object encapsulating metadata regarding a particular glyph


Given a character, determine contours to draw

returns a list of contours, with each contour being a list of ((x,y),flag) elements. There may be only a single contour.

compile(font, steps=3)[source]

Compile the glyph to a set of poly-line outlines

ttfquery.glyph.decomposeOutline(contour, steps=3)[source]

Decompose a single TrueType contour to a line-loop

In essence, this is the “interpretation” of the font as geometric primitives. I only support line and quadratic (conic) segments, which should support most TrueType fonts as far as I know.

The process consists of first scanning for any multi- off-curve control-point runs. For each pair of such control points, we insert a new on-curve control point.

Once we have the “expanded” control point array we scan through looking for each segment which includes an off-curve control point. These should only be bracketed by on-curve control points. For each found segment, we call our integrateQuadratic method to produce a set of points interpolating between the end points as affected by the middle control point.

All other control points merely generate a single line-segment between the endpoints.

ttfquery.glyph.integrateQuadratic(points, steps=3)[source]

Get points on curve for quadratic w/ end points A and C

Basis Equations are taken from here:

This is a very crude approach to the integration, everything is coded directly in Python, with no attempts to speed up the process.

XXX Should eventually provide adaptive steps so that
the angle between the elements can determine how many steps are used.

glyphquery Module

Glyph-specific queries on font-files


Determine the general descent for the font (for scaling)


Determine the general character height for the font (for scaling)

ttfquery.glyphquery.explicitGlyph(font, char, encoding=None)[source]

Return glyphName or None if there is not explicit glyph for char

ttfquery.glyphquery.glyphName(font, char, encoding=None, warnOnFailure=1)[source]

Retrieve the glyph name for the given character

Not sure what the effect of the Unicode mapping will be given the use of ord...
ttfquery.glyphquery.hasGlyph(font, char, encoding=None)[source]

Check to see if font appears to have explicit glyph for char


Get the base-line to base-line height for the font

There is some fudging going on here as I workaround what appears to be a problem with the specification for sTypoDescender, which states that it should normally be a negative value, but winds up being positive in at least one font that defines points below the zero axis.
XXX The entire OS/2 table doesn’t appear in a few
fonts (symbol fonts in particular), such as Corel’s BeeHive and BlackLight 686.
ttfquery.glyphquery.width(font, glyphName)[source]

Retrieve the width of the giving character for given font

The horizontal metrics table provides both the width and the left side bearing, we should really be using the left side bearing to adjust the character, but that’s a later project.

guessdescription Module

Heuristic attempting to extract descriptions from font names

This should only be used as a backup in case there is no proper available querying mechanism (i.e. fonttools), and even then, we really would rather avoid using this extremely fragile mechanism.

Basically what happens is that a name compression function is run over the font name, as seen in the Windows Registry, producing a base name and a set of modifiers, with the modifiers being the weight (as a string) and a flag indicating whether the font appears to be italicised.

XXX This is English-specific and entirely dependent on the
naming conventions commonly seen when naming fonts, so there will be a considerable number of cases where the resulting name and flags will be incorrect.
ttfquery.guessdescription.add(name, file)[source]

Add a font with name and file to this module’s registry

ttfquery.guessdescription.get(name, style=None)[source]

Get a font by name and optional style

Style defaults to (“normal”, 0)


Heuristic attempt to get weight and italic data from font-name

return base_font_name, (weight, italic)

ttfmetadata Module

Query for meta-data for a given font


ttffamily Module

Query for font-members of a particular family


ttffiles Module

Registry of available TrueType font files

XXX Currently two copies of exactly the same font
will likely confuse the registry because the specificFonts set will only have one of the metrics sets. Nothing breaks at the moment because of this, but it’s not ideal.
class ttfquery.ttffiles.Registry[source]

Bases: object

Object providing centralized registration of TTF files

families – mapping from TrueType font families
to sub-families and then to general fonts (as a set of font-names).
fonts – mapping from general fonts to modifiers to
specific font instances
specificFonts – mapping from specific font names
to the entire “metrics” set for the particular font.
files – mapping from (absolute) filenames to
specific font names
shortFiles – mapping from font filename basenames
to font-file-lists
DIRTY – flag indicating whether the registry has
had a new font registered (i.e. whether it should be saved out to disk).

Clear out the all tables and mark unchanged


Mark the registry as changed/unchanged

familyMembers(major, minor=None)[source]

Get all (general) fonts for a given family

filename = ''

Return the absolute path-name for a given specific font


Retrieve the set of font-forms (weight,italics) available in a font

fontMembers(fontName, weight=None, italics=None)[source]

Get specific font names for given generic font name

weight – if specified, only members with the given weight italics – if specified, only members where the flag matches

returns list of specific font names

load(file, clearFirst=1)[source]

Attempt to load the font metadata from a pickled file

file – a file open in binary read mode or a filename clearFirst – if true, clear tables first, and reset DIRTY to 0 after finished

matchName(name, single=0)[source]

Try to find a general font based on a name

metadata(filename, force=0)[source]

Retrieve metadata from font file

filename – fully specified path to the font file force – if false, and the metadata is already available for this file, do not access the font file to retrieve, just return the existing metadata.

return value:
tuple of:
filename – fully specified absolute path modifiers – (weightInteger, italicsFlag) specificName – specific name of the particular font stored in the given file, the name of the “modified” font fontName – name of the general font which the modifiers are specialising specifier – family specifier, two-tuple of high-level and sub-level font classifications based on font characteristics as encoded in the font file.
register(filename, modifiers=None, specificName=None, fontName=None, familySpecifier=None, force=0)[source]

Do the actual registration of a filename & metadata

See metadata function for description of the various arguments. If modifiers == None then the metadata function will be used to scan for the metadata.

force – if true, force re-reading font-file even if we already
have the meta-data for the file loaded.
save(file=None, force=0)[source]

Attempt to save the font metadata to a pickled file

file – a file open in binary write mode or a filename force – if not true and DIRTY false, then don’t actually save anything

returns number of records saved

scan(paths=None, printErrors=0, force=0)[source]

Scan the given paths registering each found font

ttfquery.ttffiles.load(*arguments, **named)[source]

Construct registry from saved file

Assembly creates a Registry object and calls the load method with the file as argument.


ttfgroups Module

Demo script to print ordered set of system fonts

ttfquery.ttfgroups.buildTable(filenames=None, failureCallback=None)[source]

Build table mapping {family:(font:{modifiers:(name,file)})}

filenames – if provided, list of filenames to scan, otherwise the full set of system fonts provided by findsystem will be used. failureCallback – if provided, a function taking three arguments, the failing filename, an error-type code, and the error object. If processing should stop, raise an error. codes:

0 – couldn’t open the font file 1 – couldn’t find modifiers in the font file 2 – couldn’t find font-name in the font file 3 – couldn’t find the generic family specifier for the font
ttfquery.ttfgroups.interactiveCallback(file, code, err)[source]

Simple error callback for interactive use