diff --git a/docs/quickstart.md b/docs/quickstart.md index 3441876..b033a04 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,8 +1,9 @@ # Python-Redlines Quickstart `python-redlines` wraps a C# comparison engine to produce tracked-change redline `.docx` -files. This guide uses the `XmlPowerToolsEngine` (Open-XML-PowerTools); `DocxodusEngine` -works the same way. +files. This guide uses `DocxodusEngine` — the default and recommended engine. +`XmlPowerToolsEngine` (legacy) shares the same call signature; the only behavioural +difference is that it silently ignores the keyword arguments shown in Step 4. ### Step 0: Install @@ -10,22 +11,25 @@ Install the core package plus the engine you want as an extra. No .NET SDK is ne the engine binary is prebuilt and embedded in the wheel. ```commandline -pip install python-redlines[ooxmlpowertools] +pip install python-redlines[docxodus] ``` +Use `python-redlines[ooxmlpowertools]` for the legacy engine, or `python-redlines[all]` +for both. + ### Step 1: Import and Initialize the Wrapper In your Python script or interactive session, import and initialize the wrapper: ```python -from python_redlines.engines import XmlPowerToolsEngine +from python_redlines import DocxodusEngine -wrapper = XmlPowerToolsEngine() +wrapper = DocxodusEngine() ``` ### Step 2: Run Redlines -Use the `run_redline` method to compare documents. You can pass the paths of the `.docx` files or their byte content: +Use the `run_redline` method to compare documents. You can pass the paths of the `.docx` files (as `str` or `pathlib.Path`) or their byte content: ```python # Example with file paths @@ -37,12 +41,11 @@ with open('/path/to/original.docx', 'rb') as f: with open('/path/to/modified.docx', 'rb') as f: modified_bytes = f.read() -# This is a tuple, bytes @ element 0 +# Returns (redline_bytes, stdout, stderr) output = wrapper.run_redline('AuthorTag', original_bytes, modified_bytes) ``` -In both cases, `output` will contain the byte content of the resulting redline - a .docx with changes in tracked -changes. +In both cases, `output[0]` will contain the byte content of the resulting redline — a .docx with changes as Word tracked changes. ### Step 3: Handle the Output @@ -52,3 +55,20 @@ Process or save the output as needed. For example, to save the redline output to with open('/path/to/redline_output.docx', 'wb') as f: f.write(output[0]) ``` + +### Step 4: Tune the Comparison (optional, DocxodusEngine only) + +`DocxodusEngine` accepts keyword arguments to control move detection, granularity, and +more. See the [main README](../README.md#comparison-settings-docxodusengine-only) for +the full table. + +```python +output = wrapper.run_redline( + 'AuthorTag', original_bytes, modified_bytes, + detect_moves=True, + simplify_move_markup=True, # required with detect_moves for Word compatibility + detail_threshold=0.3, +) +``` + +`XmlPowerToolsEngine` silently ignores these kwargs — switch engines if you need them. diff --git a/packages/core/src/python_redlines/engines.py b/packages/core/src/python_redlines/engines.py index 0a9f346..63e07af 100644 --- a/packages/core/src/python_redlines/engines.py +++ b/packages/core/src/python_redlines/engines.py @@ -132,11 +132,11 @@ def _build_command(self, author_tag: str, original_path, modified_path, target_p """ 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,