Pygments 全部 API

此页面描述了 Pygments API。

高级 API

来自 pygments 模块的函数

pygments.lex(code, lexer)

使用 lexer（必须是 Lexer 实例）对 code 进行词法分析，并返回一个标记迭代器。目前，这仅调用 lexer.get_tokens()。

pygments.format(tokens, formatter, outfile=None)

使用格式化程序 formatter（一个 Formatter 实例）对 tokens（一个标记迭代器）进行格式化。

如果提供了 outfile 并且是一个有效的文件对象（具有 write 方法的对象），则结果将写入其中，否则将以字符串形式返回。

pygments.highlight(code, lexer, formatter, outfile=None)

这是最高级别的突出显示功能。它将 lex 和 format 组合在一个函数中。

来自 pygments.lexers 的函数

pygments.lexers.get_lexer_by_name(_alias, **options)

返回一个 Lexer 子类的实例，该实例在它的别名列表中具有 alias。词法分析器在其实例化时被赋予 options。

如果找不到具有该别名的词法分析器，则会引发 pygments.util.ClassNotFound。

pygments.lexers.get_lexer_for_filename(_fn, code=None, **options)

获取一个文件名对应的词法分析器。

返回一个 Lexer 子类实例，该实例具有与 fn 匹配的文件名模式。词法分析器在其实例化时被赋予 options。

如果找不到该文件名的词法分析器，则会引发 pygments.util.ClassNotFound。

如果多个词法分析器匹配文件名模式，则使用它们的 analyse_text() 方法来确定哪个更合适。

pygments.lexers.get_lexer_for_mimetype(_mime, **options)

返回一个 Lexer 子类实例，该实例在其 mimetype 列表中具有 mime。词法分析器在其实例化时被赋予 options。

如果找不到该 mimetype 的词法分析器，则会引发 pygments.util.ClassNotFound。

pygments.lexers.load_lexer_from_file(filename, lexername='CustomLexer', **options)

从文件中加载词法分析器。

此方法期望一个位于当前工作目录的相对路径的文件，其中包含一个词法分析器类。默认情况下，它期望词法分析器名为 CustomLexer；你可以将自己的类名作为第二个参数传递给此函数。

用户应该非常小心输入，因为此方法等同于对输入文件运行 eval。

如果导入词法分析器时遇到任何问题，则会引发 ClassNotFound。

在版本 2.2 中添加。

pygments.lexers.guess_lexer(_text, **options)

返回一个 Lexer 子类实例，该实例是从 text 中的文本推测出来的。为此，将用文本作为参数调用每个已知词法分析器类的 analyse_text() 方法，返回最高值的词法分析器将被实例化并返回。

如果没有任何词法分析器认为它可以处理内容，则会引发 pygments.util.ClassNotFound。

pygments.lexers.guess_lexer_for_filename(_fn, _text, **options)

与 guess_lexer() 相同，但只考虑在 filenames 或 alias_filenames 中具有与 filename 匹配模式的词法分析器。

如果没有任何词法分析器认为它可以处理内容，则会引发 pygments.util.ClassNotFound。

pygments.lexers.get_all_lexers(plugins=True)

返回所有已知词法分析器的元组生成器，格式为 (name, aliases, filenames, mimetypes)。

如果 plugins 为真（默认值），则也返回由 entrypoints 提供的插件词法分析器。否则，只考虑内置词法分析器。

pygments.lexers.find_lexer_class_by_name(_alias)

返回具有 alias 在其别名列表中的 Lexer 子类，不进行实例化。

与 get_lexer_by_name 相似，但不实例化类。

如果找不到具有该别名的词法分析器，则会引发 pygments.util.ClassNotFound。

在版本 2.2 中添加。

pygments.lexers.find_lexer_class(name)

返回具有由 name 参数给定的 name 属性的 Lexer 子类。

来自 pygments.formatters 的函数

pygments.formatters.get_formatter_by_name(_alias, **options)

返回一个 Formatter 子类的实例，该实例在它的别名列表中具有 alias。格式化程序在其实例化时被赋予 options。

如果找不到具有该别名的格式化程序，则会引发 pygments.util.ClassNotFound。

pygments.formatters.get_formatter_for_filename(fn, **options)

