Metadata-Version: 2.4
Name: docx-replace-attach
Version: 0.0.6
Summary: Replace key words to attachments inside a document of MS Word or Excel
Author-email: mintya <931108724@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mintya/docx-replace-attach
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-docx>=1.1.0
Requires-Dist: pillow>=10.3.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# docx-replace-attach
![License](https://img.shields.io/github/license/mintya/docx-replace-attach)
![GitHub release](https://img.shields.io/github/release/mintya/docx-replace-attach)
![GitHub stars](https://img.shields.io/github/stars/mintya/docx-replace-attach)
![GitHub forks](https://img.shields.io/github/forks/mintya/docx-replace-attach)  

This library was built on top of [python-docx](https://python-docx.readthedocs.io/en/latest/index.html) and the main purpose is to replace key words to attachments inside a document of MS Word.    

Just like this:   
![Example](images/img.png)  

## Features
- Replaces `{key_name}` placeholders with embedded OLE attachments (shown as an icon)
- Works when the placeholder is split across multiple runs (a common case in real Word documents)
- Replaces **all** occurrences, in body text, tables, text boxes, headers and footers
- Preserves surrounding text, run order and formatting (bold, color, size, ...)
- Returns the number of replacements made
- Icon captions are wrapped by display width, so CJK filenames render correctly

## Getting started
You can define a key in your Word document. This program requires the following key format: `{key_name}`
### How to install
```sh
pip3 install docx-replace-attach
```
### How to use
Example:
```py
from docx import Document
from docx_attachment import replace_xlsx
from docx_attachment import replace_docx


# The template file
doc = Document('template.docx')

# replace key_name to a word file, key_name is word_attachment, word file is word_attachment.docx
replace_docx(doc, 'word_attachment', 'word_attachment.docx')

# replace key_name to a excel file, key_name is excel_attachment, excel file is excel_attachment.xlsx
replace_xlsx(doc, 'excel_attachment', 'excel_attachment.xlsx')

# both functions return the number of placeholders replaced
assert replace_xlsx(doc, 'excel_attachment', 'excel_attachment.xlsx') > 0

# save as a new file
doc.save('new.docx')

```
You can also use:
```py
from docx_attachment import replace_xlsx_in_template
from docx_attachment import replace_docx_in_template


replace_docx_in_template('template.docx', 'new.docx', 'word_attachment', 'word_attachment.docx')

replace_xlsx_in_template('template.docx', 'new.docx', 'excel_attachment', 'excel_attachment.xlsx')

```
### Custom attachment types
Beside Excel and Word files you can define your own attachment type:
```py
from docx import Document
from docx_attach import replace_attachment_in_document, AttachmentType

XLS_ATTACHMENT = AttachmentType(
    content_type='application/vnd.ms-excel',
    file_name_prefix='Microsoft_Excel_',
    file_extension='xls',
    program_id='Excel.Sheet.8',
    shape_width=76,
    shape_height=60,
    icon_base64='...',  # base64 encoded PNG icon
)

doc = Document('template.docx')
replace_attachment_in_document(doc, 'legacy_excel', 'file.xls', XLS_ATTACHMENT)
```

### Run tests
```sh
pip install -e '.[test]'
pytest
```

## Stargazers over time
[![Stargazers over time](https://starchart.cc/mintya/docx-replace-attach.svg?variant=adaptive)](https://starchart.cc/mintya/docx-replace-attach)
