rewrite to support formatting and nesting fields

.github/auto_assign-issues.yml

@@ -0,0 +1,8 @@
+# If enabled, auto-assigns users when a new issue is created 
+# Defaults to true, allows you to install the app globally, and disable on a per-repo basis
+addAssignees: true
+
+# The list of users to assign to new issues. 
+# If empty or not provided, the repository owner is assigned
+assignees:
+  - iulica

.github/workflows/python-publish.yml

@@ -0,0 +1,36 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -1,2 +1,9 @@
+.env
 /.tox/
 *.pyc
+*.egg-info
+dist
+*.code-workspace
+.DS_Store
+/tests/old
+/tests/output

LICENSE.txt

@@ -1,4 +1,5 @@
-Copyright (C) 2012 Bouke Haarsma
+Copyright (C) 2012 Bouke Haarsma, https://github.com/Bouke
+Copyright (C) 2023 Iulian Ciorascu, https://github.com/iulica
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.rst

@@ -2,13 +2,9 @@
 docx Mail Merge
 ===============
 
-.. image:: https://travis-ci.org/Bouke/docx-mailmerge.png?branch=master
-    :alt: Build Status
-    :target: https://travis-ci.org/Bouke/docx-mailmerge
-
-.. image:: https://badge.fury.io/py/docx-mailmerge.png
+.. image:: https://badge.fury.io/py/docx-mailmerge2.png
     :alt: PyPI
-    :target: https://pypi.python.org/pypi/docx-mailmerge
+    :target: https://pypi.python.org/pypi/docx-mailmerge2
 
 Performs a Mail Merge on Office Open XML (docx) files. Can be used on any
 system without having to install Microsoft Office Word. Supports Python 2.7,
@@ -20,7 +16,7 @@ Installation
 Installation with ``pip``:
 ::
 
-    $ pip install docx-mailmerge
+    $ pip install docx-mailmerge2
 
 
 Usage
@@ -30,14 +26,18 @@ Open the file.
 ::
 
     from mailmerge import MailMerge
-    with MailMerge('input.docx') as document:
+    with MailMerge('input.docx',
+            remove_empty_tables=False,
+            auto_update_fields_on_open="no",
+            keep_fields="none",
+            enable_experimnetal=False) as document:
         ...
 
 
 List all merge fields.
 ::
 
-    print document.get_merge_fields()
+    print(document.get_merge_fields())
 
 
 Merge fields, supplied as kwargs.
@@ -50,6 +50,9 @@ Merge table rows. In your template, add a MergeField to the row you would like
 to designate as template. Supply the name of this MergeField as ``anchor``
 parameter. The second parameter contains the rows with key-value pairs for
 the MergeField replacements.
