完整的 Pygments API

本頁描述 Pygments API。

高階 API

來自 pygments 模組的函式

pygments.lex(code, lexer)

使用 lexer (必須是 Lexer 實例) 對 code 進行詞法分析，並返回一個可迭代的符記 (tokens)。目前，這只會呼叫 lexer.get_tokens()。

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

使用格式器 formatter (一個 Formatter 實例) 來格式化 tokens (一個符記的可迭代物件)。

如果給定 outfile 並且是一個有效的文件物件 (具有 write 方法的物件)，則結果將寫入該物件，否則將作為字串返回。

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

這是最高階的語法高亮函式。它將 lex 和 format 組合在一個函式中。

來自 pygments.lexers 的函式

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

返回一個 Lexer 子類的實例，該子類的別名列表中具有 alias。詞法分析器在其例項化時會給定 options。

如果找不到具有該別名的詞法分析器，將引發 pygments.util.ClassNotFound。

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

取得檔案名的詞法分析器。

返回一個 Lexer 子類實例，其檔案名模式與 fn 匹配。詞法分析器在其例項化時會給定 options。

如果找不到該檔案名的詞法分析器，則引發 pygments.util.ClassNotFound。

如果多個詞法分析器與檔案名模式匹配，請使用它們的 analyse_text() 方法來找出哪個更合適。

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

返回一個 Lexer 子類實例，該子類的 mimetype 列表中具有 mime。詞法分析器在其例項化時會給定 options。

如果找不到該 mimetype 的詞法分析器，將引發 pygments.util.ClassNotFound。

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

從檔案載入詞法分析器。

此方法期望一個相對於目前工作目錄的檔案，其中包含一個 Lexer 類。預設情況下，它期望 Lexer 的名稱為 CustomLexer；您可以將自己的類別名稱指定為此函式的第二個引數。

使用者應非常小心輸入，因為此方法等同於在輸入檔案上執行 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 (預設值)，則還會返回由 entrypoints 提供的外掛程式詞法分析器。否則，僅考慮內建的詞法分析器。

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)

返回 Lexer 子類，該子類的 name 屬性由 name 引數給定。

來自 pygments.formatters 的函式

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

傳回一個 Formatter 子類別的實例，該子類別在其別名列表中具有 alias。格式化器會在其實例化時獲得 options。

如果找不到具有該別名的格式化器，則會引發 pygments.util.ClassNotFound 錯誤。

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

傳回一個 Formatter 子類別實例，其具有符合 fn 的檔案名稱模式。格式化器會在其實例化時獲得 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 中包含的詞法分析器應具有兩個額外屬性

url

語言規格/定義的 URL。用於 Pygments 文件中。設定為空字串以停用。

version_added

加入詞法分析器的 Pygments 版本。

Pygments 中包含的詞法分析器可能具有其他屬性

_example

範例檔名。相對於 tests/examplefiles 目錄。這用於文件產生器顯示範例。

您可以將選項傳遞給建構函式。所有詞法分析器識別並由基礎 Lexer 類別處理的基本選項如下：

stripnl

從輸入中刪除開頭和結尾的換行符（預設值：True）。

stripall

從輸入中刪除所有開頭和結尾的空白字元（預設值：False）。

ensurenl

確保輸入以換行符結尾（預設值：True）。某些逐行消耗輸入的詞法分析器需要此選項。

在 1.3 版本中新增。

tabsize

如果給定且大於 0，則展開輸入中的 Tab 字元（預設值：0）。

encoding

如果給定，則必須是編碼名稱。如果輸入字串還不是 Unicode 字串，則此編碼將用於將其轉換為 Unicode（預設值：'guess'，使用簡單的 UTF-8 / Locale / Latin1 偵測。也可以是 'chardet' 以使用 chardet 程式庫，如果已安裝的話）。

inencoding

如果給定，則覆寫 encoding。

__init__(**options)

此建構函式接受任意選項作為關鍵字引數。每個子類別都必須先處理自己的選項，然後呼叫 Lexer 建構函式，因為它會處理 stripnl 等基本選項。

一個範例如下：

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 之間的浮點數。如果它返回 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() 產生所有 Token，並捨棄 index。

如果將 unfiltered 設定為 True，則即使定義了篩選器，也會略過篩選機制。

get_tokens_unprocessed(text)

此方法應處理文字並返回 (index, tokentype, value) 元組的可迭代物件，其中 index 是 Token 在輸入文字中的起始位置。

它必須由子類別覆寫。建議將其實作為產生器，以最大化效能。

有幾個從 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)

這個詞法分析器接受兩個詞法分析器作為引數。一個根詞法分析器和一個語言詞法分析器。首先，所有內容都會使用語言詞法分析器進行掃描，然後所有 Other Token 都會使用根詞法分析器進行詞法分析。

template 詞法分析器套件中的詞法分析器使用此基底詞法分析器。

格式器

格式器衍生自此類別

class pygments.formatter.Formatter(**options)

將 Token 資料流轉換為文字。

格式器應具有屬性以協助選取它們。這些屬性與對應的 Lexer 屬性相似。

name

格式器的完整名稱，以人類可讀的形式呈現。

aliases

可以用於從清單中查詢格式器的簡短、唯一識別碼清單，例如使用 get_formatter_by_name()。

filenames

fnmatch 樣式清單，符合此格式器可以產生輸出的檔名。此清單中的樣式應在所有格式器中都是唯一的。

您可以將選項作為關鍵字引數傳遞給建構函式。所有格式器都接受這些基本選項

style

要使用的樣式，可以是字串或 Style 子類別（預設值：「default」）。例如，TerminalFormatter 不會使用。

full

告知格式器輸出「完整」文件，即完整且獨立的文件。某些格式器沒有任何作用（預設值：false）。

title

如果 full 為 true，則應該用於標題文件的標題（預設值：''）。

encoding

如果給定，則必須是編碼名稱。這將用於將輸出中的 Unicode Token 字串轉換為位元組字串。如果它是「」或 None，則 Unicode 字串將寫入輸出檔案，而大多數類檔案物件都不支援這種方式（預設值：None）。

outencoding

如果給定，則覆寫 encoding。

__init__(**options)

與詞法分析器一樣，此建構函式接受任意可選引數，如果您覆寫它，則應先處理自己的選項，然後呼叫基底類別實作。

format(tokensource, outfile)

此方法必須將來自 tokensource 可迭代物件的 token 格式化，並將格式化後的版本寫入檔案物件 outfile。

格式化器的選項可以控制 token 如何轉換。

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

如果其中一個查詢函式找不到相符的類別，則會引發此例外。