GroupDocs.Comparison for Python 26.5.0 現已推出。這是自 25.12 以來首次在 PyPI 上公開發佈的版本，加入了純 Python 包裝器、內嵌 AGENTS.md 供 AI 助手探索、新的 console script，以及大量文件結構重組。

本次發行的新功能

关键 類別 摘要
COMPARISONPYTHON-34 Feature 純 Python 包裝器重建 — 公開 API 現已可在 Python 中完整檢視
COMPARISONPYTHON-35 Feature 在 wheel 中內嵌 AGENTS.md 供 AI 代理發現
COMPARISONPYTHON-36 Feature 新增文件頁面：Agents and LLM Integration（MCP 伺服器、內嵌 AGENTS.md、LLM 優化文件）
COMPARISONPYTHON-39 Feature 隨 wheel 安裝的 console script groupdocs-comparison — 包含 compare、info、list-formats 子指令
COMPARISONPYTHON-38 Enhancement 文件結構重組 — developer-guide/comparing-documents/ 合併了 comparison-basic/ 與 advanced-usage/comparison/；載入與儲存已平面化

公開 API 變更

26.x 包裝器使用全新產生器重建，提供更廣泛的公開 API 並清理了部分成員名稱。大多數針對 25.12 撰寫的腳本在 26.5 上可直接執行；以下變更依相容性影響分組說明。

新增可直接匯入的頂層類別

這些類別在 25.12 內部存在，但因 Nuitka 編譯的包裝器隱藏了 Python 內省。現在可直接匯入：

from groupdocs.comparison.license import License, Metered
from groupdocs.comparison.options import (
    Color, PdfCompareOptions, WordCompareOptions, CalculateCoordinatesModeEnumeration,
    ChangeType, ComparisonDisplayMode, DetalisationLevel, FolderComparisonExtension,
    ImagesInheritance, MetadataType, PagesSetup, PaperSize, PasswordSaveOption,
    PreviewFormats, PreviewResolution,
)
from groupdocs.comparison.result import ComparisonAction, FileType, Rectangle

新增 Color 類別

StyleSettings.font_color、.highlight_color、.shape_color、.boarder_color 現可接受以下任意形式：

from groupdocs.comparison.options import Color

# Named‑color factory
style.font_color = Color.from_name("firebrick")

# RGB / RGBA tuple
style.font_color = (255, 0, 0)
style.font_color = (255, 0, 0, 128)

# Hex string
style.font_color = "#FF8800"
style.font_color = "#80FF8800"  # AARRGGBB

# Packed ARGB int
style.font_color = 0xFF0000

# Or a Color instance directly
style.font_color = Color(178, 34, 34, 255)

Color 可從 groupdocs.comparison、groupdocs.comparison.options 與 groupdocs.pydrawing 匯入——三條路徑指向同一個類別。

基於 Callable 的 PreviewOptions

PreviewOptions 建構子接受 Python callable 作為 CreatePageStream 委派。回呼簽名為 (page_number) -> writable_stream：

from groupdocs.comparison.options import PreviewOptions, PreviewFormats

def create_page_stream(page_number):
    return open(f"page-{page_number}.png", "wb")

def release_page_stream(page_number):
    pass  # the bridge has already flushed/closed the stream

with Comparer("source.docx") as comparer:
    preview = PreviewOptions(create_page_stream, release_page_stream)
    preview.preview_format = PreviewFormats.PNG
    preview.page_numbers = [1, 2, 3]
    comparer.source.generate_preview(preview)

PreviewOptions(create_page_stream)（單參數、無 release 回呼）亦為有效寫法。

從座標屬性取得型別化 Rectangle

options = CompareOptions(calculate_coordinates=True)
with Comparer("source.docx") as comparer:
    comparer.add("target.docx")
    comparer.compare(options)
    for change in comparer.get_changes():
        b = change.box
        print(f"({b.x:.1f}, {b.y:.1f}) {b.width:.1f}x{b.height:.1f}")
# (488.96, 223.86) 71.09x36.80 — '…'

此修正為全產品範圍——適用於每個值型屬性（Point、Size 等），不僅限於 Rectangle。

在 options 建構子中使用屬性名稱的 kwarg

opts = ApplyChangeOptions(changes=changes, save_original_state=True)
save = SaveOptions(password="secret")
load = LoadOptions(password="open-sesame")
comp = CompareOptions(detect_style_changes=True, sensitivity_of_comparison=85)

setter 方式仍可使用（opts = ApplyChangeOptions(); opts.changes = changes）。未知的 kwarg 會拋出 TypeError。

新增帶後綴的重載方法

為了讓每個 .NET 重載在 Python 中都有明確、非歧義的呼叫方式，新增了一組帶後綴的重載方法。例如：

  • Comparer.add_file(path), add_stream(stream), add_streams(streams), add_string(text)
  • Comparer.apply_changes_file(path, options), apply_changes_stream(stream, options), …
  • Comparer.compare_file(...), compare_stream(...), compare_streams(...), compare_string(...), compare_compare_options(...), compare_save_options(...)
  • Comparer.compare_directory_file(...), compare_directory_string(...)
  • Comparer.get_changes_change_type(...), get_changes_get_change_options(...)
  • License.set_license_file(...), set_license_stream(...), set_license_streams(...), set_license_string(...)
  • Metered.set_metered_key_file(...), set_metered_key_string(...)
  • Document.generate_preview_preview_options(...)
  • localization.SupportedLocales.is_locale_supported_culture_info(...), is_locale_supported_file(...), is_locale_supported_string(...)

明確的 Comparer.dispose()

提供給不想使用 with 內容管理器的呼叫者。仍建議的使用模式為：

with Comparer("source.docx") as comparer:
    comparer.add("target.docx")
    comparer.compare("result.docx")

Enum 命名規則

所有列舉皆採用大寫 Python 風格。常見列舉範例：

from groupdocs.comparison.result import ComparisonAction, FileType
from groupdocs.comparison.options import (
    ChangeType, ComparisonDisplayMode, DetalisationLevel,
    FolderComparisonExtension, ImagesInheritance, MetadataType,
    PaperSize, PasswordSaveOption, PreviewFormats, PreviewResolution,
)
from groupdocs.comparison.words.revision import RevisionAction

ComparisonAction.ACCEPT, ComparisonAction.REJECT, ComparisonAction.NONE
RevisionAction.ACCEPT, RevisionAction.REJECT, RevisionAction.NONE
PreviewFormats.PNG, PreviewFormats.JPG
MetadataType.SOURCE, MetadataType.TARGET, MetadataType.FILE_AUTHOR
PasswordSaveOption.USER, PasswordSaveOption.SOURCE, PasswordSaveOption.TARGET

若您參考 25.12 文件中使用 .Accept/.Reject 形式的列舉值，請改為大寫形式。

程式碼範例

以下是一個最小範例，示範如何匯入新顯示的頂層類別並執行簡單比較：

from groupdocs.comparison import Comparer
from groupdocs.comparison.options import CompareOptions

options = CompareOptions(detect_style_changes=True)

with Comparer("source.docx") as comparer:
    comparer.add("target.docx")
    comparer.compare(options)
    for change in comparer.get_changes():
        print(f"Change type: {change.change_type}, Box: {change.box}")

如何取得更新

PyPI

pip install groupdocs-comparison-net==26.5.0

此 wheel 已在公共 PyPI 上發布：https://pypi.org/project/groupdocs-comparison-net/

直接下載

未提供直接下載連結；請透過 PyPI 或 GroupDocs 官方網站取得套件。

資源