
*docxcompose* is a Python library for concatenating/appending Microsoft
Word (.docx) files.


Example usage
-------------

Append a document to another document:

.. code::

    from docxcompose.composer import Composer
    from docx import Document
    master = Document("master.docx")
    composer = Composer(master)
    doc1 = Document("doc1.docx")
    composer.append(doc1)
    composer.save("combined.docx")


The docxcompose console script
------------------------------


The ``docxcompose`` console script allows to compose docx files from the command
line, e.g.:

.. code:: sh

    $ docxcompose files/master.docx files/content.docx -o files/composed.docx


Docker container
----------------

docxcompose is also available as a Docker container allowing to compose docx 
documents through a web service.

To start the web service, run:

.. code:: sh

    $ docker run -it --rm -p 8080:8080 4teamwork/docxcompose

To compose documents, just upload them in the desired order as a ``multipart/form-data``
request to the web service and you will get back the composed document. Example with curl:

.. code:: sh

    $ curl -F "first=@first.docx" -F "second=@second.docx" -o composed.docx http://localhost:8080/


Options
-------

Preserving styles
~~~~~~~~~~~~~~~~~

By default docxcompose tries to apply styles from the first document to the
appended documents. This should ensure a consistent appearance throughout the
composed document.

With the ``preserve-styles`` option, it's possible to change this behavior to
keep the styles of the appended documents.

The option can be given through the command line (``--preserve-styles``),
via the web service url using an url parameter (``preserve_styles=1``) or using
Python ``Composer(preserve_styles=True)``.


Installation for development
----------------------------

To install docxcompose for development, clone the repository and using a python with poetry:

.. code:: sh

    $ poetry install

Tests can then be run with ``pytest``.


A note about testing
--------------------

The tests provide helpers for blackbox testing that can compare whole word
files. To do so the following files should be provided:

- a file for the expected output that should be added to the folder
  `docs/composed_fixture`
- multiple files that can be composed into the file above should be added
  to the folder `docs`.

The expected output can now be tested as follows:


.. code:: python

    def test_example():
        fixture = FixtureDocument("expected.docx")
        composed = ComposedDocument("master.docx", "slave1.docx", "slave2.docx")
        assert fixture == composed


Should the assertion fail the output file will be stored in the folder
`docs/composed_debug` with the filename of the fixture file, `expected.docx`
in case of this example.


Headers and footers
-------------------

The first document is considered as the main template and headers and footers from the other documents are ignored, so that the header and footer of the first document is used throughout the merged file.
