GroupDocs.Comparison for Python via .NET 26.5 Release Notes

The 26.5.0 is the first public-PyPI release of GroupDocs.Comparison for Python via .NET since 25.12. It rebuilds the Python wrapper as pure Python (was Nuitka-compiled), ships an AGENTS.md reference inside the wheel for AI coding assistants, broadens the public API surface, restructures the documentation, and fixes a set of wrapper issues.

Upgrading from 25.12? Most existing scripts run unchanged on 26.5. The biggest behavioural surface additions are: an importable Color class with flexible input shapes, callable-based PreviewOptions, typed Rectangle returns on coordinate properties, and property-name kwargs on options constructors. See Public API changes below for the full list.

Full list of changes in this release

Python version compatibility

• 25.12 (prev public release): Python 3.5 – 3.13
• 26.5 (current): Python 3.5 – 3.14

pip install now correctly accepts/rejects interpreters thanks to the new Requires-Python constraint in the wheel METADATA.

Installation

pip install groupdocs-comparison-net==26.5.0

The wheel is published on public PyPI: https://pypi.org/project/groupdocs-comparison-net/

AGENTS.md shipped inside the wheel

Starting with 26.5, the pip package bundles a machine-readable AGENTS.md at groupdocs/comparison/AGENTS.md. AI coding assistants that scan installed packages (Claude Code, Cursor, GitHub Copilot agent mode, others) discover the API surface, usage patterns, and troubleshooting tips without further configuration.

pip show -f groupdocs-comparison-net | grep AGENTS

A new documentation page explains how to combine the bundled AGENTS.md, the GroupDocs MCP server (https://docs.groupdocs.com/mcp), and the LLM-optimized documentation endpoints with AI coding tools:

• Agents and LLM Integration

Wheel distribution

Four platform-specific wheels per release:

pip automatically selects the right wheel for your platform.

Public API changes

The 26.x wrapper was rebuilt with a new generator that exposes a broader public API and cleans up a few member names. Most existing scripts written against 25.12 run unchanged on 26.5; the changes below are grouped by compatibility impact.

Newly-visible top-level classes

These classes existed in 25.12 internals but were hidden from Python introspection by the Nuitka-compiled wrapper. They are now directly importable:

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

If you previously imported these via private paths or via the bridge, you can now use the public locations above. No behavioural change.

New Color class

StyleSettings.font_color, .highlight_color, .shape_color, and .boarder_color now accept any of:

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 is importable from groupdocs.comparison, groupdocs.comparison.options, and groupdocs.pydrawing — all three paths resolve to the same class.

Callable-based PreviewOptions

PreviewOptions constructor accepts a Python callable for the CreatePageStream delegate. The callback signature is (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) (single-arg, no release callback) is also valid.

Typed Rectangle from coordinate properties

ChangeInfo.box (and every other value-typed property across the API surface) now returns a typed wrapper with snake_case accessors instead of a raw PascalCase dict:

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 — '…'

The fix is product-wide — applies to every value-typed property across every product (Point, Size, etc., not just Rectangle).

Property-name kwargs on options constructors

Every options class accepts property-name kwargs as a convenience:

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)

The setter pattern still works (opts = ApplyChangeOptions(); opts.changes = changes). Unknown kwargs still raise TypeError, so typos surface loudly.

New overload-suffixed methods

A set of overload-suffixed methods has been added to the public surface so each .NET overload is callable from Python by an explicit, non-ambiguous name. The unsuffixed overload-dispatched versions still work — these additions are documentation, not requirements.

• Comparer.add_file(path), add_stream(stream), add_streams(streams), add_string(text)
• Comparer.apply_changes_file(path, options), apply_changes_stream(stream, options), apply_changes_streams(streams, options), apply_changes_string(text, 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(...)

Explicit Comparer.dispose()

Available for callers who prefer not to use the with context-manager idiom. The recommended pattern remains:

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

Compatibility note

The wrapper’s overload dispatcher continues to handle un-suffixed add(path_or_stream), compare(path_or_stream, options=None), etc. — existing call sites do not need to change. The suffixed methods are a convenience for code generators, MCP-driven tools, and any caller that wants overload selection to be explicit.

Enum casing

All enums use UPPERCASE Python convention. The most common enums:

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

If you were on 25.12 documentation that showed .Accept / .Reject style values, update them to the uppercase form.

Documentation updates

The python-net documentation has been restructured to match the rest of the GroupDocs.Python.via.NET family:

• New top-level structure: getting-started/, developer-guide/, plus product-overview.md and agents-and-llm-integration.md at the root.
• comparison-basic/ + advanced-usage/comparison/ → developer-guide/comparing-documents/: 25 topic pages flattened into a single section, with aliases: preserving the old URLs.
• advanced-usage/loading/ → developer-guide/loading-documents/, advanced-usage/saving/ → developer-guide/saving-results/: flattened to one level.
• New pages: Quick start guide, Product overview, Agents and LLM Integration, Logging and Diagnostics, Compare multiple documents (consolidated from three legacy pages).
• Every example regenerated: code now uses from groupdocs.comparison import Comparer (rather than import groupdocs.comparison as gc) and is wrapped in a runnable function with if __name__ == "__main__":.
• Sample files and output files mirror the docs tree: input documents live under _sample_files/<doc-path>/, captured outputs under _output_files/<doc-path>/. Each example page exposes the input and output as downloadable tabs.

Code examples

The companion examples repository has been regenerated to mirror the new documentation structure:

https://github.com/groupdocs-comparison/GroupDocs.Comparison-for-Python-via-.NET

The repository now includes:

• Examples/run_all_examples.py — discovers and runs every example, reports pass/fail counts.
• AGENTS.md — extracted from the wheel for AI-tool consumption.
• Dockerfile and .dockerignore — reproducible container build for Linux / CI.
• .github/workflows/ — CI matrix that runs the full example suite on every push.

Feedback and issue reporting

Report issues on the GroupDocs.Comparison forum with:

• The GroupDocs.Comparison version (pip show groupdocs-comparison-net).
• A minimal Python snippet that reproduces the issue.
• The source and target files (or simplified versions).
• The full traceback or error message.

Paid support tickets can be opened on the Paid Support Helpdesk.