利用可能なフォーマッター

《初回公開：2022/03/26 , 最終更新：未》

原文は

Available formatters - Pygments

旧バージョンの記事は

Pygments - formatterコンポーネント - 愚鈍人

【　目次　】

利用可能なフォーマッター
- Formatterクラス
  - HTMLフォーマッタのサブクラス化

このページには、すべての組み込みフォーマッターが一覧表示されます。

encoding

指定する場合は、エンコード名（ "utf-8"など）にする必要があります。
これは、トークン文字列（Unicode文字列）を出力のバイト文字列に変換するために使用されます（デフォルト：なし）。
また、完全なオプションが指定されている場合は、ドキュメント形式に適したエンコーディング宣言で記述されます（たとえば、HTMLのcontent-typeディレクティブまたはLaTeXのinputencパッケージの呼び出し）。

これが ""またはNoneの場合、Unicode文字列が出力ファイルに書き込まれます。
これはほとんどのfile-like objectではサポートされていません。
たとえば、pygments.highlight()は、outfile引数なしで呼び出された場合にUnicode文字列を返し、write()にUnicode引数をサポートするStringIO.StringIOオブジェクトを使用するため、エンコーディングがNoneに設定されたフォーマッタを返します。
通常のファイルオブジェクトを使用しても機能しません。

バージョン0.6の新機能。

outencoding

コマンドラインからPygmentsを使用する場合、指定されたエンコードオプションはすべてレクサーとフォーマッターに渡されます。
これは、たとえば、入力エンコーディングを「guess」に設定する場合など、望ましくない場合があります。
したがって、指定された場合にフォーマッタのencodingをオーバーライドするoutencodingが導入されました。
バージョン0.7の新機能。

Formatterクラス

これらのクラスはすべて、pygments.formattersからインポートできます。

愚鈍人の独り言

私にとって重要そうなのはHtmlFormatterだけなので、そこの部分のみを抜粋。
他のFormatterクラスにつては原文を参照

class HtmlFormatter

Short names: html
Filenames: .html, .htm

トークンを、<div>タグでラップされた<div>タグ内のHTML4<span>タグとしてフォーマットします。
<div>のCSSクラスは、cssclassオプションで設定できます。
linenosオプションが "table"に設定されている場合、<pre>はさらに1つの行と2つのセル（1つは行番号を含み、もう1つはコードを含む）を持つ<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>

(明確さを向上させるために空白が追加されました。)
nowrapオプションを使用して、ラッピングを無効にすることができます。
行のリストは、hl_linesオプションを使用して指定し、これらの行を強調表示することができます（Pygments 0.11以降）。
fullオプションを使用すると、<style>タグ内のスタイル定義を含む、完全なHTML 4ドキュメントが出力されます。または、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>タグ内であっても、トークンをまったくラップしないでください。
これにより、他のほとんどのオプションが無効になります（デフォルト：False）。
full: 「完全な」ドキュメント、つまり完全な自己完結型ドキュメントを出力するようにフォーマッタに指示します（デフォルト：False）。
title: fullがtrueの場合、ドキュメントのキャプションに使用する必要のあるタイトル（デフォルト： ''）。
style: 使用するスタイルは、文字列またはスタイルサブクラス（デフォルト： 'default'）にすることができます。
cssfileおよびnoclobber_cssfileオプションが指定されていて、cssfileで指定されたファイルが存在する場合、このオプションは効果がありません。
noclasses: ラッピングしている<div>タグのCSSクラス（デフォルト： 'highlight'）。
このオプションを設定すると、get_style_defs()のデフォルトセレクターはこのクラスになります。
バージョン0.9の新機能：「table」の行番号を選択すると、ラッピングテーブルにはこの文字列と「table」のCSSクラスが含まれるため、デフォルトは「highlighttable」になります。
cssstyles: ラッピングしている<div>タグのインラインCSSスタイル（デフォルト： ''）。
prestyles: <pre>タグのインラインCSSスタイル（デフォルト： ''）。
バージョン0.11の新機能。
cssfile: fullオプションがtrueで、このオプションが指定されている場合は、外部ファイルの名前でなければなりません。
ファイル名に絶対パスが含まれていない場合、ファイルのパスは、メイン出力ファイルのパスが見つかった場合は、メイン出力ファイルのパスを基準にしたものと見なされます。
スタイルシートがそのあとHTMLファイルではなくこのファイルに書き込まれます。
バージョン0.6の新機能。
noclobber_cssfile: cssfileが指定され、指定されたファイルが存在する場合、cssファイルは上書きされません。
これにより、ユーザー指定のcssファイルと組み合わせてfullオプションを使用できます。
デフォルトはFalseです。
バージョン0.11の新機能。
linenos: 'table'に設定すると、行番号を2つのセルを持つテーブルとして出力します。1つは行番号を含み、もう1つはコード全体を含みます。
これはコピーアンドペーストに適していますが、一部のブラウザまたはフォントで配置の問題が発生する可能性があります。
'inline'に設定すると、行番号はコードを含む<pre>タグに統合されます（この設定はPygments 0.8で新しく追加されました）。
Pygments 0.7以前との互換性のために、「inline」を除くすべてのtrue値は「table」と同じことを意味します（特に、それはTrueも意味します）。
デフォルト値はFalseです。これは、行番号がまったくないことを意味します。

