GroupDocs.Comparison for Python 26.5.0 现已发布。这是自 25.12 以来的首次公开 PyPI 发布，推出了纯 Python 包装器，捆绑 AGENTS.md 用于 AI‑assistant 发现，全新的控制台脚本，以及大量文档结构重构。

本次发布的新功能

键 类别 摘要
COMPARISONPYTHON-34 Feature 纯 Python 包装器重建 — 公开 API 现在可在 Python 中完全进行反射
COMPARISONPYTHON-35 Feature 在 wheel 中捆绑 AGENTS.md 以进行 AI‑agent 发现
COMPARISONPYTHON-36 Feature 新增文档页面：Agents and LLM Integration（MCP 服务器，捆绑的 AGENTS.md，针对 LLM 优化的文档）
COMPARISONPYTHON-39 Feature 随 wheel 安装的控制台脚本 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 导入——这三条路径指向同一个类。

基于可调用对象的 PreviewOptions

PreviewOptions 构造函数接受一个 Python 可调用对象，用作 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)（单参数、无释放回调）同样有效。

从坐标属性获得类型化 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。

选项构造函数的属性名 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。

新的 overload‑suffixed 方法

为公共表面添加了一组 overload‑suffixed 方法，使每个 .NET overload 都能通过明确、无歧义的名称在 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")

枚举大小写

所有枚举均使用大写的 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 官网获取软件包。

资源