matplotlib.font_manager

Модуль для поиска, управления и использования шрифтов на разных платформах.

Этот модуль предоставляет единственный экземпляр FontManager — fontManager, который можно совместно использовать в разных бэкендах и на разных платформах. Функция findfont возвращает файл шрифта TrueType (TTF) из локального или системного пути поиска шрифтов, который лучше всего соответствует заданному экземпляру FontProperties. FontManager также обрабатывает файлы шрифтов Adobe Font Metrics (AFM), используемые бэкендом PostScript. Функция FontManager.addfont добавляет пользовательский шрифт из файла, не устанавливая его в операционную систему.

В основе реализации лежит спецификация шрифтов W3C Cascading Style Sheet, Level 1 (CSS1). В будущих версиях могут быть реализованы спецификации Level 2 или 2.1.

classmatplotlib.font_manager.FontManager(size=None, weight='normal')[исходный код]

Базовые классы: object

При импорте модуля синглтон FontManager создает список шрифтов ttf и afm и кэширует их свойства FontProperties. Метод FontManager.findfont выполняет поиск ближайшего соседа, чтобы найти шрифт, наиболее точно соответствующий спецификации. Если подходящий вариант не найден, возвращается шрифт по умолчанию.

Шрифты, добавленные методом FontManager.addfont, не сохраняются в кэше; поэтому addfont необходимо вызывать при каждом импорте Matplotlib. Этот метод следует использовать только в том случае, если шрифт невозможно установить в операционную систему другими способами.

Примечания

Метод FontManager.addfont необходимо вызывать для глобального экземпляра FontManager.

Пример использования:

import matplotlib.pyplot as plt
from matplotlib import font_manager

font_dirs = ["/resources/fonts"]  # The path to the custom font file.
font_files = font_manager.findSystemFonts(fontpaths=font_dirs)

for font_file in font_files:
    font_manager.fontManager.addfont(font_file)

addfont(path)[исходный код]

Кэширует свойства шрифта по адресу path, чтобы сделать его доступным для FontManager. Тип шрифта определяется по суффиксу пути.

Параметры:

pathstr или объект, подобный пути

Примечания

Этот метод полезен для добавления пользовательского шрифта без его установки в операционную систему. Информацию об использовании и ограничениях этой функции см. в описании синглтона FontManager.

propertydefaultFont

findfont(prop, fontext='ttf', directory=None, fallback_to_default=True, rebuild_if_missing=True)[исходный код]

Находит путь к файлу шрифта, наиболее точно соответствующему заданным свойствам шрифта.

Параметры:

propstr или FontProperties

Свойства шрифта для поиска. Это может быть объект FontProperties или строка, задающая шаблон fontconfig.

fontext{'ttf', 'afm'}, по умолчанию: 'ttf'

Расширение файла шрифта:

• 'ttf': шрифты TrueType и OpenType (.ttf, .ttc, .otf)
• 'afm': Adobe Font Metrics (.afm)

directorystr, необязательный

Если задано, поиск выполняется только в этом каталоге и его подкаталогах.

fallback_to_defaultbool

Если значение равно True, при окончательной неудаче первого поиска будет использоваться семейство шрифтов по умолчанию (обычно "DejaVu Sans" или "Helvetica").

rebuild_if_missingbool

Определяет, следует ли перестроить кэш шрифтов и выполнить поиск повторно, если первый результат указывает на несуществующий шрифт (то есть кэш шрифтов содержит устаревшие записи).

Возвращает:

str

Имя файла наиболее подходящего шрифта.

Примечания

Выполняется поиск ближайшего соседа. Каждому шрифту присваивается оценка сходства с заданными свойствами целевого шрифта. Возвращается первый шрифт с наивысшей оценкой. Если не найдено совпадений, превышающих заданный порог, возвращается шрифт по умолчанию (обычно DejaVu Sans).

Результат кэшируется, поэтому при последующих поисках не требуется выполнять поиск ближайшего соседа за O(n).