Note

デフォルトの（「table」）行番号メカニズムでは、囲んでいる<pre>タグに明示的な行の高さのCSSプロパティを指定しない限り、Internet Explorerで行番号とコードの行の高さを変えることができます（行でデフォルトの行間隔を取得します） -高さ：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>タグ内の行を分割するのに十分ですが、たとえば、 HTMLの改行を取得するには、「<br>」に設定します。
バージョン0.7の新機能。
lineanchors: 空でない文字列に設定されている場合、例： fooの場合、フォーマッタは各出力行をfoo-linenumberのID（および名前）を持つアンカータグでラップします。
これにより、特定の行に簡単にリンクできます。
バージョン0.9の新機能。
linespans: 空でない文字列に設定されている場合、例： fooの場合、フォーマッタは各出力行をfoo-linenumberのIDを持つspanタグでラップします。
これにより、javascriptを介して行に簡単にアクセスできます。
バージョン1.6の新機能。
anchorlinenos: Trueに設定すると、行番号が<a>タグでラップされます。 linenosおよびlineanchorsと組み合わせて使用されます。
tagsfile: ctagsファイルのパスに設定されている場合は、名前をその定義にリンクするアンカータグでラップします。
lineanchorsを使用する必要があり、tagsファイルで行番号を指定する必要があります（ctagsの-nオプションを参照）。
バージョン1.6の新機能。
tagurlformat: ctags定義へのリンクを生成するために使用される文字列フォーマットパターン。
使用可能な変数は、%(path)s, %(fname)sおよび%(fext)sです。
デフォルトは空の文字列で、結果は#prefix-numberリンクのみになります。
バージョン1.6の新機能。
filename: <pre>ブロックをレンダリングするときに、たとえばソースコードを表示する場合に、ファイル名を生成するために使用される文字列。
linenosが 'table'に設定されている場合、ファイル名は、両方の列にまたがる単一の<th>を含む最初の行にレンダリングされます。
バージョン2.1の新機能。
wrapcode: HTML5仕様で推奨されているように、<code>を使用して<pre>ブロック内にコードをラップします。
バージョン2.4の新機能。
debug_token_types: トークンの名前を示すすべてのトークン<span>タグにタイトル属性を追加します。
バージョン2.10の新機能。

HTMLフォーマッタのサブクラス化

HTMLフォーマッターは、簡単にサブクラス化できるように構築されているため、出力HTMLコードをカスタマイズできます。
format（）メソッドはself._format_lines（）を呼び出します。
これは、（1、line）のタプルを生成するジェネレーターを返します。1は、その行がフォーマットされたソースコードの行であることを示します。
nowrapオプションが設定されている場合、ジェネレーターが繰り返され、結果のHTMLが出力されます。
それ以外の場合、format()はself.wrap()を呼び出し、ジェネレーターを他のジェネレーターでラップします。

これらは、_format_lines（）によって生成された行を変更することによって、_format_lines（）によって生成されたものにいくつかのHTMLコードを追加する可能性があります。
次に、（1、line）を使用して、または行の前後に（0、html）を使用して他のHTMLコードを生成することにより、それらを再度生成します。
ソース行と他のコードを区別することで、ジェネレーターを複数回ラップすることができます。
デフォルトのwrap()実装は、<div>タグと<pre>タグを追加します。

カスタムHtmlFormatterサブクラスは次のようになります。

class CodeHtmlFormatter(HtmlFormatter):

    def wrap(self, source, outfile):
        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が出力されます。