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.FontEntry(fname='', name='', style='normal', variant='normal', weight='normal', stretch='normal', size='medium')[source]

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

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

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

fname=''

name=''

size='medium'

stretch='normal'

style='normal'

variant='normal'

weight='normal'

classmatplotlib.font_manager.FontManager(size=None, weight='normal')[source]

Базы: 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)[source]

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

Параметры:

pathstr или path-like

Примечания

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

propertydefaultFont

findfont(prop, fontext='ttf', directory=None, fallback_to_default=True, rebuild_if_missing=True)[source]

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

Параметры:

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()[source]

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

get_default_weight()[source]

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

get_font_names()[source]

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

score_family(families, family2)[source]

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

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

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

Отсутствие совпадения вернёт 1.0.

score_size(size1, size2)[source]

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

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

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

score_stretch(stretch1, stretch2)[source]

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

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

score_style(style1, style2)[source]

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

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

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

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

score_variant(variant1, variant2)[source]

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

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

score_weight(weight1, weight2)[source]

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

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

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

set_default_weight(weight)[source]

Устанавливает значение по умолчанию для начертания шрифта. Начальное значение равно 'normal'.

classmatplotlib.font_manager.FontProperties(family=None, style=None, variant=None, weight=None, stretch=None, size=None, fname=None, math_fontfamily=None)[source]

Базы: object

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

Свойства шрифта — это шесть свойств, описанных в спецификации W3C Cascading Style Sheet, Level 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 pattern, если он является единственным переданным аргументом. Эта поддержка не зависит от fontconfig; мы просто заимствуем его синтаксис шаблона для использования здесь.

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

copy()[source]

Возвращает копию self.

get_family()[source]

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

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

get_file()[source]

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

get_fontconfig_pattern()[source]

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

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

get_math_fontfamily()[source]

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

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

get_name()[source]

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

get_size()[source]

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

get_size_in_points()[source]

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

get_slant()[source]

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

get_stretch()[source]

Возвращает ширину шрифта. Варианты: 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'.

get_style()[source]

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

get_variant()[source]

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

get_weight()[source]

Устанавливает начертание шрифта. Варианты: Числовое значение в диапазоне 0-1000 или одно из 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'

set_family(family)[source]

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

set_file(file)[source]

Устанавливает имя файла шрифта для использования. В этом случае все остальные свойства будут игнорироваться.

set_fontconfig_pattern(pattern)[source]

Устанавливает свойства, анализируя шаблон fontconfig.

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

set_math_fontfamily(fontfamily)[source]

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

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

Параметры:

fontfamilystr

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

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

См. также

text.Text.get_math_fontfamily

set_name(family)[source]

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

set_size(size)[source]

Установка размера шрифта.

Параметры:

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

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

set_slant(style)[source]

Установка стиля шрифта.

Параметры:

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

set_stretch(stretch)[source]

Установка начертания или ширины шрифта.

Параметры:

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)[source]

Установка стиля шрифта.

Параметры:

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

set_variant(variant)[source]

Установка варианта шрифта.

Параметры:

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

set_weight(weight)[source]

Установка начертания шрифта.

Параметры:

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)[source]

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

Параметры:

fontpathstr

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

fontAFM

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

Возвращает:

FontEntry

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

matplotlib.font_manager.findSystemFonts(fontpaths=None, fontext='ttf')[source]

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

matplotlib.font_manager.findfont(prop, fontext='ttf', directory=None, fallback_to_default=True, rebuild_if_missing=True)[source]

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

Параметры:

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 Cascading Style Sheet, Level 1 для описания алгоритма поиска шрифтов.

matplotlib.font_manager.get_font(font_filepaths, hinting_factor=None)[source]

Получение объекта ft2font.FT2Font по списку путей к файлам.

Параметры:

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

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

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

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

Возвращает:

ft2font.FT2Font

matplotlib.font_manager.get_font_names()[source]

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

matplotlib.font_manager.get_fontext_synonyms(fontext)[source]

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

matplotlib.font_manager.is_opentype_cff_font(filename)[source]

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

matplotlib.font_manager.json_dump(data, filename)[source]

Выгружает данные FontManager в формате JSON в файл с именем filename.

См. также

json_load

Примечания

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

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

matplotlib.font_manager.json_load(filename)[source]

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

См. также

json_dump

matplotlib.font_manager.list_fonts(directory, extensions)[source]

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

matplotlib.font_manager.ttfFontProperty(font)[source]

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

Параметры:

fontFT2Font

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

Возвращаемое значение:

FontEntry

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

matplotlib.font_manager.win32FontDirectory()[source]

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

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

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

matplotlib.font_manager.fontManager[source]

Глобальная инстанция FontManager.

classmatplotlib.font_manager.FontEntry(fname='', name='', style='normal', variant='normal', weight='normal', stretch='normal', size='medium')[source]

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

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