Export a docx file in Django application

Exporting file is a commonly used feature that allows users to retrieve their data.

Throughout this series, I will outline various methods for exporting files in a Django application. The exported file formats may include docx, csv, zip, or pdf.

In this initial post of the series, I will introduce the process of exporting a docx file. We will be utilizing a library called python-docx to achieve this.

python-docx

Introduction

python-dox is a Python library for creating and updating Microsoft Word (.docx) files.

Please checkout the official documentation here.

The fundamental concept behind python-docx is to create a document object to which you can add content such as paragraphs, headings, page breaks, tables, pictures and styling options like bold or italic.

Example:

from docx import Document
document = Document()
document.add_paragraph('Lorem ipsum dolor sit amet.')

Installing

To install python-docx, run command:

pip install python-docx

Export view

To enable the download of a docx file through an API, we typically create a view that allows only the GET method.

class ExportDocx(APIView):
    def get(self, request, *args, **kwargs):
        # create an empty document object
        document = Document()

        # save document info
        buffer = io.BytesIO()
        # save your memory stream
        document.save(buffer)
        # rewind the stream to a file
        buffer.seek(0)

        # put them to streaming content response
        # within docx content_type
        response = StreamingHttpResponse(
            # use the stream's content
            streaming_content=buffer,
            content_type='application/vnd.openxmlformats-officedocument.wordprocessingm'
        )

        response['Content-Disposition'] = 'attachment;filename=Test.docx'
        response["Content-Encoding"] = 'UTF-8'

        return response

Once we have created an empty document, the next step is to save it and send it to the response.

python-docx provides a document.save() method that acceps a stream instead of a file name.

We can initialize an io.BytesIO() object to store the document information and then send that to the user.

To handle large data and return a response, we use the StreamingHttpResponse function and set the content type to application/vnd.openxmlformats-officedocument.wordprocessingm for docx files.

Build document content

After enable to download an empty docx file, the next step is to begin building the content for the docx. It is recommended to refer to the python-docx documentation for detailed instructions.

To add header text, you can use the .add_heading() method, and to add paragraphs, you can use the .add_paragraph() method.

If you wish to style the text, you can add a run to a paragraph.

As an example, I have created a build_document() method which builds all the content in the document.

def build_document(self):
    document = Document()

    # add a header
    document.add_heading("This is a header")

    # add a paragraph
    document.add_paragraph("This is a normal style paragraph")

    # add a paragraph within an italic text then go on with a break.
    paragraph = document.add_paragraph()
    run = paragraph.add_run()
    run.italic = True
    run.add_text("text will have italic style")
    run.add_break()

    return document

I will then replace the code that creates an empty document in the view with the following:

document = self.build_document()

The current export result is shown below:

Advance - build html content

Essentially, I can export a docx file with content in it.

To begin with, I simply add the content within a paragraph:

# add paragraph for html content
document.add_paragraph("<p>Nice to see Prep note 2</p><ul><li>Prep note 2 content 1</li><li>Prep note 2 content 2</li></ul>")

However, there was a strange display as following:

I need to find a way to convert HTML content to plain text while preserving basic formatting such as italics, bolding, and bullet points. Here’s an example:

Nice to see Prep note 2
    ●    Prep note 2 content 1
    ●    Prep note 2 content 2

After research around, I discovered a Python built-in library called html.parser - Simple HTML and XHTML parser.

Followed an examle to create a class called DocumentHTMLParser to handle it, as shown below:

class DocumentHTMLParser(HTMLParser):
    """
    Document Within HTML Parser
    """
    def __init__(self, document):
        """
        Override __init__ method
        """
        HTMLParser.__init__(self)
        self.document = document
        self.paragraph = None
        self.run = None

    def add_paragraph_and_feed(self, html):
        """
        Custom method where add paragraph and feed
        """
        self.paragraph = self.document.add_paragraph()
        self.feed(html)

    def handle_starttag(self, tag, attrs):
        """
        Override handle_starttag method
        """
        self.run = self.paragraph.add_run()

        if tag in ["ul"]:
            self.run.add_break()
        if tag in ["li"]:
            self.run.add_text(u'        \u2022    ')

    def handle_endtag(self, tag):
        """
        Override handle_endtag method
        """
        if tag in ["li"]:
            self.run.add_break()

    def handle_data(self, data):
        """Override handle_data method"""
        self.run.add_text(data)

The code above involves overriding a function in the HTMLParser class and using the paragraph’s run to customize its style based on the starting tag.

If a tag needs to break on the end, we add a break for it.

I then utilized this custom class in my view to handle the HTML content:

def build_document(self):
    """Build content document"""
    document = Document()
    doc_html_parser = DocumentHTMLParser(document)

    # add a header
    document.add_heading("This is a header")

    # add a paragraph
    document.add_paragraph("This is a normal style paragraph")

    # add a paragraph within an italic text then go on with a break.
    paragraph = document.add_paragraph()
    run = paragraph.add_run()
    run.italic = True
    run.add_text("text will have italic style")
    run.add_break()

    # with html content, call method add_paragraph_and_feed tui build content
    html_content = "<p>Nice to see Prep note 2</p><ul><li>Prep note 2 content 1</li><li>Prep note 2 content 2</li></ul>"
    doc_html_parser.add_paragraph_and_feed(html_content)

Here’s the resulting docx file from the HTML content:

Unit Test

On the backend side, unit testing is a crucial component to protect your application. In my project, each pull request requires a minimum of 80% code coverage through testing, making unit testing a mandatory part of the development process. To aid in writing unit tests, we utilize libraries such as factory_boy and pytest. If you’re unfamiliar with these libraries, you can check out the links provided before proceeding.