返回一个 Formatter 子类实例，该实例的 filename 模式与 fn 匹配。格式化程序在实例化时会获得 options。

如果找不到该 filename 的格式化程序，则会引发 pygments.util.ClassNotFound。

pygments.formatters.load_formatter_from_file(filename, formattername='CustomFormatter', **options)

返回从当前目录中提供的文件加载的 Formatter 子类实例。

预期该文件包含一个名为 formattername 的 Formatter 类（默认情况下为 CustomFormatter）。用户应该非常小心输入，因为此方法等同于在输入文件上运行 eval()。格式化程序在实例化时会获得 options。

如果加载格式化程序时出现任何错误，则会引发 pygments.util.ClassNotFound。

在版本 2.2 中添加。

来自 pygments.styles 的函数

pygments.styles.get_style_by_name(name)

通过其简短名称返回样式类。内置样式的名称列在 pygments.styles.STYLE_MAP 中。

如果找不到该名称的样式，则会引发 pygments.util.ClassNotFound。

pygments.styles.get_all_styles()

返回所有样式的名称生成器，包括内置样式和插件样式。

pygments.styles.STYLE_MAP = {'abap': 'abap::AbapStyle', 'algol': 'algol::AlgolStyle', 'algol_nu': 'algol_nu::Algol_NuStyle', 'arduino': 'arduino::ArduinoStyle', 'autumn': 'autumn::AutumnStyle', 'borland': 'borland::BorlandStyle', 'bw': 'bw::BlackWhiteStyle', 'coffee': 'coffee::CoffeeStyle', 'colorful': 'colorful::ColorfulStyle', 'default': 'default::DefaultStyle', 'dracula': 'dracula::DraculaStyle', 'emacs': 'emacs::EmacsStyle', 'friendly': 'friendly::FriendlyStyle', 'friendly_grayscale': 'friendly_grayscale::FriendlyGrayscaleStyle', 'fruity': 'fruity::FruityStyle', 'github-dark': 'gh_dark::GhDarkStyle', 'gruvbox-dark': 'gruvbox::GruvboxDarkStyle', 'gruvbox-light': 'gruvbox::GruvboxLightStyle', 'igor': 'igor::IgorStyle', 'inkpot': 'inkpot::InkPotStyle', 'lightbulb': 'lightbulb::LightbulbStyle', 'lilypond': 'lilypond::LilyPondStyle', 'lovelace': 'lovelace::LovelaceStyle', 'manni': 'manni::ManniStyle', 'material': 'material::MaterialStyle', 'monokai': 'monokai::MonokaiStyle', 'murphy': 'murphy::MurphyStyle', 'native': 'native::NativeStyle', 'nord': 'nord::NordStyle', 'nord-darker': 'nord::NordDarkerStyle', 'one-dark': 'onedark::OneDarkStyle', 'paraiso-dark': 'paraiso_dark::ParaisoDarkStyle', 'paraiso-light': 'paraiso_light::ParaisoLightStyle', 'pastie': 'pastie::PastieStyle', 'perldoc': 'perldoc::PerldocStyle', 'rainbow_dash': 'rainbow_dash::RainbowDashStyle', 'rrt': 'rrt::RrtStyle', 'sas': 'sas::SasStyle', 'solarized-dark': 'solarized::SolarizedDarkStyle', 'solarized-light': 'solarized::SolarizedLightStyle', 'staroffice': 'staroffice::StarofficeStyle', 'stata-dark': 'stata_dark::StataDarkStyle', 'stata-light': 'stata_light::StataLightStyle', 'tango': 'tango::TangoStyle', 'trac': 'trac::TracStyle', 'vim': 'vim::VimStyle', 'vs': 'vs::VisualStudioStyle', 'xcode': 'xcode::XcodeStyle', 'zenburn': 'zenburn::ZenburnStyle'}

内置样式的字典，将样式名称映射到 'submodule::classname' 字符串。此列表已弃用。请改用 pygments.styles.STYLES

词法分析器

所有词法分析器都继承自的基词法分析器类是

class pygments.lexer.Lexer(**options)

特定语言的词法分析器。

另请参见 编写自己的词法分析器，这是一个关于编写词法分析器的高级指南。

