5 Best Ways to Convert HTML to DOCX in Python

by

💡 Problem Formulation: Converting HTML strings to DOCX format is a common task for developers working with document automation and conversion in Python. The challenge lies in the need to preserve formatting and structure from the web-based HTML content into a Word document. For example, if we have an HTML string containing formatted text and images, our desired output would be a .docx file where all the elements appear as they did in the HTML string.

Method 1: Using Python-Docx

Python-Docx is a Python library for creating and updating Microsoft Word (.docx) files. However, it does not directly convert HTML to DOCX, but you can parse HTML and manually add the parsed content to a DOCX document by using this library.

Here’s an example:

from html.parser import HTMLParser
from docx import Document

class MyHTMLParser(HTMLParser):
    def __init__(self, doc):
        super().__init__()
        self.doc = doc
        
    def handle_data(self, data):
        self.doc.add_paragraph(data)

# Sample HTML string
html_string = "<p>Hello, World!</p>"

document = Document()
parser = MyHTMLParser(document)
parser.feed(html_string)
document.save('output.docx')

Output: A DOCX file named ‘output.docx’ with the text ‘Hello, World!’ in a paragraph.

This example demonstrates the use of the HTMLParser class from the Python built-in html.parser module to parse HTML data and then use Python-Docx to add it to a Word document. This method requires a bit more effort as you need to manually handle different HTML tags.

Method 2: Using Mammoth

Mammoth is a Python package designed to convert .docx files to HTML and vice versa. It aims to provide a simple way to convert documents without needing to worry about the styles used in the original HTML.

Here’s an example:

import mammoth

html_string = "<p>This is a second example.</p>"

# Convert the HTML to DOCX
with open("output2.docx", "wb") as docx_file:
    result = mammoth.convert_to_docx(html_string)
    docx_file.write(result.value)

Output: A DOCX file named ‘output2.docx’ containing a paragraph with the text ‘This is a second example.’

This one-liner code by Mammoth is very convenient for quick conversion, handling various HTML elements and producing a clean DOCX file with proper formatting from the HTML input.

Method 3: Using Pandoc

Pandoc is a universal document converter that can be used from the command line. While not strictly a Python library, you can call it from Python using the subprocess module to convert files from one markup format to another.

Here’s an example:

import subprocess

html_string = "<p>Example for method 3.</p>"
with open("temp.html", "w") as html_file:
    html_file.write(html_string)

# Call Pandoc to convert the temporary HTML file to DOCX
subprocess.run(["pandoc", "temp.html", "-o", "output3.docx"])

Output: A DOCX file named ‘output3.docx’ with ‘Example for method 3.’ in a paragraph.

This code snippet creates a temporary HTML file, writes the HTML string to it, and then uses Pandoc (called via subprocess.run) to convert that HTML file into a DOCX document. While powerful, using Pandoc requires installation of external software and the command-line interface which might complicate deployment in some environments.

Method 4: Using docx-mailmerge

docx-mailmerge is typically used for populating a Word document template with data, but it can also be adapted for simpler HTML to DOCX conversions. You’ll need to prepare a DOCX template with merge fields that match the data keys in your HTML.

Here’s an example:

from mailmerge import MailMerge

html_content = {
    'html_content_field': 'A sample content for method 4.'
}

template = "template.docx"
document = MailMerge(template)
document.merge(**html_content)
document.write('output4.docx')

Output: A DOCX file named ‘output4.docx’ with ‘A sample content for method 4.’ placed where the corresponding merge field was in the template.

This code leverages the MailMerge class from the docx-mailmerge library to merge HTML content into a pre-defined DOCX template. This method is useful for generating DOCX documents when the structure is more complex but stable and predefined in a template.

Bonus One-Liner Method 5: Using Caracal

Caracal is a Ruby library for document generation which can be used from Python through shell commands. The Caracal library offers an elegant DSL for generating DOCX files. Although this does not provide a direct Python API, for the sake of providing diverse options, it is presented here as a one-liner shell command.

Here’s an example:

import os

html_string = "<p>Caracal gem example</p>"
os.system(f"echo '{html_string}' | caracal -o output5.docx")

Output: A DOCX file named ‘output5.docx’ with the text ‘Caracal gem example’.

This code uses the os.system call in Python to execute the Caracal command in a shell, converting the HTML to DOCX. It’s a quick and dirty way but requires a Ruby environment set up with the Caracal gem installed.

Summary/Discussion

  • Method 1: Python-Docx. Best for full control over document generation. Requires manual handling of HTML elements. Less efficient for complex HTML and time-consuming for large documents.
  • Method 2: Mammoth. Aimed at converting existing DOCX to HTML and vice versa. Streamlined for relatively simple HTML. May not handle complex cases with the same fidelity as Custom Python-Docx implementation.
  • Method 3: Pandoc. Extremely powerful and versatile. Best for large-scale or complex documents. Requires external dependencies and might have a steeper learning curve.
  • Method 4: docx-mailmerge. Ideal for template-based DOCX generation. Not suitable for dynamic document structures where the template cannot be predefined.
  • Method 5: Caracal. One-liner shell command. Requires Ruby environment and is less practical for a Python-only workflow.