In this section, I won’t be covering how to use or write unit tests for a Django application. Instead, I will ensure that the exported docx file has the correct name and type, and that the file contains the expected content and style.

Test content response

I performed some basic checks on the exported file, such as verifying the response status, content type, and file name.

def test_export_docx_general(self):
    """
    Ensure general content like
    status response, content type, file name exported correctly
    """
    response = self.client.get(reverse("export_docx"))
    import pdb;pdb.set_trace()

By using import pdb;pdb.set_trace() after making the GET request in the unit test, I am able to inspect the current data.

Here is an example of what it looks like:

<django.http.response.StreamingHttpResponse object at 0x7fc392a61990>
(Pdb) response.status_code
200
(Pdb) response.streaming_content
<map object at 0x7fc3927aadd0>
(Pdb) response.streaming_content.__dir__()
['__getattribute__', '__iter__', '__next__', '__new__', '__reduce__', '__doc__', '__repr__', '__hash__', '__str__', '__setattr__', '__delattr__', '__lt__', '__le__', '__eq__', '__ne__', '__gt__', '__ge__', '__init__', '__reduce_ex__', '__subclasshook__', '__init_subclass__', '__format__', '__sizeof__', '__dir__', '__class__']
(Pdb) response.get("Content-Type")
'application/vnd.openxmlformats-officedocument.wordprocessingm'
(Pdb) response.get("Content-Disposition")
'attachment;filename=Recipe_Pho_2021-04-15-14-34-09.docx'

As seen in the previous code block, I can continue writing unit tests to check the exported file’s general content, such as the file’s content type, status code, and name.

def test_export_docx_general(self):
    """
    Ensure general content like
    status response, content type, file name exported correctly
    """
    response = self.client.get(reverse("export_docx"))
    assert response.status_code == status.HTTP_200_OK
    assert response.get("Content-Type") == \
        "application/vnd.openxmlformats-officedocument.wordprocessingm"
    filename = response.get("Content-Disposition").split("=")[1]
    assert filename == "Test.docx"

Please note the response.streaming_content object above which appears as a map object without any data for testing. Initially, I was unsure about how to test the content and style of the document accurately. Despite researching various options, I could not find a suitable solution. Eventually, I came up with a solution for testing the built document myself, which is as follows:

Test document content

I have created a function in the code called build_document to build the document, which is now ready for testing:

def build_document(self):
    """Build content document"""
    document = Document()
    doc_html_parser = DocumentHTMLParser(document)

    # with html content, call method add_paragraph_and_feed tui build content
    html_content = "<p>Nice to see Prep note 2</p><ul><li>Prep note 2 content 1</li><li>Prep note 2 content 2</li></ul>"
    doc_html_parser.add_paragraph_and_feed(html_content)

My solution was to directly call this function for testing on a mocked view.

Here’s how it appears in the test function:

def test_build_document_for_docx(self):
    """Ensure document built content and style correctly"""
    # inline import just for you know where they are
    from django.http import HttpRequest
    from rest_framework.request import Request as DRFRequest

    # mock drf request
    request = HttpRequest()
    request.method = 'GET'
    drf_request = DRFRequest(request)
    drf_request.user = self.user

    # mock view with request
    view = ExportRecipesDocx()
    view.request = request

    # call function in view directly
    document = view.build_document()
    import pdb;pdb.set_trace()

Once again, I checked the document profile. As an example, I just have a personal curiosity and love to explore what they are 🥰.

(Pdb) document
<docx.document.Document object at 0x7fd5e65140a0>
(Pdb) document._body.paragraphs
[<docx.text.paragraph.Paragraph object at 0x7fd5e5d5fb50>]
(Pdb) document._body.paragraphs[0].runs
[<docx.text.run.Run object at 0x7fd5e5e419d0>, <docx.text.run.Run object at 0x7fd5e5eba6d0>, <docx.text.run.Run object at 0x7fd5e5eba410>, <docx.text.run.Run object at 0x7fd5e5eba3d0>]
(Pdb) document._body.paragraphs[0].runs[0].text
'Nice to see Prep note 2\n'
(Pdb) document._body.paragraphs[0].runs[0].style.name
'Default Paragraph Font'
(Pdb) document._body.paragraphs[0].runs[0].style.priority
1
(Pdb) document._body.paragraphs[0].runsp[1].text

In my current build_document method, I create a paragraph and add some runs to it, while also inserting breaks where necessary based on the start and end tags of the HTML.

Below is the final version of my unit test for checking the document’s content and styles:

def test_build_document_for_docx(self):
    """Ensure document built content and style correctly"""
    # mock request and view initialize like above code
    # ...
    # call function in view directly
    document = view.build_document()

    paragraphs = document._body.paragraphs
    assert len(paragraphs) == 1
    assert paragraphs[0].style.name == "Normal"
    assert paragraphs[0].style.priority is None
    assert [
        'Nice to see Prep note 2',
        '\n',
        '        •    Prep note 2 content 1\n',
        '        •    Prep note 2 content 2\n'
    ] == [item.text for item in paragraphs[0].runs]
    assert {None} == {item.italic for item in paragraphs[0].runs}
    assert {None} == {item.bold for item in paragraphs[0].runs}

Exporting files in a Django app is a fascinating process, and Python has several libraries that are useful for handling content formats.

Final word

In this article, we discussed a straightforward example of exporting docx files within a Django app.