PygmentsのフルAPI

このページでは、PygmentsのAPIについて説明します。

高レベルAPI

pygmentsモジュールの関数

pygments.lex(code, lexer)

codeをlexer（Lexerインスタンスである必要があります）で字句解析し、トークンのイテラブルを返します。現在、これはlexer.get_tokens()を呼び出すだけです。

pygments.format(tokens, formatter, outfile=None)

tokens（トークンのイテラブル）をフォーマッタformatter（Formatterインスタンス）でフォーマットします。

outfileが指定され、有効なファイルオブジェクト（writeメソッドを持つオブジェクト）である場合、結果はそれに書き込まれ、それ以外の場合は文字列として返されます。

pygments.highlight(code, lexer, formatter, outfile=None)

これは、最も高レベルの強調表示関数です。これは、lexとformatを1つの関数に結合します。

pygments.lexersの関数

pygments.lexers.get_lexer_by_name(_alias, **options)

エイリアスリストにaliasを持つLexerサブクラスのインスタンスを返します。字句解析器には、インスタンス化時にoptionsが与えられます。

そのエイリアスを持つ字句解析器が見つからない場合は、pygments.util.ClassNotFoundを発生させます。

pygments.lexers.get_lexer_for_filename(_fn, code=None, **options)

ファイル名の字句解析器を取得します。

fnに一致するファイル名パターンを持つLexerサブクラスインスタンスを返します。字句解析器には、インスタンス化時にoptionsが与えられます。

そのファイル名の字句解析器が見つからない場合は、pygments.util.ClassNotFoundを発生させます。

複数の字句解析器がファイル名パターンに一致する場合、analyse_text()メソッドを使用して、より適切なものを判断します。

pygments.lexers.get_lexer_for_mimetype(_mime, **options)

mimetypeリストにmimeを持つLexerサブクラスのインスタンスを返します。字句解析器には、インスタンス化時にoptionsが与えられます。

そのmimetypeの字句解析器が見つからない場合は、pygments.util.ClassNotFoundを発生させます。

pygments.lexers.load_lexer_from_file(filename, lexername='CustomLexer', **options)

ファイルから字句解析器を読み込みます。

このメソッドは、現在の作業ディレクトリを基準とした場所にある、Lexerクラスを含むファイルを想定しています。デフォルトでは、Lexerの名前がCustomLexerであることを想定しています。この関数の2番目の引数として、独自のクラス名を指定できます。

このメソッドは入力ファイルに対してevalを実行するのと同等であるため、ユーザーは入力に非常に注意する必要があります。

Lexerのインポートに問題がある場合は、ClassNotFoundを発生させます。

バージョン2.2で追加されました。

pygments.lexers.guess_lexer(_text, **options)

textのテキストから推測されるLexerサブクラスのインスタンスを返します。そのため、既知のすべての字句解析器クラスのanalyse_text()メソッドがテキストを引数として呼び出され、最も高い値を返した字句解析器がインスタンス化されて返されます。

どの字句解析器もコンテンツを処理できると考えられない場合は、pygments.util.ClassNotFoundが発生します。

pygments.lexers.guess_lexer_for_filename(_fn, _text, **options)

guess_lexer()と同様ですが、filenamesまたはalias_filenamesにfilenameと一致するパターンを持つ字句解析器のみが考慮されます。

どの字句解析器もコンテンツを処理できると考えられない場合は、pygments.util.ClassNotFoundが発生します。

pygments.lexers.get_all_lexers(plugins=True)

すべての既知の字句解析器の(name, aliases, filenames, mimetypes)形式のタプルのジェネレータを返します。

pluginsがtrue（デフォルト）の場合、エントリポイントによって提供されるプラグイン字句解析器も返されます。それ以外の場合は、組み込みのもののみが考慮されます。

pygments.lexers.find_lexer_class_by_name(_alias)

エイリアスリストにaliasを持つLexerサブクラスを、インスタンス化せずに返します。

get_lexer_by_nameと同様ですが、クラスをインスタンス化しません。

そのエイリアスを持つ字句解析器が見つからない場合は、pygments.util.ClassNotFoundを発生させます。

バージョン2.2で追加されました。

pygments.lexers.find_lexer_class(name)

name引数で指定されたname属性を持つLexerサブクラスを返します。

pygments.formattersの関数

pygments.formatters.get_formatter_by_name(_alias, **options)

エイリアスリストに alias を持つ Formatter サブクラスのインスタンスを返します。フォーマッタには、インスタンス化時に options が与えられます。

そのエイリアスを持つフォーマッタが見つからない場合は、pygments.util.ClassNotFound が発生します。

pygments.formatters.get_formatter_for_filename(fn, **options)

fn に一致するファイル名パターンを持つ Formatter サブクラスのインスタンスを返します。フォーマッタには、インスタンス化時に options が与えられます。