词法分析器类具有用于根据各种条件选择最合适的词法分析器的属性。

name

词法分析器的完整名称，以人类可读的形式

aliases

一个简短的、唯一的标识符列表，可用于从列表中查找词法分析器，例如使用 get_lexer_by_name()。

filenames

一个 fnmatch 模式列表，这些模式与包含此词法分析器内容的 filename 匹配。此列表中的模式应在所有词法分析器中都是唯一的。

alias_filenames = []

一个 fnmatch 模式列表，这些模式与可能包含或可能不包含此词法分析器内容的 filename 匹配。此列表由 guess_lexer_for_filename() 函数使用，以确定哪些词法分析器随后将包含在猜测正确的词法分析器中。这意味着例如，每个用于 HTML 和模板语言的词法分析器都应在该列表中包含 \*.html。

mimetypes

可以使用此词法分析器分析的内容的 MIME 类型列表。

priority = 0

优先级，如果多个词法分析器匹配且没有提供内容

包含在 Pygments 中的词法分析器应具有两个附加属性

url

语言规范/定义的 URL。在 Pygments 文档中使用。设置为空字符串以禁用。

version_added

添加词法分析器的 Pygments 版本。

包含在 Pygments 中的词法分析器可能具有其他属性

_example

示例文件名。相对于 tests/examplefiles 目录。这由文档生成器用于显示示例。

您可以将选项传递给构造函数。所有词法分析器都识别的基本选项以及由基 Lexer 类处理的选项是

stripnl

从输入中删除开头和结尾的换行符（默认值：True）。

stripall

从输入中删除所有开头和结尾的空格（默认值：False）。

ensurenl

确保输入以换行符结尾（默认值：True）。这对于一些按行消费输入的词法分析器是必需的。

在 1.3 版中添加。

tabsize

如果给出且大于 0，则展开输入中的制表符（默认值：0）。

encoding

如果给出，则必须是编码名称。此编码将用于将输入字符串转换为 Unicode，如果它还不是 Unicode 字符串（默认值：'guess'，它使用简单的 UTF-8 / Locale / Latin1 检测。也可以是 'chardet'，如果安装了 chardet 库，则使用该库。

inencoding

如果给出，则覆盖 encoding。

__init__(**options)

此构造函数将任意选项作为关键字参数。每个子类都必须首先处理自己的选项，然后调用 Lexer 构造函数，因为它处理 stripnl 等基本选项。

一个例子如下所示

def __init__(self, **options):
    self.compress = options.get('compress', '')
    Lexer.__init__(self, **options)

由于这些选项都必须作为字符串指定（由于命令行使用），因此有各种实用程序函数可用于帮助实现这一点，请参见 实用程序。

add_filter(filter_, **options)

在此词法分析器中添加一个新的流过滤器。

static analyse_text(text)

用于词法分析器猜测的静态方法。

它应该分析文本并返回一个介于 0.0 到 1.0 之间的浮点数。如果返回 0.0，则词法分析器将不会被选为最可能的词法分析器；如果返回 1.0，它将被立即选择。这由 guess_lexer 使用。

LexerMeta 元类会自动包装此函数，使其像静态方法一样工作（没有 self 或 cls 参数），返回值会自动转换为 float。如果返回值是一个布尔值为 False 的对象，则等同于返回值为 0.0。

get_tokens(text, unfiltered=False)

此方法是词法分析器的基本接口。它由 highlight() 函数调用。它必须处理文本并返回 (tokentype, value) 对的可迭代对象，这些对来自 text。

通常，您不需要覆盖此方法。默认实现会处理所有词法分析器识别的选项（stripnl、stripall 等等），然后从 get_tokens_unprocessed() 中生成所有标记，并去掉 index。

如果将 unfiltered 设置为 True，即使定义了过滤器，也会绕过过滤机制。

get_tokens_unprocessed(text)

此方法应处理文本并返回 (index, tokentype, value) 元组的可迭代对象，其中 index 是标记在输入文本中的起始位置。

它必须由子类覆盖。建议将其实现为生成器，以最大限度地提高效率。

有多个从 Lexer 派生的基类可用于构建词法分析器

class pygments.lexer.RegexLexer(*args, **kwds)

