Metadata-Version: 2.4
Name: docx-stitch
Version: 0.1.2
Summary: A Python library for merging .docx files that actually preserves the formatting.
Author: Cyrald
License-Expression: MIT
Project-URL: Homepage, https://github.com/Cyrald/DocxStitch
Project-URL: Repository, https://github.com/Cyrald/DocxStitch
Project-URL: Issues, https://github.com/Cyrald/DocxStitch/issues
Keywords: docx,docx-stitch,stitch,word,ooxml,merge,concatenate,document,office
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing :: Markup :: XML
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=5.0.0
Dynamic: license-file

# docx-stitch

A Python library for merging `.docx` files that actually preserves the formatting.


## Description


The implementation operates directly on the ZIP/XML structure of the OOXML
format. no high-level document library is involved. 
Each document's style names are isolated by adding a unique prefix
(`_doc2_`, `_doc3_`, …) to every style belonging to non-base documents, then
rewriting all references inside that document's XML to match, before merging
the XML trees.

Merging is pairwise and left-accumulative:

```
docx-stitch A B C -o out  ≡  merge(merge(A, B), C) → out
```

## Requirements

Python ≥ 3.10 · lxml ≥ 5.0

## Install

```
pip install docx-stitch
```

## Usage

### Command line

```bash
# Merge any number of files
docx-stitch part1.docx part2.docx part3.docx -o full.docx
```

### Python API

```python
from pathlib import Path
from docx_stitch import stitch

# Any number of files — merged in order
stitch(
    [Path("ch1.docx"), Path("ch2.docx"), Path("ch3.docx")],
    Path("book.docx"),
)
```

## What is preserved

| Feature | Status |
|---|---|
| Styles (paragraph, run, table, list) | ✅ Full isolation via per-document prefix |
| Images / media | ✅ UUID-renamed, rIds remapped |
| Headers & footers | ✅ Transferred with new filenames, rIds remapped |
| Numbered / bulleted lists | ✅ abstractNum and numId remapped |
| Footnotes & endnotes | ✅ w:id remapped, separator stubs synthesised if needed |
| Font table | ✅ Merged, duplicates skipped |
| Bookmarks & cross-references | ✅ w:id remapped to prevent repair dialogs |
| Floating objects (shapes, text boxes) | ✅ Drawing IDs remapped |
| Hyperlinks (external) | ✅ rIds remapped |
| Page margins / page size per document | ✅ Kept as independent OOXML sections |
| Charts, OLE objects, ActiveX | ⚠️  Skipped with warning |

## Known limitations

- **Charts, OLE objects, ActiveX controls**: skipped with a `WARNING` log message. The element referencing the unsupported object is kept in place; Word will report a missing relationship.
- **`word/theme/`**: not transferred (theme colours and fonts fall back to the base document's theme).
- **Custom XML parts** (`word/customXml/`): not transferred.

## REPORTING BUGS

https://github.com/Cyrald/DocxStitch/issues