そのファイル名のフォーマッタが見つからない場合は、pygments.util.ClassNotFound が発生します。

pygments.formatters.load_formatter_from_file(filename, formattername='CustomFormatter', **options)

現在のディレクトリを基準とした、指定されたファイルからロードされた Formatter サブクラスのインスタンスを返します。

ファイルには、formattername（デフォルトでは CustomFormatter）という名前の Formatter クラスが含まれている必要があります。このメソッドは入力ファイルに対して eval() を実行するのと同じであるため、ユーザーは入力に十分注意する必要があります。フォーマッタには、インスタンス化時に options が与えられます。

フォーマッタのロード中にエラーが発生した場合は、pygments.util.ClassNotFound が発生します。

バージョン2.2で追加されました。

pygments.styles の関数

pygments.styles.get_style_by_name(name)

短い名前でスタイルクラスを返します。組み込みスタイルの名前は、pygments.styles.STYLE_MAP にリストされています。

その名前のスタイルが見つからない場合は、pygments.util.ClassNotFound が発生します。

pygments.styles.get_all_styles()

組み込みとプラグインの両方の、名前によるすべてのスタイルのジェネレータを返します。

pygments.styles.STYLE_MAP = {'abap': 'abap::AbapStyle', 'algol': 'algol::AlgolStyle', 'algol_nu': 'algol_nu::Algol_NuStyle', 'arduino': 'arduino::ArduinoStyle', 'autumn': 'autumn::AutumnStyle', 'borland': 'borland::BorlandStyle', 'bw': 'bw::BlackWhiteStyle', 'coffee': 'coffee::CoffeeStyle', 'colorful': 'colorful::ColorfulStyle', 'default': 'default::DefaultStyle', 'dracula': 'dracula::DraculaStyle', 'emacs': 'emacs::EmacsStyle', 'friendly': 'friendly::FriendlyStyle', 'friendly_grayscale': 'friendly_grayscale::FriendlyGrayscaleStyle', 'fruity': 'fruity::FruityStyle', 'github-dark': 'gh_dark::GhDarkStyle', 'gruvbox-dark': 'gruvbox::GruvboxDarkStyle', 'gruvbox-light': 'gruvbox::GruvboxLightStyle', 'igor': 'igor::IgorStyle', 'inkpot': 'inkpot::InkPotStyle', 'lightbulb': 'lightbulb::LightbulbStyle', 'lilypond': 'lilypond::LilyPondStyle', 'lovelace': 'lovelace::LovelaceStyle', 'manni': 'manni::ManniStyle', 'material': 'material::MaterialStyle', 'monokai': 'monokai::MonokaiStyle', 'murphy': 'murphy::MurphyStyle', 'native': 'native::NativeStyle', 'nord': 'nord::NordStyle', 'nord-darker': 'nord::NordDarkerStyle', 'one-dark': 'onedark::OneDarkStyle', 'paraiso-dark': 'paraiso_dark::ParaisoDarkStyle', 'paraiso-light': 'paraiso_light::ParaisoLightStyle', 'pastie': 'pastie::PastieStyle', 'perldoc': 'perldoc::PerldocStyle', 'rainbow_dash': 'rainbow_dash::RainbowDashStyle', 'rrt': 'rrt::RrtStyle', 'sas': 'sas::SasStyle', 'solarized-dark': 'solarized::SolarizedDarkStyle', 'solarized-light': 'solarized::SolarizedLightStyle', 'staroffice': 'staroffice::StarofficeStyle', 'stata-dark': 'stata_dark::StataDarkStyle', 'stata-light': 'stata_light::StataLightStyle', 'tango': 'tango::TangoStyle', 'trac': 'trac::TracStyle', 'vim': 'vim::VimStyle', 'vs': 'vs::VisualStudioStyle', 'xcode': 'xcode::XcodeStyle', 'zenburn': 'zenburn::ZenburnStyle'}

スタイル名を 'submodule::classname' 文字列にマッピングする、組み込みスタイルの辞書。このリストは非推奨です。pygments.styles.STYLES を代わりに使用してください

字句解析器

すべての字句解析器が派生する基本字句解析器クラスは次のとおりです。

class pygments.lexer.Lexer(**options)

特定の言語の字句解析器。

独自の字句解析器の作成（字句解析器を作成するための高レベルガイド）も参照してください。

字句解析器クラスには、さまざまな基準に基づいて最適な字句解析器を選択するために使用される属性があります。

name

字句解析器の完全名（人間が読める形式）

aliases

get_lexer_by_name() などのリストから字句解析器を検索するために使用できる、短く一意な識別子のリスト。

filenames

この字句解析器のコンテンツを含むファイル名に一致する fnmatch パターンのリスト。このリストのパターンは、すべての字句解析器間で一意である必要があります。

