python-redlines 0.2.0__tar.gz → 0.3.0__tar.gz

{python_redlines-0.2.0 → python_redlines-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-redlines
-Version: 0.2.0
+Version: 0.3.0
 Summary: Generate tracked-change redline .docx documents by comparing Word files.
 Project-URL: Homepage, https://github.com/JSv4/Python-Redlines
 Project-URL: Issues, https://github.com/JSv4/Python-Redlines/issues
@@ -57,6 +57,9 @@ redline_bytes, stdout, stderr = engine.run_redline(
 )
 ```
 
+`DocxodusEngine` accepts `engine="wmlcomparer"` (default) or `engine="docxdiff"` to select the
+comparison algorithm. See the [project README](https://github.com/JSv4/Python-Redlines#choosing-an-engine).
+
 If an engine's companion package is not installed, instantiating the engine
 raises `EngineNotInstalledError` with the `pip install` command to fix it.
 

{python_redlines-0.2.0 → python_redlines-0.3.0}/README.md

@@ -28,6 +28,9 @@ redline_bytes, stdout, stderr = engine.run_redline(
 )
 ```
 
+`DocxodusEngine` accepts `engine="wmlcomparer"` (default) or `engine="docxdiff"` to select the
+comparison algorithm. See the [project README](https://github.com/JSv4/Python-Redlines#choosing-an-engine).
+
 If an engine's companion package is not installed, instantiating the engine
 raises `EngineNotInstalledError` with the `pip install` command to fix it.
 

{python_redlines-0.2.0 → python_redlines-0.3.0}/src/python_redlines/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2024-present U.N. Owen <void@some.where>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{python_redlines-0.2.0 → python_redlines-0.3.0}/src/python_redlines/engines.py

@@ -132,16 +132,21 @@ class BaseEngine(object):
         """
         return [self.extracted_binaries_path, author_tag, original_path, modified_path, target_path]
 
-    def run_redline(self, author_tag: str, original: Union[bytes, Path], modified: Union[bytes, Path], **kwargs) \
-            -> Tuple[bytes, Optional[str], Optional[str]]:
+    def run_redline(self, author_tag: str, original: Union[str, bytes, Path], modified: Union[str, bytes, Path],
+                    **kwargs) -> Tuple[bytes, Optional[str], Optional[str]]:
         """
-        Runs the redline binary. The 'original' and 'modified' arguments can be either bytes or file paths.
-        Returns the redline output as bytes.
+        Runs the redline binary. The 'original' and 'modified' arguments can be either bytes or file paths
+        (as ``str`` or ``pathlib.Path``). Returns the redline output as bytes.
 
         Additional keyword arguments are passed to _build_command() for engine-specific options.
-        DocxodusEngine supports: detail_threshold, case_insensitive, detect_moves,
+        DocxodusEngine supports: engine, detail_threshold, case_insensitive, detect_moves,
         simplify_move_markup, move_similarity_threshold, move_minimum_word_count,
         detect_format_changes, conflate_spaces, date_time.
+
+        DocxodusEngine's engine kwarg selects the comparison algorithm: 'wmlcomparer'
+        (the default) or 'docxdiff'. The docxdiff engine ignores detail_threshold,
+        simplify_move_markup, and detect_format_changes, so passing them alongside
+        engine='docxdiff' raises ValueError rather than silently changing nothing.
         """
         temp_files = []
         try:
@@ -194,6 +199,13 @@ class DocxodusEngine(BaseEngine):
     BINARY_BASE_NAME = 'redline'
     EXTRA_NAME = 'docxodus'
 
+    # Comparison engines accepted by the redline CLI's --engine flag.
+    ENGINES = ('wmlcomparer', 'docxdiff')
+
+    # DocxCompare.ToDocxDiffSettings drops these on the docxdiff branch, and the CLI
+    # accepts them there without complaint, so reject them before we shell out.
+    _WMLCOMPARER_ONLY = ('detail_threshold', 'simplify_move_markup', 'detect_format_changes')
+
     # Boolean flags (default False — presence enables)
     _BOOL_FLAGS = [
         ('case_insensitive', '--case-insensitive'),
@@ -215,8 +227,33 @@ class DocxodusEngine(BaseEngine):
         ('date_time', '--date-time'),
     ]
 
-    @staticmethod
-    def _validate_kwargs(kwargs):
+    @classmethod
+    def _normalize_engine(cls, kwargs):
+        """The chosen engine, lowercased and stripped, or None if the caller didn't pick one."""
+        if 'engine' not in kwargs:
+            return None
+
+        engine = kwargs['engine']
+        if not isinstance(engine, str):
+            raise ValueError(f"engine must be a string, got {engine!r}")
+
+        normalized = engine.strip().lower()
+        if normalized not in cls.ENGINES:
+            raise ValueError(
+                f"engine must be one of {', '.join(cls.ENGINES)}, got {engine!r}"
+            )
+        return normalized
+
+    @classmethod
+    def _validate_kwargs(cls, kwargs):
+        if cls._normalize_engine(kwargs) == 'docxdiff':
+            for name in cls._WMLCOMPARER_ONLY:
+                if name in kwargs:
+                    raise ValueError(
+                        f"{name} is not supported by the 'docxdiff' engine "
+                        f"(WmlComparer-only). Remove it or use engine='wmlcomparer'."
+                    )
+
         if 'detail_threshold' in kwargs:
             val = kwargs['detail_threshold']
             if not isinstance(val, (int, float)) or val < 0.0 or val > 1.0:
@@ -234,10 +271,14 @@ class DocxodusEngine(BaseEngine):
 
     def _build_command(self, author_tag, original_path, modified_path, target_path, **kwargs):
         self._validate_kwargs(kwargs)
+        engine = self._normalize_engine(kwargs)
 
         cmd = [self.extracted_binaries_path, original_path, modified_path, target_path,
                f'--author={author_tag}']
 
+        if engine is not None:
+            cmd.append(f'--engine={engine}')
+
         for kwarg, flag in self._BOOL_FLAGS:
             if kwargs.get(kwarg):
                 cmd.append(flag)