Add pluggable comparison engine system with Docxodus support #18
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit introduces a pluggable architecture for document comparison engines,
allowing users to choose between Open-Xml-PowerTools and Docxodus backends.
Key changes:
- Add abstract ComparisonEngine base class defining the engine interface
- Refactor XmlPowerToolsEngine to inherit from ComparisonEngine
- Add DocxodusEngine for the modern Docxodus backend (.NET 8.0)
- Create EngineRegistry for dynamic engine discovery and selection
- Add get_engine(), list_engines(), list_available_engines() functions
- Create Docxodus C# CLI project using Docxodus NuGet package
- Update build system to support building both engines
- Add comprehensive test suite (79 tests) covering:
- Base class interface contracts
- Engine implementations with mocking
- Registry functionality
- Package imports and API
- Backward compatibility with run_redline() method
Breaking changes: None - maintains full backward compatibility
Usage:
from python_redlines import get_engine
engine = get_engine() # default: openxml-powertools
engine = get_engine('docxodus') # use Docxodus
redline, _, _ = engine.compare(author, original, modified)
- Run tests on Ubuntu, Windows, and macOS - Test against Python 3.9, 3.10, 3.11, 3.12 - Build .NET binaries before running tests - Include coverage reporting via Codecov - Add separate unit-test-only job for quick feedback - Add linting check with ruff - Add build verification job
- Add Quick Start section with installation and basic usage - Document the pluggable engine architecture - Add comparison table for available engines - Explain Docxodus benefits and plan to make it default - Add API reference section with ComparisonEngine interface - Update project structure documentation - Add supported platforms table - Include development setup and build instructions - Add roadmap section - Add CI badge and other status badges - Link to Docxodus, Open-Xml-PowerTools, and other resources
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces a pluggable comparison engine architecture for the python-redlines library, enabling support for multiple document comparison backends. It adds the Docxodus engine (a modern .NET 8.0 fork of Open-Xml-PowerTools) alongside the existing Open-Xml-PowerTools engine, with improved build infrastructure and comprehensive documentation.
Key Changes
Architecture & Core
ComparisonEngineabstract base class andComparisonErrorexception for a pluggable architectureEngineRegistryfor dynamic engine discovery and selection viaget_engine()functionBinaryManagerutility class to handle platform-specific binary extraction and caching for both Windows, Linux, and macOS (x64 and ARM64)Engine Implementations
ComparisonEnginewith improved error handling and backward compatibilitycompare(author, original, modified)interfaceBuild System
--engine,--platform)csproj-docxodus/with Program.cs and redline.csproj for building the Docxodus binarySKIP_BINARY_BUILDenvironment variable is set (useful for development)Project Metadata
pyproject.tomlwith proper description, keywords, and classifiersbuild-engines,build-openxml,build-docxodusDocumentation
__init__.pywith quick start examplesDirectory Structure
dist/openxml-powertools/anddist/docxodus/.gitignorefiles for binary artifactsImplementation Details
run_redline()method andextracted_binaries_pathproperty on XmlPowerToolsEngine for existing codeTesting Considerations
The changes maintain backward compatibility while enabling new functionality. Existing code using
XmlPowerToolsEnginedirectly will continue to work unchanged. New code can use the registry system for more flexible engine selection.