alias_filenames = []

この字句解析器のコンテンツを含む場合と含まない場合があるファイル名に一致する fnmatch パターンのリスト。このリストは、guess_lexer_for_filename() 関数で、どの字句解析器を正しいものを推測に含めるかを判断するために使用されます。つまり、たとえば、HTML およびテンプレート言語のすべての字句解析器は、このリストに \*.html を含める必要があります。

mimetypes

この字句解析器で字句解析できるコンテンツの MIME タイプのリスト。

priority = 0

優先度。複数の字句解析器が一致し、コンテンツが提供されない場合に使用されます。

Pygments に含まれる字句解析器には、さらに 2 つの属性が必要です。

url

言語仕様/定義の URL。Pygments のドキュメントで使用されます。無効にするには、空の文字列に設定します。

version_added

字句解析器が追加された Pygments のバージョン。

Pygments に含まれる字句解析器には、追加の属性がある場合があります。

_example

サンプルファイル名です。tests/examplefiles ディレクトリからの相対パスです。ドキュメントジェネレータがサンプルを表示するために使用します。

コンストラクタにオプションを渡すことができます。すべてのレクサーで認識され、ベースの Lexer クラスで処理される基本的なオプションは以下のとおりです。

stripnl

入力の先頭と末尾の改行を削除します（デフォルト：True）。

stripall

入力の先頭と末尾のすべての空白を削除します（デフォルト：False）。

ensurenl

入力が改行で終わるようにします（デフォルト：True）。これは、入力を行単位で消費する一部のレクサーで必要です。

バージョン 1.3 で追加されました。

tabsize

指定されていて0より大きい場合、入力内のタブを展開します（デフォルト：0）。

encoding

指定された場合、エンコーディング名である必要があります。このエンコーディングは、入力文字列がまだUnicode文字列でない場合、Unicodeに変換するために使用されます（デフォルト：'guess'。これは単純なUTF-8 / Locale / Latin1検出を使用します。chardetライブラリがインストールされている場合は、'chardet'を使用することもできます）。

inencoding

指定された場合、encoding を上書きします。

__init__(**options)

このコンストラクタは、キーワード引数として任意のオプションを取ります。すべてのサブクラスは、まず独自のオプションを処理し、次にstripnlのような基本オプションを処理するため、Lexerコンストラクタを呼び出す必要があります。

例えば、このようになります

def __init__(self, **options):
    self.compress = options.get('compress', '')
    Lexer.__init__(self, **options)

これらのオプションはすべて文字列として指定できる必要があるので（コマンドラインでの使用のため）、それを支援するためのさまざまなユーティリティ関数が利用可能です。 ユーティリティを参照してください。

add_filter(filter_, **options)

このレクサーに新しいストリームフィルターを追加します。

static analyse_text(text)

レクサーの推測のために呼び出される静的メソッドです。

テキストを分析し、0.0から1.0の範囲のfloatを返す必要があります。 0.0を返した場合、そのレクサーは最も可能性の高いものとして選択されません。1.0を返した場合、すぐに選択されます。これはguess_lexerによって使用されます。

LexerMetaメタクラスは、この関数が静的メソッド（selfまたはclsパラメータなし）のように動作するように自動的にラップし、戻り値が自動的にfloatに変換されます。戻り値がブール値のFalseであるオブジェクトである場合、戻り値が0.0であった場合と同じです。

get_tokens(text, unfiltered=False)

このメソッドは、レクサーの基本的なインターフェースです。これは、highlight()関数によって呼び出されます。テキストを処理し、textから(tokentype, value) ペアのイテラブルを返す必要があります。

通常、このメソッドをオーバーライドする必要はありません。デフォルトの実装では、すべてのレクサーで認識されるオプション（stripnl、stripallなど）を処理し、get_tokens_unprocessed()からすべてのトークンを、indexをドロップして生成します。

unfilteredがTrueに設定されている場合、フィルターが定義されていても、フィルターメカニズムはバイパスされます。

get_tokens_unprocessed(text)

このメソッドは、テキストを処理し、(index, tokentype, value)タプルのイテラブルを返す必要があります。ここで、indexは入力テキスト内のトークンの開始位置です。

サブクラスによってオーバーライドされる必要があります。効率を最大化するために、ジェネレーターとして実装することをお勧めします。

レクサーを構築するために使用できるLexerから派生したいくつかの基本クラスがあります

class pygments.lexer.RegexLexer(*args, **kwds)

単純なステートフル正規表現ベースのレクサーのベースです。状態と正規表現のリストを提供するだけで済むように、レクサー処理を簡略化します。

class pygments.lexer.ExtendedRegexLexer(*args, **kwds)

