docx2python

The document structure is preserved as nested lists. Paragraphs are always at depth 4 (output.body[i][j][k][l]).

Structure Hierarchy:

• document (List)
  • table (List)
    • row (List)
      • cell (List)
        • paragraph (String, Run, or Par instance)

If a document contains no tables, the body will appear as a single-cell table containing all content. Tables are always returned as $n imes m$ (rows $ imes$ columns) lists. If duplicate_merged_cells=True, merged cells are filled with content from adjacent cells; if False, they are filled with empty cells.

[
  # document
  [
    # table
    [
      # row
      [
        # cell
        "Paragraph 1",
        "Paragraph 2"
      ]
    ]
  ]
]

The docx2python function unzips a .docx file and extracts headers, footers, text, footnotes, endnotes, properties, comments, and images into a DocxContent object.

It is recommended to use the function as a context manager (with ... as) to ensure the underlying zipfile is closed properly. Alternatively, you can call .close() explicitly.

Basic Usage:

from docx2python import docx2python

# Using context management (recommended)
with docx2python('path/to/file.docx') as docx_content:
    print(docx_content.text)

# Manual close
docx_content = docx2python('path/to/file.docx')
print(docx_content.text)
docx_content.close()

from docx2python import docx2python

# extract docx content
with docx2python('path/to/file.docx') as docx_content:
    print(docx_content.text)

You can extract images in two ways: by providing an image_folder argument during initialization, or by calling .save_images() on the resulting DocxContent object.

Option 1: Specify folder during initialization

with docx2python('path/to/file.docx', 'path/to/image_directory') as docx_content:
    print(docx_content.text)

Option 2: Use save_images()

with docx2python('path/to/file.docx') as docx_content:
    docx_content.save_images('path/to/image/directory')

Option 3: Manual extraction from the images dictionary If you need to handle the binary data yourself, access the .images attribute, which maps image names to their binary content:

for name, image in result.images.items():
    with open(name, 'wb') as image_destination:
        image_destination.write(image)

Install the package using pip to begin extracting content from .docx files.

pip install docx2python

By setting html=True, docx2python converts basic font styles into HTML tags.

Supported tags include:

• <i> (italic), <b> (bold), <u> (underline), <s> (strike)
• <sup> (superscript), <sub> (subscript)
• <span style="font-variant: small-caps"> (small caps)
• <span style="text-transform:uppercase"> (all caps)
• <span style="background-color: yellow"> (highlighted)
• <span style="font-size:32"> (font size)
• <span style="color:#ff0000"> (colored text)

Note: Hyperlinks are always exported as HTML (<a href="...">link text</a>) regardless of the html setting. Special characters like &, >, and < are encoded as &, >, and < when html=True.

with docx2python('path/to/file.docx', html=True) as docx_content:
    print(docx_content.text)

The docx2python package organizes document content into a nested list structure representing the hierarchy of a .docx file. The depth of the nesting corresponds to the document elements:

[
    # document
    [
        # table (tbl)
        [
            # row (tr)
            [
                # cell (tc)
                [
                    # paragraph (p)
                    [
                        "" # text run (r)
                    ]
                ]
            ]
        ]
    ]
]

Text in table cells and text outside of a table is captured at depth=5. You can access the full tree of Par (paragraph) objects via the DepthCollector.tree property, or a simplified nested list of strings via DepthCollector.tree_text.

Use the DocxReader class to load a .docx file or a BytesIO object. This is the primary entry point for extracting content from a Word document.

Arguments:

• docx_filename: Path to the .docx file or a BytesIO object.
• html (optional): If True, converts XML to HTML. Defaults to False.
• duplicate_merged_cells (optional): If True, duplicates text in merged cells. Defaults to True.

Note that DocxReader supports the context manager pattern (with statement) to ensure the underlying zip file is closed correctly.

from docx2python import DocxReader

with DocxReader('example.docx') as reader:
    # Use reader here
    pass

You can retrieve comments from a Word document using the comments attribute of the DocxContent object. This is best used within a context manager to ensure proper resource handling.

Each comment is returned as a tuple containing: (reference_text, author, date, comment_text).

from docx2python import docx2python

with docx2python('path/to/file.docx') as docx_content:
    print(docx_content.comments)

The docx2python.iterators module provides helper functions to navigate and manipulate the nested list structures (tables) returned by docx2python.

• enum_cells(tables): Iterates over cells in a table structure, yielding a tuple of indices (i, j, k) and the cell content.
• enum_at_depth(tables, depth): Iterates through the nested structure at a specific depth, yielding indices and the content at that level.

from docx2python.iterators import enum_cells

def remove_empty_paragraphs(tables):
    for (i, j, k), cell in enum_cells(tables):
        tables[i][j][k] = [x for x in cell if x]

# Example usage:
tables = [[[['a', 'b'], ['a', '', 'd', '']]]]
remove_empty_paragraphs(tables)
# Result: [[[['a', 'b'], ['a', 'd']]]]