Описание алгоритма поиска шрифтов см. в документации W3C Cascading Style Sheet, Level 1.

staticget_default_size()[исходный код]

Возвращает размер шрифта по умолчанию.

get_default_weight()[исходный код]

Возвращает толщину шрифта по умолчанию.

get_font_names()[исходный код]

Возвращает список доступных шрифтов.

score_family(families, family2)[исходный код]

Возвращает оценку совпадения между списком семейств шрифтов families и именем семейства шрифтов family2.

Точное совпадение с первым элементом списка дает значение 0.0.

Совпадение с элементом ниже в списке дает значение от 0 до 1.

При отсутствии совпадения возвращается значение 1.0.

score_size(size1, size2)[исходный код]

Возвращает оценку совпадения между size1 и size2.

Если size2 (размер, указанный в файле шрифта) имеет значение 'scalable', эта функция всегда возвращает 0.0, поскольку можно создать шрифт любого размера.

В противном случае результатом является абсолютная разница между size1 и size2, нормированная так, чтобы обычный диапазон размеров шрифта (6pt–72pt) соответствовал значениям от 0.0 до 1.0.

score_stretch(stretch1, stretch2)[исходный код]

Возвращает оценку совпадения между stretch1 и stretch2.

Результат представляет собой абсолютную разницу между числовыми значениями CSS для stretch1 и stretch2, нормированную в диапазоне от 0.0 до 1.0.

score_style(style1, style2)[исходный код]

Возвращает оценку совпадения между style1 и style2.

Точное совпадение дает значение 0.0.

Совпадение между 'italic' и 'oblique' дает значение 0.1.

При отсутствии совпадения возвращается значение 1.0.

score_variant(variant1, variant2)[исходный код]

Возвращает оценку совпадения между variant1 и variant2.

Точное совпадение дает значение 0.0, в противном случае — 1.0.

score_weight(weight1, weight2)[исходный код]

Возвращает оценку совпадения между weight1 и weight2.

Результат равен 0.0, если значения weight1 и weight2 заданы строками и совпадают.

В противном случае результат представляет собой абсолютную разницу между числовыми значениями CSS для weight1 и weight2, нормированную в диапазоне от 0.05 до 1.0.

set_default_weight(weight)[исходный код]

Задает толщину шрифта по умолчанию. Начальное значение — 'normal'.

classmatplotlib.font_manager.FontProperties(family=None, style=None, variant=None, weight=None, stretch=None, size=None, fname=None, math_fontfamily=None)[исходный код]

Базовые классы: object

Класс для хранения свойств шрифта и управления ими.

Свойства шрифта включают шесть свойств, описанных в спецификации шрифтов каскадных таблиц стилей W3C, уровень 1, а также math_fontfamily для математических шрифтов:

• family: Список названий шрифтов в порядке убывания приоритета. Элементы могут включать общее название семейства шрифтов: 'sans-serif', 'serif', 'cursive', 'fantasy' или 'monospace'. В этом случае фактический используемый шрифт будет определён по соответствующему rcParam в процессе поиска с помощью findfont. По умолчанию: rcParams["font.family"] (по умолчанию: ['sans-serif'])
• style: 'normal', 'italic' или 'oblique'. По умолчанию: rcParams["font.style"] (по умолчанию: 'normal')
• variant: 'normal' или 'small-caps'. По умолчанию: rcParams["font.variant"] (по умолчанию: 'normal')
• stretch: Числовое значение в диапазоне 0–1000 или одно из значений 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded' или 'ultra-expanded'. По умолчанию: rcParams["font.stretch"] (по умолчанию: 'normal')
• weight: Числовое значение в диапазоне 0–1000 или одно из значений 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'. По умолчанию: rcParams["font.weight"] (по умолчанию: 'normal')
• size: Относительное значение 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large' или абсолютный размер шрифта, например 10. По умолчанию: rcParams["font.size"] (по умолчанию: 10.0)
• math_fontfamily: Семейство шрифтов, используемых для отображения математического текста. Поддерживаются значения: 'dejavusans', 'dejavuserif', 'cm', 'stix', 'stixsans' и 'custom'. По умолчанию: rcParams["mathtext.fontset"] (по умолчанию: 'dejavusans')

