=================
docx Merge Fields
=================

.. image:: https://badge.fury.io/py/docx-mergefields.png
    :alt: PyPI
    :target: https://pypi.python.org/pypi/docx-mergefields

Udpates the MAILMERGE fields in Office Open XML (docx) files. Can be used on any
system without having to install Microsoft Office Word. Supports Python 3.7 and up.
For the moment only the INCLUDEPICTURE fields are supported.

It supports local images, URLs and base64 image encoded strings. Also, it allows 
the resize of the image both in width and height.

The fields are *replaced* so afterwards they cannot be updated anymore.

This library makes use of the excellent `python-docx`_ library.

Also, it is better used after mailmerging the INCLUDEPICTURE fields using the 
`docx-mailmerge2`_ library.


Installation
============

Installation with ``pip``:
::

    $ pip install docx-mergefields


Usage
=====

Open the file.
::

    from mergefields import MergeFieldsDocument
    with MergeFieldsDocument("../documents/mailmerge_doc.docx") as doc:
      doc.transform_fields()
      doc.doc.save("../documents/merged_doc.docx")


Examples
========

From local file, original size:
::

  { INCLUDEPICTURE "./filename.jpg" }

From a URL, resize width to the given size, resize height to 
preserving the aspect ratio:
::

  { INCLUDEPICTURE "https://www.pngall.com/wp-content/uploads/8/Sample-Watermark-PNG-Image.png" \w 200 }

From a base64 URI, resize both width and height to the given value
(aspect ratio is not preserved):
::

  { INCLUDEPICTURE "data:image/png;base64, " \w 200 \h 200 }


Todo / Wish List
================

* Include other fields
* Update the fields instead of replacing them

Contributing
============

* Fork the repository on GitHub and start hacking
* Create / fix the unit tests
* Send a pull request with your changes

Unit tests
----------

In order to make sure that the library performs the way it was designed, unit
tests are used. When providing new features, or fixing bugs, there should be a
unit test that demonstrates it. Run the test suite::

    python -m unittest discover

Credits
=======

| This repository is written and maintained by `Iulian Ciorăscu`_.

.. _python-docx: https://pypi.org/project/python-docx/
.. _docx-mailmerge2: https://github.com/iulica/docx-mailmerge
.. _Iulian Ciorăscu: https://github.com/iulica/