简单状态化正则表达式词法分析器的基础。简化了词法分析过程，因此您只需要提供状态和正则表达式的列表。

class pygments.lexer.ExtendedRegexLexer(*args, **kwds)

使用上下文对象存储其状态的 RegexLexer。

class pygments.lexer.DelegatingLexer(_root_lexer, _language_lexer, _needle=('Other',), **options)

此词法分析器接受两个词法分析器作为参数。一个根词法分析器和一个语言词法分析器。首先使用语言词法分析器扫描所有内容，然后使用根词法分析器对所有 Other 标记进行词法分析。

来自 template 词法分析器包的词法分析器使用此基词法分析器。

格式化程序

格式化程序是从此类派生的

class pygments.formatter.Formatter(**options)

将标记流转换为文本。

格式化程序应该具有帮助选择它们的属性。这些类似于相应的 Lexer 属性。

name

格式化程序的完整名称，以人类可读的形式。

aliases

一个简短、唯一的标识符列表，可用于从列表中查找格式化程序，例如使用 get_formatter_by_name()。

filenames

一个 fnmatch 模式列表，与该格式化程序可以生成输出的文件名匹配。此列表中的模式应在所有格式化程序中都是唯一的。

您可以将选项作为关键字参数传递给构造函数。所有格式化程序都接受这些基本选项

style

要使用的样式，可以是字符串或 Style 子类（默认值：“default”）。例如，TerminalFormatter 不使用它。

full

告诉格式化程序输出一个“完整”的文档，即一个完整的自包含文档。这对某些格式化程序没有任何影响（默认值：false）。

title

如果 full 为 true，则应使用该标题为文档加标题（默认值：‘’）。

encoding

如果给出，必须是编码名称。这将用于将 Unicode 标记字符串转换为输出中的字节字符串。如果它为 “” 或 None，则 Unicode 字符串将写入输出文件，大多数类文件对象不支持它（默认值：None）。

outencoding

如果给出，则覆盖 encoding。

__init__(**options)

与词法分析器一样，此构造函数接受任意可选参数，如果您覆盖它，您应该首先处理您自己的选项，然后调用基类实现。

format(tokensource, outfile)

此方法必须格式化来自 tokensource 可迭代对象的标记并将格式化后的版本写入文件对象 outfile。

格式化程序选项可以控制标记的转换方式。

get_style_defs(arg='')

此方法必须返回适合为后续突出显示的文本定义当前样式的语句或声明（例如，HTMLFormatter 中的 CSS 类）。

可选参数 arg 可用于修改生成，并依赖于格式化程序（它已标准化，因为可以在命令行上给出它）。

此方法由 -S 命令行选项 调用，arg 由 -a 选项给出。

实用程序

pygments.util 模块具有一些可用于处理命令行选项的实用函数。以下所有函数都从选项字典中获取值。如果值已经是选项期望的类型，则按原样返回它。否则，如果值是字符串，则首先尝试将其转换为期望的类型（如果可能）。

exception pygments.util.OptionError

如果参数的类型或值不正确，所有选项处理函数都会引发此异常。

pygments.util.get_bool_opt(options, optname, default=None)

直观地说，这是 options.get(optname, default)，但仅限于布尔值。布尔值可以表示为字符串，以便接受来自命令行参数的布尔值。如果键 optname 出现在字典 options 中，并且未与布尔值关联，则引发 OptionError。如果它不存在，则返回 default。

用于 True 的有效字符串值为 1、yes、true 和 on，用于 False 的有效字符串值为 0、no、false 和 off（不区分大小写匹配）。

pygments.util.get_int_opt(options, optname, default=None)

如 get_bool_opt()，但将值解释为整数。

pygments.util.get_list_opt(options, optname, default=None)

如果字典 options 中的键 optname 是一个字符串，则以空格为分隔符将其拆分并返回。如果它已经是列表或元组，则将其作为列表返回。

pygments.util.get_choice_opt(options, optname, allowed, default=None, normcase=False)

如果字典中的键 optname 不在序列 allowed 中，则抛出错误，否则返回它。

它还定义了一个异常

exception pygments.util.ClassNotFound

如果其中一个查找函数没有找到匹配的类，则抛出此异常。