DOCX utilities¶

The utkit.utils.docx module provides utilities for working with Word documents, including extracting embedded images from .docx files.

Installation¶

python-docx is required for DOCX operations. Install it with the standard extra:

pip install "utkit[standard]"

Or with uv:

uv add "utkit[standard]"

python-docx is included in the standard extra category.

Quick start¶

import tempfile
from utkit.utils.docx import fetch_docx_images

docx_path = "document.docx"
temp_dir = None

try:
    temp_dir = tempfile.mkdtemp(prefix="docx_images_")
    saved_files = fetch_docx_images(docx_path, temp_dir)

    # --- Post-processing operations (images are accessible here) ---
    for filepath in saved_files:
        print(f"Post-processing: {filepath}")
        # Your operations here (upload, resize, OCR, etc.)

    print(f"All operations completed. Images were in: {temp_dir}")
finally:
    if temp_dir and os.path.exists(temp_dir):
        shutil.rmtree(temp_dir)

`fetch_docx_images`¶

Extract all embedded images from a .docx file into a temporary directory for post-processing.

def fetch_docx_images(docx_path: str, temp_dir: str) -> list[str]

Parameter	Type	Description
`docx_path`	`str`	Path to the `.docx` file to extract images from.
`temp_dir`	`str`	Directory where extracted images will be saved.

Returns: list[str] — List of file paths for the extracted images.

Raises: - FileNotFoundError — If the docx file does not exist. - ValueError — If the file is not a valid .docx document. - PermissionError — If the temp directory is not writable. - OSError — For other I/O related failures.

Basic usage¶

import tempfile
import os
from utkit.utils.docx import fetch_docx_images

docx_path = "report.docx"
temp_dir = tempfile.mkdtemp(prefix="docx_images_")

try:
    saved_files = fetch_docx_images(docx_path, temp_dir)
    print(f"Extracted {len(saved_files)} images")

    for filepath in saved_files:
        print(f"Image: {filepath}")
finally:
    if os.path.exists(temp_dir):
        import shutil
        shutil.rmtree(temp_dir)

With post-processing operations¶

import tempfile
from utkit.utils.docx import fetch_docx_images

docx_path = "presentation.docx"
temp_dir = None

try:
    temp_dir = tempfile.mkdtemp(prefix="docx_images_")
    saved_files = fetch_docx_images(docx_path, temp_dir)

    # --- Post-processing operations (images are accessible here) ---
    for filepath in saved_files:
        print(f"Post-processing: {filepath}")
        # Your operations here (upload, resize, OCR, etc.)

    print(f"All operations completed. Images were in: {temp_dir}")
finally:
    if temp_dir and os.path.exists(temp_dir):
        import shutil
        shutil.rmtree(temp_dir)

Error handling¶

import tempfile
from utkit.utils.docx import fetch_docx_images

try:
    temp_dir = tempfile.mkdtemp(prefix="docx_images_")
    saved_files = fetch_docx_images("missing.docx", temp_dir)
except FileNotFoundError as e:
    print(f"File not found: {e}")
except ValueError as e:
    print(f"Invalid document: {e}")
except PermissionError as e:
    print(f"Permission error: {e}")