Вместо этого шрифт можно задать с помощью абсолютного пути к файлу шрифта, используя аргумент fname. Однако в этом случае обычно проще передать путь (как объект pathlib.Path, а не str) аргументу font объекта Text.

Рекомендуется задавать размеры шрифта относительными значениями, например 'large', а не абсолютными, например 12. Такой подход позволяет увеличивать или уменьшать размер всего текста относительно размера шрифта по умолчанию, заданного менеджером шрифтов.

Этот класс принимает единственную позиционную строку в качестве шаблона fontconfig либо отдельные свойства в виде именованных аргументов:

FontProperties(pattern)
FontProperties(*, family=None, style=None, variant=None, ...)

Эта возможность не зависит от fontconfig; здесь используется лишь заимствованный синтаксис его шаблонов.

Обратите внимание: внутренний менеджер шрифтов Matplotlib и fontconfig используют разные алгоритмы поиска шрифтов, поэтому результаты для одного и того же шаблона в Matplotlib могут отличаться от результатов в других приложениях, использующих fontconfig.

copy()[исходный код]

Возвращает копию текущего объекта.

get_family()[исходный код]

Возвращает список отдельных названий семейств шрифтов или общих названий семейств.

Семейства шрифтов или общие семейства шрифтов (которые будут определены по соответствующим rcParams при поиске подходящего шрифта), перечисленные в порядке предпочтения.

get_file()[исходный код]

Возвращает имя файла связанного шрифта.

get_fontconfig_pattern()[исходный код]

Возвращает шаблон fontconfig, подходящий для поиска шрифта, заданного с помощью утилиты fc-match из fontconfig.

Эта возможность не зависит от fontconfig; здесь используется лишь заимствованный синтаксис его шаблонов.

get_math_fontfamily()[исходный код]

Возвращает название семейства шрифтов, используемого для математического текста.

Шрифт по умолчанию: rcParams["mathtext.fontset"] (по умолчанию: 'dejavusans').

get_name()[исходный код]

Возвращает название шрифта, наиболее соответствующего свойствам шрифта.

get_size()[исходный код]

Возвращает размер шрифта.

get_size_in_points()[исходный код]

Возвращает размер шрифта.

get_slant()[исходный код]

Возвращает стиль шрифта. Возможные значения: 'normal', 'italic' или 'oblique'.

get_stretch()[исходный код]

Возвращает степень сжатия или ширину шрифта. Возможные значения: 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'.

get_style()[исходный код]

Возвращает стиль шрифта. Возможные значения: 'normal', 'italic' или 'oblique'.

get_variant()[исходный код]

Возвращает вариант шрифта. Возможные значения: 'normal' или 'small-caps'.

get_weight()[исходный код]

Задаёт насыщенность шрифта. Возможные значения: числовое значение в диапазоне 0–1000 или одно из значений 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'

set_family(family)[исходный код]

Изменяет семейство шрифтов. Можно указать псевдоним (в терминологии CSS — общее название), например 'serif', 'sans-serif', 'cursive', 'fantasy' или 'monospace', реальное название шрифта или список реальных названий шрифтов. Реальные названия шрифтов не поддерживаются, если rcParams["text.usetex"] (по умолчанию: False) имеет значение True. По умолчанию: rcParams["font.family"] (по умолчанию: ['sans-serif'])

set_file(file)[исходный код]

Задаёт имя файла шрифта. В этом случае все остальные свойства игнорируются.

set_fontconfig_pattern(pattern)[исходный код]

Задаёт свойства, разбирая шаблон fontconfig.

Эта возможность не зависит от fontconfig; здесь используется лишь заимствованный синтаксис его шаблонов.

