可用的格式化程序

此页面列出了所有内置格式化程序。

通用选项

所有格式化程序都支持这些选项

encoding

如果给出，则必须是编码名称（例如 "utf-8"）。这将用于将标记字符串（为 Unicode 字符串）转换为输出中的字节字符串（默认值：None）。如果给出 full 选项，它也会写入适合文档格式的编码声明（例如，HTML 中的 meta content-type 指令或 LaTeX 中对 inputenc 包的调用）。

如果为 "" 或 None，Unicode 字符串将写入输出文件，大多数类文件对象不支持。例如，如果调用 pygments.highlight() 且没有 outfile 参数和具有 encoding 设置为 None 的格式化程序，它将返回一个 Unicode 字符串，因为它使用 StringIO.StringIO 对象，该对象支持对 write() 的 Unicode 参数。使用常规文件对象将不起作用。

在版本 0.6 中添加。

outencoding

从命令行使用 Pygments 时，任何给定的 encoding 选项都将传递给词法分析器和格式化程序。这有时不理想，例如，如果您想将输入编码设置为 "guess"。因此，引入了 outencoding，它在给出时会覆盖格式化程序的 encoding。

在版本 0.7 中添加。

格式化程序类

所有这些类都可以从 pygments.formatters 导入。

class BBCodeFormatter

简短名称：

bbcode, bb

文件名：

无

使用 BBcode 格式化标记。这些格式化代码被许多公告板使用，因此您可以在将源代码发布到那里之前使用 pygments 对其进行突出显示。

此格式化程序不支持背景颜色和边框，因为没有通用的 BBcode 标记用于此。

某些板系统（例如 phpBB）不支持其 [code] 标记中的颜色，因此您无法将突出显示与该标记一起使用。[code] 标记中的文本通常以等宽字体显示（此格式化程序可以使用 monofont 选项实现）并且没有空格（您需要缩进）被删除。

接受的附加选项

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。

codetag

如果设置为 true，则将输出放在 [code] 标记中（默认值：false）。

monofont

如果设置为 true，则添加一个标记以使用等宽字体显示代码（默认值：false）。

class BmpImageFormatter

简短名称：

bmp, bitmap

文件名：

*.bmp

从源代码创建位图图像。这使用 Python Imaging Library 从源代码生成一个像素图。

在版本 1.0 中添加。

class GifImageFormatter

简短名称：

gif

文件名：

*.gif

从源代码创建 GIF 图像。这使用 Python Imaging Library 从源代码生成一个像素图。

在版本 1.0 中添加。

class GroffFormatter

简短名称：

groff, troff, roff

文件名：

无

使用 groff 转义符格式化标记以更改其颜色和字体样式。

在版本 2.11 中添加。

接受的附加选项

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。

monospaced

如果设置为 true，将使用等宽字体（默认值：true）。

linenos

如果设置为 true，则打印行号（默认值：false）。

wrap

将行换行到指定数量的字符。如果设置为 0，则禁用（默认值：0）。

class HtmlFormatter

简短名称：

html

文件名：

*.html, *.htm

将标记格式化为 HTML 4 <span> 标记。默认情况下，内容包含在一个 <pre> 标记中，自身包含在一个 <div> 标记中（但请参见 nowrap 选项）。<div> 的 CSS 类可以通过 cssclass 选项设置。

如果 linenos 选项设置为 "table"，则 <pre> 还会包装在一个 <table> 中，该表有一行两列：一列包含行号，另一列包含代码。示例

<div class="highlight" >
<table><tr>
  <td class="linenos" title="click to toggle"
    onclick="with (this.firstChild.style)
             { display = (display == '') ? 'none' : '' }">
    <pre>1
    2</pre>
  </td>
  <td class="code">
    <pre><span class="Ke">def </span><span class="NaFu">foo</span>(bar):
      <span class="Ke">pass</span>
    </pre>
  </td>
</tr></table></div>

（添加了空格以提高清晰度）。

可以使用 hl_lines 选项指定行列表，以使这些行突出显示（从 Pygments 0.11 开始）。

使用 full 选项，将输出完整的 HTML 4 文档，包括 <style> 标记内的样式定义，或者如果给出 cssfile 选项，则在单独的文件中。

