A module for finding, managing, and using fonts across platforms.
This module provides a single FontManager instance that can be shared across backends and platforms. The findfont() function returns the best TrueType (TTF) font file in the local or system font path that matches the specified FontProperties instance. The FontManager also handles Adobe Font Metrics (AFM) font files for use by the PostScript backend.
The design is based on the W3C Cascading Style Sheet, Level 1 (CSS1) font specification. Future versions may implement the Level 2 or 2.1 specifications.
Experimental support is included for using fontconfig on Unix variant platforms (Linux, OS X, Solaris). To enable it, set the constant USE_FONTCONFIG in this file to True. Fontconfig has the advantage that it is the standard way to look up fonts on X11 platforms, so if a font is installed, it is much more likely to be found.
Bases: object
A class for storing Font properties. It is used when populating the font lookup dictionary.
On import, the FontManager singleton instance creates a list of TrueType fonts based on the font properties: name, style, variant, weight, stretch, and size. The findfont() method does a nearest neighbor search to find the font that most closely matches the specification. If no good enough match is found, a default font is returned.
Search the font list for the font that most closely matches the FontProperties prop.
findfont() performs a nearest neighbor search. Each font is given a similarity score to the target font properties. The first font with the highest score is returned. If no matches below a certain threshold are found, the default font (usually Vera Sans) is returned.
directory, is specified, will only return fonts from the given directory (or subdirectory of that directory).
The result is cached, so subsequent lookups don’t have to perform the O(n) nearest neighbor search.
If fallback_to_default is True, will fallback to the default font family (usually “Bitstream Vera Sans” or “Helvetica”) if the first lookup hard-fails.
See the W3C Cascading Style Sheet, Level 1 documentation for a description of the font finding algorithm.
Returns a match score between the list of font families in families and the font family name family2.
An exact match anywhere in the list returns 0.0.
A match by generic font name will return 0.1.
No match will return 1.0.
Returns a match score between size1 and size2.
If size2 (the size specified in the font file) is ‘scalable’, this function always returns 0.0, since any font size can be generated.
Otherwise, the result is the absolute distance between size1 and size2, normalized so that the usual range of font sizes (6pt - 72pt) will lie between 0.0 and 1.0.
Returns a match score between stretch1 and stretch2.
The result is the absolute value of the difference between the CSS numeric values of stretch1 and stretch2, normalized between 0.0 and 1.0.
Returns a match score between style1 and style2.
An exact match returns 0.0.
A match between ‘italic’ and ‘oblique’ returns 0.1.
No match returns 1.0.
Returns a match score between variant1 and variant2.
An exact match returns 0.0, otherwise 1.0.
Returns a match score between weight1 and weight2.
The result is the absolute value of the difference between the CSS numeric values of weight1 and weight2, normalized between 0.0 and 1.0.
Bases: object
A class for storing and manipulating font properties.
The font properties are those described in the W3C Cascading Style Sheet, Level 1 font specification. The six properties are:
- family: A list of font names in decreasing order of priority. The items may include a generic font family name, either ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’. In that case, the actual font to be used will be looked up from the associated rcParam in matplotlibrc.
- style: Either ‘normal’, ‘italic’ or ‘oblique’.
- variant: Either ‘normal’ or ‘small-caps’.
- stretch: A numeric value in the range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’ or ‘ultra-expanded’
- weight: A numeric value in the range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’
- size: Either an relative value of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’ or an absolute font size, e.g. 12
The default font property for TrueType fonts (as specified in the default matplotlibrc file) is:
sans-serif, normal, normal, normal, normal, scalable.
Alternatively, a font may be specified using an absolute path to a .ttf file, by using the fname kwarg.
The preferred usage of font sizes is to use the relative values, e.g. ‘large’, instead of absolute font sizes, e.g. 12. This approach allows all text sizes to be made larger or smaller based on the font manager’s default font size.
This class will also accept a fontconfig pattern, if it is the only argument provided. See the documentation on fontconfig patterns. This support does not require fontconfig to be installed. We are merely borrowing its pattern syntax for use here.
Note that matplotlib’s internal font manager and fontconfig use a different algorithm to lookup fonts, so the results of the same pattern may be different in matplotlib than in other applications that use fontconfig.
Get a fontconfig pattern suitable for looking up the font as specified with fontconfig’s fc-match utility.
See the documentation on fontconfig patterns.
This support does not require fontconfig to be installed or support for it to be enabled. We are merely borrowing its pattern syntax for use here.
Set the properties by parsing a fontconfig pattern.
See the documentation on fontconfig patterns.
This support does not require fontconfig to be installed or support for it to be enabled. We are merely borrowing its pattern syntax for use here.
A function for populating a FontKey instance by extracting information from the AFM font file.
font is a class:AFM instance.
A function for populating the FontKey by extracting information from the TrueType font file.
font is a FT2Font instance.
Return the user-specified font directory for Win32. This is looked up from the registry key:
\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Fonts
If the key is not found, $WINDIR/Fonts will be returned.
A module for parsing and generating fontconfig patterns.
See the fontconfig pattern specification for more information.
A simple pyparsing-based parser for fontconfig-style patterns.
See the fontconfig pattern specification for more information.