关于Python pygments库的简单介绍

Python库pygments学习笔记

简单介绍

pygments是一个将代码格式化的Python库，可以将代码格式化为html代码、图片、rtf文件等多种格式。
官网：pygments.org
PyPI：pygments

安装

pip install pygments

如果警告pip版本过低需要升级，那么只需要这样做

python -m pip install -U pip

简单使用

一下内容摘取自官网，并在此基础上稍作改动：

from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

code = 'print "Hello World"'
print(highlight(code, lexer=PythonLexer(), formatter=HtmlFormatter()))

并且会看到像这样的输出：

<div class="highlight">
<pre><span class="k">print</span> <span class="s">"Hello World"</span></pre>
</div>

详解：
highlight->用于生成格式化之后的代码，生成的格式由后面的formatter决定
lexer->译做词法分析程序，用于判断当前输入的代码属于哪种编程语言（C、C++、Python、Java等）
formatter->格式化选项，这里是格式化为html代码，也可以格式化为.png、.jpg格式的图片等

自动推断语言

使用PythonLexer等lexer时我们还需要手动指定需要分析的编程语言，但是有的时候我们无法提前知道需要格式化的语言是什么，这个时候就需要使用pygments提供的语言猜测功能了。
官网说明

1. guess_lexer(_text, **options)：根据提供的代码进行分析。官方给出的注释如下：
   Guess a lexer by strong distinctions in the text (eg, shebang).，通过文本中显著的区别（例如：事件）选择合适的此法分析程序。
   shebang：事件，但是具体什么意思我也不清楚
2. guess_lexer_for_filename(_fn, _text, **options)第一个是文件名，第二个是文件内的代码。

    """
    Lookup all lexers that handle those filenames primary (``filenames``)
    or secondary (``alias_filenames``). Then run a text analysis for those
    lexers and choose the best result.

    usage::

        >>> from pygments.lexers import guess_lexer_for_filename
        >>> guess_lexer_for_filename('hello.html', '<%= @foo %>')
        <pygments.lexers.templates.RhtmlLexer object at 0xb7d2f32c>
        >>> guess_lexer_for_filename('hello.html', '<h1>{{ title|e }}</h1>')
        <pygments.lexers.templates.HtmlDjangoLexer object at 0xb7d2f2ac>
        >>> guess_lexer_for_filename('style.css', 'a { color: <?= $link ?> }')
        <pygments.lexers.templates.CssPhpLexer object at 0xb7ba518c>
    """

根据给出的注释，我们可以发现这个函数在进行分析之前会根据文件名或者文件别名提前列举出一个可能的范围，之后再根据这个范围进行精确的搜索。就像文中的实例一样，Django模板，R语言模板和普通的html文件的后缀都是.html，所以这个时候就需要进行精确区分。
下面我们以上面注释中第一个例子为例动手试验一把：
代码：<%= @foo %>

# test 1
from pygments.lexers import guess_lexer

print(guess_lexer("<%= @foo %>"))

>>> <pygments.lexers.ErbLexer>

# test 2
from pygments.lexers import guess_lexer_for_filename

print(guess_lexer_for_filename("test.html", "<%= @foo %>"))

>>> <pygments.lexers.RhtmlLexer>

可以看到，如果不指定文件名的话，可能会出现一些未知的lexer被筛选出来，这就有可能造成程序中的错误，所以使用guess_lexer_for_filename函数更多的是起到保险的作用。

formatters

pygments库中提供了众多的formatter，可以转化成多种形式的输出形式，可以是（富）文本，可以是图片，也可以直接输出在终端上，下面挑选几个进行介绍。
官网说明

• common
  所有的formatter都会有的参数

  • encoding：指定输入的代码的编码格式
  • style：指定代码高亮的风格，可以在pygments.styles包里面找到，常用的风格有：
    • default
    • vs
    • vim
    • emacs
    • xcode
    • colorful
    • fruity
    • …
  • outencoding：这个和命令行的操作有关，这里暂时不会使用到

• HtmlFormatter
  用于将一段代码转换成html代码，下面是官网上面的快速指导：

  <div class="highlight">
  <pre><span class="k">print</span> <span class="s">&quot;Hello World&quot;</span></pre>
  </div>
  

  这里讲一下几个常用的参数：

  • full/bool：如果指定为True，那么不必为html另外生成css文件，所有的样式都会写在html文件里面

  • style/str：指定代码高亮风格，前文已经有所介绍，因此不再赘述

  • noclasses/bool：如果设置为True，那么所有的样式不再以类的形式出现，而是使用内联样式

  • linenos/str：如果设置成table，那么生成的html最外面不是div标签，而是table标签，将行号和代码分开；如果设置成inline，那么行号就会和代码放在一起

    优点是可以生成html代码之后自己手动处理html代码，对其进行更进一步的操作，比如写入到Word文档中。缺点是没法指定字体的大小，如果要修改，只能修改生成的html文件的代码。

• ImageFormatter
  用于将代码格式化为图片，需要PIL或者pillow作为图片处理的库，常用的参数有：

  • image_format/str：生成的图片格式，默认为"PNG"，也可以是"JPEG"/“BMP”/“GIF”
  • font_name/str：指定代码的字体
  • font_size/int：指定代码的字号，默认为14
  • line_number_chars/int：指定代码行号占几个字符，防止留给行号的空间不够，默认为2

除了上面列举的两个，pygments还提供了一些别的formatter，比如RtfFormatter，SvgFormatter，TerminalFormatter，BmpImageFormatter等，可以自行到官网查看

其他

pygments还提供了扩展的功能，如果你想自定义formatter/lexer/style，那么可以参考官网上面的说明进行尝试。除了Python之外，pygments还提供了Java（基于JPython）的使用方法，POM文件如下：

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>example</artifactId>
  <version>1.0-SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>org.python</groupId>
      <artifactId>jython-standalone</artifactId>
      <version>2.5.3</version>
    </dependency>
    <dependency>
      <groupId>org.pygments</groupId>
      <artifactId>pygments</artifactId>
      <version>1.5</version>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>

PythonInterpreter interpreter = new PythonInterpreter();

// Set a variable with the content you want to work with
interpreter.set("code", code);

// Simple use Pygments as you would in Python
interpreter.exec("from pygments import highlight\n"
    + "from pygments.lexers import PythonLexer\n"
    + "from pygments.formatters import HtmlFormatter\n"
    + "\nresult = highlight(code, PythonLexer(), HtmlFormatter())");

// Get the result that has been set in a variable
System.out.println(interpreter.get("result", String.class));