+
+If the tables are empty and you want them removed, set remove_empty_tables=True
+in constructor.
 ::
 
     document.merge_rows('col1',
@@ -72,11 +75,8 @@ single call to `merge`.
 Starting in version 0.2.0 there's also the feature for template merging.
 This creates a copy of the template for each item in the list, does a merge,
 and separates them by page or section breaks (see function documentation).
-
-When using this feature, make sure you don't use comments, footnotes, 
-bookmarks, etc. This is because these elements have an id attribute, which
-must be unique. This library does not handle this, resulting in invalid
-documents.
+Starting in version 0.8.0 you can also use fields in the headers/footers/footnotes
+with the merge_templates method.
 ::
 
     document.merge_templates([
@@ -85,20 +85,105 @@ documents.
     ], separator='page_break')
 
 
+Starting in version 0.6.0 the fields formatting is respected when compatible.
+Numeric, Text, Conditional and Date fields (0.6.2) are implemented.
+For Date fields a compatible datetime, date or time objects must be provided.
+If locale support is needed, make sure to call the setlocale before merging
+::
+
+    import locale
+    locale.setlocale(locale.LC_TIME, '') # for system locale
+
+    document.merge_templates([
+        {'datefield': datetime.date('2022-04-15')},
+    ], separator='page_break')
+
+The {NEXT} fields are supported (0.6.3).
+
+You can also use the merge fields inside other fields, for example to insert
+pictures in the docx {INCLUDEPICTURE} or for conditional texts {IF}.
+Microsoft Word is needed to update the values of those fields.
+::
+
+    { INCLUDEPICTURE "{ MERGEFIELD path }/{ MERGEFIELD image }" }
+    { IF "{ MERGEFIELD reason }" <> "" "Reason: { MERGEFIELD reason }" }
+
+Always enclose the fields with double quotes, as the MERGE fields will be first
+filled in with data and then the other fields will be computed through Word.
+
+If the fields are nested inside other fields, the outer fields need to be
+updated in Word. This can be done by selecting everything (CTRL-a) and then
+update the fields (F9). There is a way to force the Word to update fields
+automatically when opening the document. docx-mailmerge can set this
+setting when saving the document. You can configure this feature by using
+the *auto_update_fields_on_open* parameter. The value *always* will set the
+setting regardless if needed or not and the value *auto* will only set it
+when necessary (when nested fields exist). The default value *no* will not
+activate this setting.
+
+The {NEXTIF} and {SKIPIF} fields are supported (0.9.0).
+The {IF} fields are supported (0.9.0) only if the enable_experimnetal=True is
+set.
+The condition can use nested fields. Spaces are *MANDATORY* before and after 
+the operator (<, <>, >, <=, >=, =). The values are better enclosed in double
+quotes. For <> and = operators, the Microsoft-style regular expressions are
+supported (?, \*).
+
 Write document to file. This should be a new file, as ``ZipFile`` cannot modify
 existing zip files.
 ::
 
     document.write('output.docx')
 
+By default, all MERGEFIELD fields are replaced with their value. If a value is 
+not given, it is replaced with an empty string.
+If you want to keep the existing MERGEFIELD fields (with their current value)
+you can specify the keep_fields="some" parameter in the constructor.
+::
+
+    from mailmerge import MailMerge
+    with MailMerge('keep_unchanged_fields.docx',
+            keep_fields="some") as document:
+        ...
+
+If you want to only update the value of the MERGEFIELD fields but keep the 
+fields themselves, you can specify the keep_fields="all" parameter in the 
+constructor. This way, you can change the document and update the fields again
+later.
+::
+
+    from mailmerge import MailMerge
+    with MailMerge('keep_all_fields.docx',
+            keep_fields="all") as document:
+        ...
+
+
 See also the unit tests and this nice write-up `Populating MS Word Templates
 with Python`_ on Practical Business Python for more information and examples.
 
+Inserting Dynamic Images
+========================
+
+To include dynamic images in a docx template document you can use the 
+{ INCLUDEPICTURE "...." } field. For the path you can use MERGEFIELD dynamic 
+fields. See example above.
+
+The problem is to actually include the images in the word document after the 
+mailmerge. This can be done by opening the merged docx in Microsoft Word, 
+selecting all the text and pressing the F9 to update all fields. Unfortunately
+this method needs Microsoft Word installed and it is known to cause a lot of 
+problems.
+
+Another solution would be to use the `docx-mergefields`_ package to replace the
+INCLUDEPICTURE fields with the actual image. This method also works with images
+loaded from a database in base64 data-uri format, as well as URLs and local images.
+
+See the documentation of `docx-mergefields`_ for examples.
+
 Todo / Wish List
 ================
 
-* Image merging.
-
+* Better support for the IF fields and conditions
 
 Contributing
 ============
@@ -119,7 +204,11 @@ unit test that demonstrates it. Run the test suite::
 Credits
 =======
 
-This library was written by `Bouke Haarsma`_ and contributors.
+| This library was `originally`_ written by `Bouke Haarsma`_ and contributors.
+| This repository is maintained by `Iulian Ciorăscu`_.
 
 .. _Bouke Haarsma: https://twitter.com/BoukeHaarsma
 .. _Populating MS Word Templates with Python: http://pbpython.com/python-word-template.html
+.. _originally: https://github.com/Bouke/docx-mailmerge
+.. _Iulian Ciorăscu: https://github.com/iulica/
+.. _docx-mergefields: https://github.com/iulica/docx-mergefields