set_math_fontfamily(fontfamily)[исходный код]

Задаёт семейство шрифтов для текста в математическом режиме.

Если значение не задано явно, будет использоваться rcParams["mathtext.fontset"] (по умолчанию: 'dejavusans').

Параметры:

fontfamilystr

Название семейства шрифтов.

Доступные семейства шрифтов определены в файле matplotlibrc по умолчанию.

См. также

text.Text.get_math_fontfamily

set_name(family)[исходный код]

Изменяет семейство шрифтов. Можно указать псевдоним (в терминологии CSS — общее название), например 'serif', 'sans-serif', 'cursive', 'fantasy' или 'monospace', реальное название шрифта или список реальных названий шрифтов. Реальные названия шрифтов не поддерживаются, если rcParams["text.usetex"] (по умолчанию: False) имеет значение True. По умолчанию: rcParams["font.family"] (по умолчанию: ['sans-serif'])

set_size(size)[исходный код]

Задаёт размер шрифта.

Параметры:

sizefloat или {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}, по умолчанию: rcParams["font.size"] (по умолчанию: 10.0)

Если задано число с плавающей точкой, размер шрифта указывается в пунктах. Строковые значения задают размеры относительно размера шрифта по умолчанию.

set_slant(style)[исходный код]

Задаёт стиль шрифта.

Параметры:

style{'normal', 'italic', 'oblique'}, по умолчанию: rcParams["font.style"] (по умолчанию: 'normal')

set_stretch(stretch)[исходный код]

Задаёт степень сжатия или ширину шрифта.

Параметры:

stretchint или {'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}, по умолчанию: rcParams["font.stretch"] (по умолчанию: 'normal')

Если задано целое число, оно должно находиться в диапазоне 0–1000.

set_style(style)[исходный код]

Задаёт стиль шрифта.

Параметры:

style{'normal', 'italic', 'oblique'}, по умолчанию: rcParams["font.style"] (по умолчанию: 'normal')

set_variant(variant)[исходный код]

Задаёт вариант шрифта.

Параметры:

variant{'normal', 'small-caps'}, по умолчанию: rcParams["font.variant"] (по умолчанию: 'normal')

set_weight(weight)[исходный код]

Задаёт насыщенность шрифта.

Параметры:

weightint или {'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}, по умолчанию: rcParams["font.weight"] (по умолчанию: 'normal')

Если задано целое число, оно должно находиться в диапазоне 0–1000.

matplotlib.font_manager.afmFontProperty(fontpath, font)[исходный код]

Извлекает информацию из файла шрифта AFM.

Параметры:

fontpathstr

Имя файла, соответствующего font.

fontAFM

Файл шрифта AFM, из которого будет извлечена информация.

Возвращает:

FontEntry

Извлечённые свойства шрифта.

matplotlib.font_manager.findSystemFonts(fontpaths=None, fontext='ttf')[исходный код]

Ищет шрифты по указанным путям. Если пути не заданы, используются стандартные системные пути, а также список шрифтов, отслеживаемых fontconfig, если fontconfig установлен и доступен. По умолчанию возвращается список шрифтов TrueType; также можно выбрать шрифты AFM.

matplotlib.font_manager.findfont(prop, fontext='ttf', directory=None, fallback_to_default=True, rebuild_if_missing=True)[исходный код]

Находит путь к файлу шрифта, наиболее точно соответствующему заданным свойствам шрифта.

Параметры:

propstr или FontProperties

Свойства шрифта, по которым выполняется поиск. Это может быть объект FontProperties или строка, задающая шаблон fontconfig.

fontext{'ttf', 'afm'}, по умолчанию: 'ttf'

Расширение файла шрифта:

• 'ttf': шрифты TrueType и OpenType (.ttf, .ttc, .otf)
• 'afm': метрики шрифтов Adobe (.afm)

directorystr, необязательный

Если задан, поиск выполняется только в этом каталоге и его подкаталогах.

fallback_to_defaultbool

Если значение True, при полном сбое первого поиска будет использовано семейство шрифтов по умолчанию (обычно "DejaVu Sans" или "Helvetica").

rebuild_if_missingbool

Следует ли перестроить кэш шрифтов и повторить поиск, если первая найденная запись указывает на отсутствующий шрифт (то есть кэш шрифтов содержит устаревшие записи).

Возвращает:

str

Имя файла наиболее подходящего шрифта.

Примечания

Выполняется поиск ближайшего соседа. Каждому шрифту присваивается оценка сходства с целевыми свойствами шрифта. Возвращается первый шрифт с наивысшей оценкой. Если не найдено совпадений выше определённого порога, возвращается шрифт по умолчанию (обычно DejaVu Sans).

Результат кэшируется, поэтому при последующих поисках не требуется выполнять поиск ближайшего соседа за O(n).

Описание алгоритма поиска шрифтов см. в документации каскадных таблиц стилей W3C, уровень 1.

matplotlib.font_manager.get_font(font_filepaths, hinting_factor=None)[исходный код]

Возвращает объект ft2font.FT2Font по списку путей к файлам.

Параметры:

font_filepathsIterable[str, Path, bytes], str, Path, bytes

Относительные или абсолютные пути к используемым файлам шрифтов.

Если передана одна строка, последовательность байтов или объект pathlib.Path, он будет обработан как список, содержащий только этот элемент.

Если передано несколько путей к файлам, возвращённый объект FT2Font будет поочерёдно использовать шрифты в указанном порядке, чтобы найти необходимый глиф.

Возвращает:

ft2font.FT2Font

matplotlib.font_manager.get_font_names()[исходный код]

Возвращает список доступных шрифтов.

matplotlib.font_manager.get_fontext_synonyms(fontext)[исходный код]

Возвращает список расширений файлов, являющихся синонимами для заданного расширения файла fileext.

matplotlib.font_manager.is_opentype_cff_font(filename)[исходный код]

Возвращает, является ли указанный шрифт шрифтом PostScript Compact Font Format, встроенным в оболочку OpenType. Используется бэкендами PostScript и PDF, которые не могут создавать подмножества таких шрифтов.

matplotlib.font_manager.json_dump(data, filename)[исходный код]

Записывает FontManager data в формате JSON в файл с именем filename.

См. также

json_load

Примечания

Пути к файлам, являющимся дочерними элементами пути к данным Matplotlib (обычно это шрифты, поставляемые с Matplotlib), сохраняются относительно этого пути к данным, чтобы оставаться действительными в разных virtualenv.

Эта функция временно блокирует выходной файл, чтобы предотвратить перезапись данных несколькими процессами.

matplotlib.font_manager.json_load(filename)[исходный код]

Загружает FontManager из JSON-файла с именем filename.

См. также

json_dump

matplotlib.font_manager.list_fonts(directory, extensions)[исходный код]

Возвращает список всех шрифтов с любым из указанных расширений, найденных в каталоге и его подкаталогах.

matplotlib.font_manager.ttfFontProperty(font)[исходный код]

Извлекает информацию из файла шрифта TrueType.

Параметры:

fontFT2Font

Файл шрифта TrueType, из которого будет извлечена информация.

Возвращает:

FontEntry

Извлечённые свойства шрифта.

matplotlib.font_manager.win32FontDirectory()[исходный код]

Возвращает указанный пользователем каталог шрифтов для Win32. Он определяется по ключу реестра

\\HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Fonts

Если ключ не найден, будет возвращено %WINDIR%\Fonts.

matplotlib.font_manager.fontManager[исходный код]

Глобальный экземпляр FontManager.

classmatplotlib.font_manager.FontEntry(fname='', name='', style='normal', variant='normal', weight='normal', stretch='normal', size='medium')[исходный код]

Класс для хранения свойств шрифта.

Используется при заполнении словаря для поиска шрифтов.