简介和快速入门¶
欢迎来到 Pygments！本文档解释了基本概念和术语，并给出了一些如何使用该库的例子。
架构¶
有四种类型的组件一起工作，高亮一段代码：
lexer 将源文件分割成形符，即源文件的片段，其形符类型决定了文本在语义上代表什么（例如，关键字、字符串或注释）。Pygments 支持的每种语言或形符格式都有一个 lexer。
形符流可以通过 filters，这些过滤器通常会修改形符类型或文本片段，例如将所有关键词大写。
然后，一个 formatter 接收形符流，并将其写入一个输出文件，格式为 HTML、LaTeX 或 RTF。
在编写输出时，一个 style 决定了如何高亮所有不同的标记类型。它将它们映射到诸如 “red and bold” 等属性
示例¶
下面是一个高亮 Python 代码的小例子：
from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter
code = 'print "Hello World"'
print(highlight(code, PythonLexer(), HtmlFormatter()))
它的打印结果是这样的：
<div class="highlight">
<pre><span class="k">print</span> <span class="s">"Hello World"</span></pre>
</div>
正如你所看到的，Pygments 使用 CSS 类（默认情况下，但你可以改变）而不是内联样式，以避免重复输出多余的样式信息。一个包含所有可能在输出中使用的 CSS 类的 CSS 样式表可以通过以下方式产生：
print(HtmlFormatter().get_style_defs('.highlight'))
get_style_defs() 的参数被用作额外的 CSS 选择器：输出可能看起来像这样：
.highlight .k { color: #AA22FF; font-weight: bold }
.highlight .s { color: #BB4444 }
...
选项¶
highlight() 函数支持第四个参数，称为 outfile，如果给出的话，它必须是一个文件对象。然后，格式化的输出将被写入这个文件，而不是作为一个字符串返回。
Lexers 和 formatters 都支持选项。它们作为关键字参数被提供给类或查找方法：
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import HtmlFormatter
lexer = get_lexer_by_name("python", stripall=True)
formatter = HtmlFormatter(linenos=True, cssclass="source")
result = highlight(code, lexer, formatter)
这使得 lexer 从输入中去除所有前导和尾部的空白（stripall 选项），让 formatter 输出行号（linenos 选项），并将包装的 <div> 的类设置为 source （而不是 highlight）。
重要的选项包括：
- encoding用于 lexers 和 formatters
Since Pygments uses Unicode strings internally, this determines which encoding will be used to convert to or from byte strings.
- style用于 formatters
编写输出时要使用的样式名称。
关于内建 lexer 和 formatter 及其选项的概述，请访问 lexer 和 formatters 列表。
关于过滤器的文档，见 this page。
lexer 和 formatter 查询¶
如果你想通过别名或文件名来查询一个内置的 lexer，你可以使用以下方法之一：
>>> from pygments.lexers import (get_lexer_by_name,
... get_lexer_for_filename, get_lexer_for_mimetype)
>>> get_lexer_by_name('python')
<pygments.lexers.PythonLexer>
>>> get_lexer_for_filename('spam.rb')
<pygments.lexers.RubyLexer>
>>> get_lexer_for_mimetype('text/x-perl')
<pygments.lexers.PerlLexer>
所有这些函数都接受关键字参数；它们将作为选项传递给 lexer。
类似的 API 可用于 formatter：使用来自 pygments.formatters 模块的 get_formatter_by_name() 和 get_formatter_for_filename()，用于此目的。
猜测词库¶
如果你不知道文件的内容，或者你想高亮一个扩展名不明确的文件，如 .html （可能包含纯 HTML 或一些模板标签），请使用这些函数：
>>> from pygments.lexers import guess_lexer, guess_lexer_for_filename
>>> guess_lexer('#!/usr/bin/python\nprint "Hello World!"')
<pygments.lexers.PythonLexer>
>>> guess_lexer_for_filename('test.py', 'print "Hello World!"')
<pygments.lexers.PythonLexer>
guess_lexer() 将给定的内容传递给词库类的 analyse_text() 方法，并返回其返回最高数字的那个。
所有的词库都有两个不同的文件名模式列表：主要的和次要的。get_lexer_for_filename() 函数只使用主列表，其条目在所有词库中应该是唯一的。guess_lexer_for_filename()，然而，将首先循环浏览所有词库，如果文件名匹配，则查看主和次的文件名模式。如果只有一个词库匹配，它将被返回，否则 guess_lexer() 的猜测机制将与匹配的词库一起使用。
像往常一样，这些函数的关键字参数被作为选项提供给创建的词库。
命令行用法¶
你可以从命令行使用 Pygments，使用 pygmentize 脚本
$ pygmentize test.py
将使用 ANSI 转义序列（又称终端颜色）突出显示 Python 文件 test.py，并将结果打印到标准输出。
要输出HTML，使用 -f 选项
$ pygmentize -f html -o test.html test.py
将 test.py 的 HTML 高亮版本写到 test.html 文件中。注意，它将只是一个 HTML 片段，如果你想要一个完整的 HTML 文档，请使用 “full” 选项
$ pygmentize -f html -O full -o test.html test.py
这将产生一个包含样式表的完整 HTML 文档。
可以用 -O style=<name> 来选择一种风格。
如果你需要一个使用 Pygments CSS 类的现有 HTML 文件的样式表，可以用
$ pygmentize -S default -f html > style.css
其中 default 是风格名称。
更多的选项和技巧可以在 命令行参考 中找到。