状態を格納するためにコンテキストオブジェクトを使用するRegexLexer。

class pygments.lexer.DelegatingLexer(_root_lexer, _language_lexer, _needle=('Other',), **options)

このレクサーは、引数として2つのレクサーを取ります。ルートレクサーとランゲージレクサーです。まず、ランゲージレクサーを使用してすべてがスキャンされ、その後、すべてのOtherトークンはルートレクサーを使用してレクシングされます。

template レクサーパッケージのレクサーは、このベースレクサーを使用します。

フォーマッター

フォーマッターは、このクラスから派生します

class pygments.formatter.Formatter(**options)

トークンストリームをテキストに変換します。

フォーマッターは、それらを選択するのに役立つ属性を持っている必要があります。これらは、対応する Lexer 属性に似ています。

name

フォーマッターの完全な名前（人間が読める形式）。

aliases

リストからフォーマッターを検索するために使用できる、短く一意の識別子のリスト。たとえば、get_formatter_by_name()を使用するなど。

filenames

このフォーマッターが出力を生成できるファイル名と一致する fnmatch パターンのリスト。このリストのパターンは、すべてのフォーマッターで一意である必要があります。

コンストラクタにキーワード引数としてオプションを渡すことができます。すべてのフォーマッターは、これらの基本的なオプションを受け入れます

style

使用するスタイル。文字列またはStyleサブクラスを指定できます（デフォルト：「default」）。TerminalFormatterなどでは使用されません。

full

フォーマッターに「完全な」ドキュメント、つまり完全に自己完結型のドキュメントを出力するように指示します。一部のフォーマッターでは効果がありません（デフォルト：false）。

title

fullがtrueの場合、ドキュメントの見出しとして使用する必要があるタイトル（デフォルト： ''）。

encoding

指定された場合、エンコーディング名である必要があります。これは、出力でUnicodeトークン文字列をバイト文字列に変換するために使用されます。 “”またはNoneの場合、Unicode文字列が出力ファイルに書き込まれますが、ほとんどのファイルライクオブジェクトはサポートしていません（デフォルト：None）。

outencoding

指定された場合、encodingをオーバーライドします。

__init__(**options)

レクサーと同様に、このコンストラクタは任意のオプション引数を受け取り、オーバーライドする場合は、まず独自のオプションを処理してから、基本クラスの実装を呼び出す必要があります。

format(tokensource, outfile)

このメソッドは、tokensourceイテラブルからトークンを整形し、整形されたバージョンをファイルオブジェクトoutfileに書き込む必要があります。

Formatterのオプションは、トークンが正確にどのように変換されるかを制御できます。

get_style_defs(arg='')

このメソッドは、後続の強調表示されたテキスト（例えば、HTMLFormatterのCSSクラス）に対して現在のスタイルを定義するのに適したステートメントまたは宣言を返す必要があります。

オプションの引数argは、生成を変更するために使用でき、フォーマッターに依存します（コマンドラインで指定できるため標準化されています）。

このメソッドは、-S コマンドラインオプションによって呼び出され、argは-aオプションによって与えられます。

ユーティリティ

pygments.utilモジュールには、コマンドラインオプションの処理に使用できるいくつかのユーティリティ関数があります。以下の関数はすべて、オプションの辞書から値を取得します。値がオプションで期待される型ですでに存在する場合は、そのまま返されます。それ以外の場合、値が文字列の場合は、可能であれば最初に期待される型に変換されます。

exception pygments.util.OptionError

引数の型または値が正しくない場合、この例外はすべてのオプション処理関数によって発生します。

pygments.util.get_bool_opt(options, optname, default=None)

直感的に言うと、これはoptions.get(optname, default)ですが、ブール値に限定されています。ブール値は、コマンドライン引数からブール値を受け入れるために文字列として表すことができます。キーoptnameが辞書optionsに存在し、ブール値に関連付けられていない場合は、OptionErrorを発生させます。存在しない場合は、代わりにdefaultが返されます。

Trueの有効な文字列値は、1、yes、true、onで、Falseの有効な文字列値は、0、no、false、offです（大文字と小文字を区別せずに一致します）。

pygments.util.get_int_opt(options, optname, default=None)

get_bool_opt()と同様ですが、値を整数として解釈します。

pygments.util.get_list_opt(options, optname, default=None)

辞書optionsからのキーoptnameが文字列である場合は、空白で分割して返します。すでにリストまたはタプルである場合は、リストとして返されます。

pygments.util.get_choice_opt(options, optname, allowed, default=None, normcase=False)

辞書からのキーoptnameがシーケンスallowedにない場合は、エラーを発生させ、それ以外の場合は返します。

また、例外も定義します

exception pygments.util.ClassNotFound

ルックアップ関数のいずれかが一致するクラスを見つけられなかった場合に発生します。