イントロダクションとクイックスタート
《 初回公開：2022/03/26 , 最終更新：未 》
原文は
旧バージョンの記事は
【 目次 】
Pygmentsへようこそ！ このドキュメントでは、基本的な概念と用語について説明し、ライブラリの使用方法の例をいくつか示します。
アーキテクチャ
コードの一部を強調表示するために連携して動作するコンポーネントには、次の4つのタイプがあります。
- レクサーは、ソースをトークンに分割します。
トークンは、テキストが意味的に表すもの（キーワード、文字列、コメントなど）を決定するトークンタイプを持つソースのフラグメントです。
Pygmentsがサポートするすべての言語またはマークアップ形式に対応するレクサーがあります。 - トークンストリームは、通常、トークンタイプまたはテキストフラグメントを変更するフィルターを介してパイプすることができます。
すべてのキーワードを大文字にします。 - 次に、フォーマッタはトークンストリームを取得し、HTML、LaTeX、RTFなどの形式で出力ファイルに書き込みます。
- 出力の書き込み中に、スタイルによって、すべての異なるトークンタイプを強調表示する方法が決まります。
それらを「赤と太字」などの属性にマップします。
例
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 }
...
Options
Highlight()関数は、outfileと呼ばれる4番目の引数をサポートします。指定されている場合は、ファイルオブジェクトである必要があります。
フォーマットされた出力は、文字列として返されるのではなく、このファイルに書き込まれます。
レクサーとフォーマッターはどちらもオプションをサポートしています。
それらは、クラスまたはルックアップメソッドのいずれかにキーワード引数として与えられます。
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)
これにより、レクサーは入力からすべての先頭と末尾の空白を削除し（stripallオプション）、フォーマッターは行番号を出力し（linenosオプション）、ラッピングする<div>のクラスを（highlightではなく）sourceに設定します。
重要なオプションは次のとおりです。
- encoding: レクサーおよびフォーマッター用
- Pygmentsは内部でUnicode文字列を使用するため、これにより、バイト文字列との間で変換するために使用されるエンコーディングが決まります。
- style: フォーマッター用
- 出力を書き込むときに使用するスタイルの名前。
組み込みのレクサーとフォーマッターおよびそれらのオプションの概要については、レクサーとフォーマッターのリストにアクセスしてください。
フィルタに関するドキュメントについては、このページを参照してください。
レクサーとフォーマッターのルックアップ
組み込みのレクサーをエイリアスまたはファイル名で検索する場合は、次のいずれかの方法を使用できます。
>>> 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>
これらの関数はすべてキーワード引数を受け入れます。 それらはオプションとしてレクサーに渡されます。
フォーマッターにも同様のAPIを使用できます。この目的には、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()メソッドに渡し、最大の数値を返すものを返します。
すべてのレクサーには、プライマリとセカンダリの2つの異なるファイル名パターンリストがあります。
get_lexer_for_filename()関数は、プライマリリストのみを使用します。プライマリリストのエントリは、すべてのレクサーの中で一意であると想定されています。
ただし、guess_lexer_for_filename()は、最初にすべてのレクサーをループし、ファイル名が一致する場合はプライマリおよびセカンダリのファイル名パターンを調べます。
一致するレクサーが1つだけの場合は返されます。一致しない場合は、guess_lexer()の推測メカニズムが一致するレクサーで使用されます。
いつものように、これらの関数へのキーワード引数は、オプションとして作成されたレクサーに与えられます。
コマンドラインでの使い方
pygmentizeスクリプトを使用して、コマンドラインからPygmentsを使用できます。
$ pygmentize test.py
ANSIエスケープシーケンス（別名ターミナルカラー）を使用してPythonファイルtest.pyを強調表示し、結果を標準出力に出力します。 HTMLを出力するには、-fオプションを使用します。
$ pygmentize -f html -o test.html test.py
HTMLで強調表示されたバージョンのtest.pyをファイルtest.htmlに書き込みます。
これはHTMLのスニペットにすぎないことに注意してください。完全なHTMLドキュメントが必要な場合は、「完全な」オプションを使用してください。
$ 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はスタイル名です。
その他のオプションとトリックは、コマンドラインリファレンスにあります。