当 tagsfile 设置为 ctags 索引文件的路径时，它用于从名称生成指向其定义的超链接。您必须启用 lineanchors 并使用 -n 选项运行 ctags 以使其正常工作。必须安装 PyPI 上的 python-ctags 模块才能使用此功能；否则将引发 RuntimeError。

HtmlFormatter 的 get_style_defs(arg=’’) 方法返回一个字符串，其中包含格式化程序使用的 CSS 类的 CSS 规则。参数 arg 可用于指定附加的 CSS 选择器，这些选择器将附加到类前面。调用 fmter.get_style_defs(‘td .code’) 将导致以下 CSS 类

td .code .kw { font-weight: bold; color: #00FF00 }
td .code .cm { color: #999999 }
...

如果您拥有 Pygments 0.6 或更高版本，您还可以将列表或元组传递给 get_style_defs() 方法，以请求标记的多个前缀

formatter.get_style_defs(['div.syntax pre', 'pre.syntax'])

然后输出将如下所示

div.syntax pre .kw,
pre.syntax .kw { font-weight: bold; color: #00FF00 }
div.syntax pre .cm,
pre.syntax .cm { color: #999999 }
...

接受的附加选项

nowrap

如果设置为 True，则不要在标记周围添加 <pre> 和 <div> 标记。这会禁用大多数其他选项（默认值：False）。

full

告诉格式化程序输出“完整”文档，即一个完整的自包含文档（默认值：False）。

title

如果 full 为 true，则用于为文档添加标题的标题（默认值：''）。

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。如果给出 cssfile 和 noclobber_cssfile 选项并且 cssfile 中指定的文件存在，则此选项无效。

noclasses

如果设置为 true，则标记 <span> 标记（以及行号元素）将不使用 CSS 类，而是使用内联样式。对于较大的代码段不建议这样做，因为它会大大增加输出大小（默认值：False）。

classprefix

由于标记类型使用相对较短的类名，因此它们可能会与您自己的某些类名发生冲突。在这种情况下，您可以使用 classprefix 选项来提供一个字符串，将其附加到为标记类型生成的所有 Pygments 生成的 CSS 类名前面。请注意，此选项也会影响 get_style_defs() 的输出。

cssclass

包装 <div> 标记的 CSS 类（默认值：'highlight'）。如果您设置此选项，则 get_style_defs() 的默认选择器将为此类。

在版本 0.9 中添加： 如果您选择 'table' 行号，则包装表将具有此字符串加上 'table' 的 CSS 类，默认值相应地为 'highlighttable'。

cssstyles

包装 <div> 标记的内联 CSS 样式（默认值：''）。

prestyles

用于 <pre> 标记的内联 CSS 样式（默认值：''）。

在版本 0.11 中添加。

cssfile

如果给出 full 选项，并且给出此选项，则它必须是外部文件的名称。如果文件名不包含绝对路径，则该文件的路径将被假定为相对于主输出文件的路径，如果后者可以找到。然后，样式表将写入此文件，而不是写入 HTML 文件。

在版本 0.6 中添加。

noclobber_cssfile

如果给出 cssfile 并且指定的文件存在，则不会覆盖 css 文件。这允许在使用 full 选项以及用户指定的 css 文件时使用。默认值为 False。

在版本 1.1 中添加。

linenos

如果设置为 'table'，则将行号输出为具有两个单元格的表格，一个单元格包含行号，另一个单元格包含整个代码。这支持复制粘贴，但可能会导致某些浏览器或字体对齐问题。如果设置为 'inline'，则行号将集成到包含代码的 <pre> 标记中（该设置是 *Pygments 0.8 中的新功能*）。

为了与 Pygments 0.7 及更早版本兼容，除了 'inline' 之外的任何真值都与 'table' 相同（特别是，这意味着也包含 True）。

默认值为 False，这意味着根本没有行号。

注意：使用默认（“table”）行号机制时，除非给包含的 <pre> 标签指定显式的 line-height CSS 属性，否则 Internet Explorer 中的行号和代码可能具有不同的行高（使用 line-height: 125% 可以获得默认行间距）。

hl_lines

指定要突出显示的行列表。行号始终相对于输入（即第一行为第 1 行），并且独立于 linenostart。

在版本 0.11 中添加。

linenostart

第一行的行号（默认：1）。

linenostep

如果设置为数字 n > 1，则只打印每隔 n 个行号。

linenospecial

如果设置为数字 n > 0，则每隔 n 个行号将被赋予 CSS 类 "special"（默认：0）。

nobackground

如果设置为 True，则格式化程序不会输出包装元素的背景颜色（当没有包装元素时，这将自动默认为 False [例如：没有给 get_syntax_defs 方法提供参数]）（默认：False）。

在版本 0.6 中添加。

lineseparator

此字符串在代码行的输出之间。它默认为 "\n"，这足以在 <pre> 标签内换行，但您可以例如将其设置为 "<br>" 以获取 HTML 换行符。

在版本 0.7 中添加。

lineanchors

如果设置为非空字符串，例如 foo，则格式化程序将使用 id（和 name）为 foo-linenumber 的锚标签包装每个输出行。这允许轻松链接到特定行。

在版本 0.9 中添加。

linespans

如果设置为非空字符串，例如 foo，则格式化程序将使用 id 为 foo-linenumber 的跨度标签包装每个输出行。这允许通过 javascript 轻松访问行。

在版本 1.6 中添加。

anchorlinenos

如果设置为 True，则将行号包装在 <a> 标签中。与 linenos 和 lineanchors 结合使用。

tagsfile

如果设置为 ctags 文件的路径，则将名称包装在链接到其定义的锚标签中。应该使用 lineanchors，并且 tags 文件应指定行号（参见 ctags 的 -n 选项）。假定 tags 文件以 UTF-8 编码。

在版本 1.6 中添加。

tagurlformat

用于生成到 ctags 定义的链接的字符串格式化模式。可用变量是 %(path)s、%(fname)s 和 %(fext)s。默认为空字符串，导致只有 #prefix-number 链接。

在版本 1.6 中添加。

filename

用于在呈现 <pre> 块时生成文件名，例如显示源代码时。如果 linenos 设置为 'table'，则文件名将在包含一个跨越两列的 <th> 的初始行中呈现。

在版本 2.1 中添加。

wrapcode

使用 <code> 包装 <pre> 块内的代码，如 HTML5 规范推荐。

在版本 2.4 中添加。

debug_token_types

为所有显示标记名称的标记 <span> 标签添加 title 属性。

在版本 2.10 中添加。

子类化 HTML 格式化程序

在版本 0.7 中添加。

HTML 格式化程序现在以一种允许轻松子类化的方式构建，从而自定义输出 HTML 代码。 format() 方法调用 self._format_lines()，后者返回一个生成器，生成 (1, line) 的元组，其中 1 表示 line 是格式化源代码的一行。

如果设置了 nowrap 选项，则对生成器进行迭代并输出生成的 HTML。

否则， format() 调用 self.wrap()，后者使用其他生成器包装生成器。这些可能会通过修改后者生成的线，然后再次使用 (1, line) 生成它们，以及/或者通过在线之前或之后使用 (0, html) 生成其他 HTML 代码，从而在 _format_lines() 生成的 HTML 代码中添加一些 HTML 代码。源代码行和其他代码之间的区别使得可以多次包装生成器。

默认的 wrap() 实现添加了一个 <div> 和一个 <pre> 标签。

自定义 HtmlFormatter 子类可能如下所示

class CodeHtmlFormatter(HtmlFormatter):

    def wrap(self, source, *, include_div):
        return self._wrap_code(source)

    def _wrap_code(self, source):
        yield 0, '<code>'
        for i, t in source:
            if i == 1:
                # it's a line of formatted code
                t += '<br>'
            yield i, t
        yield 0, '</code>'

这将导致使用 <code> 标签包装格式化的行，其中源代码行使用 <br> 标签进行断开。

在调用 wrap() 之后， format() 方法还会在设置相应的选项时添加“行号”和/或“完整文档”包装器。然后，输出包装的生成器生成的全部 HTML。

class IRCFormatter

简短名称：

irc, IRC

文件名：

无

使用 IRC 颜色序列格式化标记

get_style_defs() 方法不执行任何特殊操作，因为不支持通用样式。

接受的选项

bg

根据终端的背景设置为 "light" 或 "dark"（默认："light"）。

colorscheme

一个字典，将标记类型映射到 (lightbg, darkbg) 颜色名称或 None（默认：None = 使用内置颜色方案）。

linenos

设置为 True 表示在输出中包含行号（默认：False = 无行号）。

class ImageFormatter

简短名称：

img, IMG, png

文件名：

*.png

从源代码创建 PNG 图像。这使用 Python Imaging Library 从源代码生成像素图。

在版本 0.10 中添加。

接受的附加选项

image_format

要输出到的 PIL 识别的图像格式，包括

• “PNG”（默认）

• “JPEG”

• “BMP”

• “GIF”

line_pad

每行文本之间的额外间距（以像素为单位）。

默认：2

font_name

要使用的字体名称，作为其他字体（例如粗体和斜体字体）生成的基准字体。这实际上应该是一种等宽字体才能看起来正常。如果指定了文件名或类文件对象，则用户必须提供字体的不同样式。

默认：Windows 上的“Courier New”，Mac OS 上的“Menlo”和

*nix 上的“DejaVu Sans Mono”

font_size

要使用的字体大小（以磅为单位）。

默认：14

image_pad

要用于生成图像每个边缘的填充（以像素为单位）。

默认：10

line_numbers

是否应显示行号：True/False

默认：True

line_number_start

第一行的行号。

默认：1

line_number_step

打印行号时使用的步长。

默认：1

line_number_bg

行号栏的背景颜色（以“#123456”格式表示），或 None 以使用样式背景颜色。

默认："#eed"

line_number_fg

行号的文本颜色（以“#123456”格式表示）。

默认："#886"

line_number_chars

行号边距中允许的行号列数。

默认：2

line_number_bold

行号是否为粗体：True/False

默认：False

line_number_italic

行号是否为斜体：True/False

默认：False

line_number_separator

行号区域和源代码区域之间是否绘制一条线：True/False

默认：True

line_number_pad

行号边距和源代码区域之间的水平填充（以像素为单位）。

默认：6

hl_lines

指定要突出显示的行列表。

在版本 1.2 中添加。

默认：空列表

hl_color

指定突出显示行的颜色。

在版本 1.2 中添加。

默认：选定样式的突出显示颜色

class JpgImageFormatter

简短名称：

jpg, jpeg

文件名：

*.jpg

从源代码创建 JPEG 图像。这使用 Python Imaging Library 从源代码生成像素图。

在版本 1.0 中添加。

class LatexFormatter

简短名称：

latex, tex

文件名：

*.tex

将标记格式化为 LaTeX 代码。这需要 fancyvrb 和 color 标准包。

如果没有 full 选项，代码将格式化为一个 Verbatim 环境，如下所示

\begin{Verbatim}[commandchars=\\\{\}]
\PY{k}{def }\PY{n+nf}{foo}(\PY{n}{bar}):
    \PY{k}{pass}
\end{Verbatim}

可以使用 nowrap 选项禁用包装。

此处使用的特殊命令（\PY）以及它所需的所有其他宏都是由 get_style_defs 方法输出的。

使用 full 选项，将输出完整的 LaTeX 文档，包括前言中的命令定义。

LatexFormatter 的 get_style_defs() 方法返回一个字符串，其中包含在 Verbatim 环境内定义的宏所需的 \def 命令。

接受的附加选项

nowrap

如果设置为 True，则根本不包装标记，甚至不在 \begin{Verbatim} 环境内包装。这将禁用大多数其他选项（默认：False）。

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。

full

告诉格式化程序输出“完整”文档，即一个完整的自包含文档（默认值：False）。

title

如果 full 为 true，则用于为文档添加标题的标题（默认值：''）。

docclass

如果启用了 full 选项，则这是要使用的文档类（默认：'article'）。

preamble

如果启用了full选项，则可以进一步添加前导命令，例如 \usepackage（默认值：''）。

linenos

如果设置为 True，则输出行号（默认值：False）。

linenostart

第一行的行号（默认：1）。

linenostep

如果设置为数字 n > 1，则只打印每隔 n 个行号。

verboptions

传递给 Verbatim 环境的附加选项（有关可能的值，请参阅 *fancyvrb* 文档）（默认值：''）。

commandprefix

用于生成彩色输出的 LaTeX 命令使用此前缀和一些字母构建（默认值：'PY'）。

在版本 0.7 中添加。

版本 0.10 中的更改： 默认值现在是 'PY' 而不是 'C'。

texcomments

如果设置为 True，则启用 LaTeX 注释行。也就是说，注释标记中的 LaTex 标记不会转义，以便 LaTeX 可以渲染它（默认值：False）。

在版本 1.2 中添加。

mathescape

如果设置为 True，则在注释中启用 LaTeX 数学模式转义。也就是说，注释中的 '$...$' 将触发数学模式（默认值：False）。

在版本 1.2 中添加。

escapeinside

如果设置为长度为 2 的字符串，则启用转义到 LaTeX。用这两个字符分隔的文本将被读取为 LaTeX 代码并相应地排版。它对字符串文字无效。如果设置了 texcomments 或 mathescape，它对注释无效。（默认值：''）。

在版本 2.0 中添加。

envname

允许您选择一个替代环境名称来替换 Verbatim。替代环境仍然必须支持 Verbatim 的选项语法。（默认值：'Verbatim'）。

在版本 2.0 中添加。

class NullFormatter

简短名称：

text, null

文件名：

*.txt

不进行任何格式化地输出文本。

class PangoMarkupFormatter

简短名称：

pango, pangomarkup

文件名：

无

将标记格式化为 Pango 标记代码。然后可以将其渲染为 SVG。

在版本 2.9 中添加。

class RawTokenFormatter

简短名称：

raw, tokens

文件名：

*.raw

将标记格式化为用于存储标记流的原始表示形式。

格式为 tokentype<TAB>repr(tokenstring)\n。输出以后可以使用 RawTokenLexer 转换为标记流，如 lexer 列表 中所述。

仅接受两个选项

compress

如果设置为 'gz' 或 'bz2'，则在编码后使用给定的压缩算法压缩输出（默认值：''）。

error_color

如果设置为颜色名称，则使用该颜色突出显示错误标记。如果设置但没有值，则默认为 'red'。

在版本 0.11 中添加。

class RtfFormatter

简短名称：

rtf

文件名：

*.rtf

将标记格式化为 RTF 标记。此格式化程序会自动输出包含颜色信息和其他有用内容的完整 RTF 文档。非常适合复制粘贴到 Microsoft(R) Word(R) 文档中。

请注意，encoding 和 outencoding 选项将被忽略。RTF 格式是本地的 ASCII，但由于使用了转义序列，因此可以正确处理 Unicode 字符。

在版本 0.6 中添加。

接受的附加选项

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。

fontface

使用的字体系列，例如 Bitstream Vera Sans。默认为一些通用字体，该字体应该是固定宽度的。

fontsize

使用的字体大小。大小以半点为单位指定。默认值为 24 半点，对应于 12 号字体。

在版本 2.0 中添加。

linenos

打开行号（默认值：False）。

在版本 2.18 中添加。

lineno_fontsize

行号的字体大小。大小以半点为单位指定（默认值：fontsize）。

在版本 2.18 中添加。

lineno_padding

(内联) 行号与源代码之间的空格数（默认值：2）。

在版本 2.18 中添加。

linenostart

第一行的行号（默认：1）。

在版本 2.18 中添加。

linenostep

如果设置为数字 n > 1，则只打印每隔 n 个行号。

在版本 2.18 中添加。

lineno_color

行号的颜色，以十六进制三元组指定，例如 '5e5e5e'。如果样式的行号颜色是十六进制三元组，则默认为该颜色，否则为 ANSI 亮黑色。

在版本 2.18 中添加。

hl_lines

指定要突出显示的行的列表，以空格分隔的行号表示，例如 '3 7 8'。除非设置了 hl_linenostart，否则行号相对于输入（即第一行为第 1 行）。

在版本 2.18 中添加。

hl_color

用于突出显示 hl_lines 中指定的行的颜色，以十六进制三元组指定（默认值：样式的 highlight_color）。

在版本 2.18 中添加。

hl_linenostart

如果设置为 True，则 hl_lines 中的行号相对于 linenostart 指定（默认值 False）。

在版本 2.18 中添加。

class SvgFormatter

简短名称：

svg

文件名：

*.svg

将标记格式化为 SVG 图形文件。此格式化程序仍处于实验阶段。每行代码都是一个 <text> 元素，其中包含明确的 x 和 y 坐标，这些坐标包含具有单个标记样式的 <tspan> 元素。

默认情况下，此格式化程序会输出完整的 SVG 文档，包括文档类型声明和 <svg> 根元素。

在版本 0.9 中添加。

接受的附加选项

nowrap

不要将 SVG <text> 元素包装在 <svg><g> 元素中，也不要添加 XML 声明和文档类型。如果为真，则会忽略 fontfamily 和 fontsize 选项。默认为 False。

fontfamily

要赋予包装的 <g> 元素的 font-family 属性的值，默认为 "monospace"。

fontsize

要赋予包装的 <g> 元素的 font-size 属性的值，默认为 "14px"。

linenos

如果为 True，则添加行号（默认值：False）。

linenostart

第一行的行号（默认：1）。

linenostep

如果设置为数字 n > 1，则只打印每隔 n 个行号。

linenowidth

分配给行号的最大宽度（默认值：3*ystep，足以容纳最多 4 位数字的行号。对于较长的代码块，请增加宽度）。

xoffset

X 方向的起始偏移量，默认为 0。

yoffset

Y 方向的起始偏移量，如果字体大小以像素为单位给出，则默认为字体大小，否则默认为 20。（这是必要的，因为文本坐标指的是文本基线，而不是顶部边缘）。

ystep

为后续每行添加的 Y 坐标偏移量。这应该大致等于文本大小加 5。如果文本大小以像素为单位给出，则默认为该值，否则默认为 25。

spacehack

将源代码中的空格转换为  ，即不间断空格。SVG 提供了 xml:space 属性来控制如何处理标签内的空格，理论上，preserve 值可用于保持所有空格不变。但是，许多当前的 SVG 浏览器不遵守该规则，因此提供了此选项作为解决方法，并且默认为 True。

class Terminal256Formatter

简短名称：

terminal256, console256, 256

文件名：

无

使用 ANSI 颜色序列格式化标记，用于在 256 色终端或控制台中输出。与 TerminalFormatter 一样，颜色序列在换行符处终止，以便分页输出正常工作。

格式化程序从 style 选项定义的样式中获取颜色，并将它们转换为最接近的 ANSI 256 色转义序列。样式中的粗体和下划线属性将保留（并显示）。

在版本 0.9 中添加。

版本 2.2 中的更改： 如果使用的样式以 #ansi* 的形式定义前景色，则 Terminal256Formatter 会将它们映射到非扩展前景色。有关更多信息，请参阅 终端样式。

版本 2.4 中的更改： ANSI 颜色名称已更新为更易于理解的名称，并与其他项目和终端的颜色名称保持一致。有关更多信息，请参阅 此表。

接受的选项

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。

linenos

设置为 True 表示在终端输出中也显示行号（默认值：False = 无行号）。

class TerminalFormatter

简短名称：

terminal, console

文件名：

无

使用 ANSI 颜色序列格式化标记，用于在文本控制台中输出。颜色序列在换行符处终止，以便分页输出正常工作。

get_style_defs() 方法不执行任何特殊操作，因为不支持通用样式。

接受的选项

bg

根据终端的背景设置为 "light" 或 "dark"（默认："light"）。

colorscheme

一个字典，将标记类型映射到 (lightbg, darkbg) 颜色名称或 None（默认：None = 使用内置颜色方案）。

linenos

设置为 True 表示在终端输出中也显示行号（默认值：False = 无行号）。

class TerminalTrueColorFormatter

简短名称：

terminal16m, console16m, 16m

文件名：

无

使用 ANSI 颜色序列格式化标记，用于在真彩色终端或控制台中输出。与 TerminalFormatter 一样，颜色序列在换行符处终止，以便分页输出正常工作。

在版本 2.1 中添加。

接受的选项

style

要使用的样式，可以是字符串或 Style 子类（默认值：'default'）。

class TestcaseFormatter

简短名称：

testcase

文件名：

无

将标记格式化为适合新测试用例的格式。

在版本 2.0 中添加。