docxcompose 2.2.0

Compose .docx documents

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

Example usage

Append a document to another document:

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.:

$ 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:

$ 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:

$ 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:

$ 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:

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.