Python-docx: автоматизация обработки Word документов

Расширенные примеры использования python-docx

Создание документа с оглавлением (TOC)

python-docx не имеет встроенной поддержки оглавления (поле TOC), но можно добавить поле вручную через XML. Пример:

from docx import Document
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

doc = Document()
doc.add_heading('Глава 1', level=1)
doc.add_paragraph('Текст главы 1')
doc.add_heading('Глава 2', level=1)
doc.add_paragraph('Текст главы 2')

# Вставка поля TOC в пустой абзац
p = doc.add_paragraph()
run = p.add_run()
fldChar1 = OxmlElement('w:fldChar')
fldChar1.set(qn('w:fldCharType'), 'begin')
run._r.append(fldChar1)

run2 = p.add_run()
instrText = OxmlElement('w:instrText')
instrText.set(qn('xml:space'), 'preserve')
instrText.text = ' TOC \\o "1-3" \\h \\z \\u '
run2._r.append(instrText)

run3 = p.add_run()
fldChar2 = OxmlElement('w:fldChar')
fldChar2.set(qn('w:fldCharType'), 'end')
run3._r.append(fldChar2)

doc.save('toc_doc.docx')

После открытия в Word нужно обновить поля (Ctrl+A, F9). В коде используется работа с XML OpenXML для создания поля.

Использование закладок (bookmarks)

Для создания закладок также требуется манипуляция с XML:

from docx import Document
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

doc = Document()
p = doc.add_paragraph('Текст с закладкой')
run = p.runs[0]

# Создаём элемент bookmarkStart
bm_start = OxmlElement('w:bookmarkStart')
bm_start.set(qn('w:id'), '0')
bm_start.set(qn('w:name'), 'MyBookmark')
run._r.addprevious(bm_start)

# bookmarkEnd
bm_end = OxmlElement('w:bookmarkEnd')
bm_end.set(qn('w:id'), '0')
run._r.addnext(bm_end)

doc.save('bookmark.docx')

После вставки закладки на неё можно ссылаться из гиперссылок или макросов Word.

Объединение нескольких документов

Можно скопировать содержимое одного документа в другой, используя внутренние объекты:

from docx import Document

doc1 = Document('doc1.docx')
doc2 = Document('doc2.docx')

for element in doc2.element.body:
    doc1.element.body.append(element)

doc1.save('merged.docx')

Внимание: этот способ копирует всё тело документа, включая секции и колонтитулы, что может нарушить структуру. Рекомендуется копировать только содержимое (параграфы, таблицы) через изучение структуры.

Создание сложной таблицы с объединением ячеек

Для объединения ячеек используйте методы merge:

from docx import Document
from docx.shared import Inches

doc = Document()
table = doc.add_table(rows=3, cols=3)
table.cell(0, 0).merge(table.cell(0, 1))
table.cell(0, 0).text = 'Объединённая ячейка'
table.cell(1, 0).text = 'A'
table.cell(1, 1).text = 'B'
table.cell(1, 2).text = 'C'
# Установка стиля
from docx.enum.table import WD_TABLE_ALIGNMENT
table.alignment = WD_TABLE_ALIGNMENT.CENTER
doc.save('merged_table.docx')

Метод merge принимает другую ячейку и возвращает объект объединённой ячейки. После объединения индексы строк/столбцов могут сместиться.

Заполнение шаблона (mail merge) с помощью замены текста

Простой способ: подготовить документ с плейсхолдерами вида {{name}} и заменить их:

from docx import Document

doc = Document('template.docx')
placeholders = {'{{name}}': 'Анна', '{{city}}': 'Москва'}

for paragraph in doc.paragraphs:
    for key, value in placeholders.items():
        if key in paragraph.text:
            paragraph.text = paragraph.text.replace(key, value)

# Также замена в таблицах
for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            for key, value in placeholders.items():
                if key in cell.text:
                    cell.text = cell.text.replace(key, value)

doc.save('filled.docx')

Недостаток: при такой замене теряется форматирование исходного текста (run properties). Для сохранения форматирования нужно работать с XML каждого run.

Работа с XML напрямую (пример: изменение цвета страницы)

Можно модифицировать низкоуровневые свойства документа через lxml:

from docx import Document
from docx.oxml.ns import qn

doc = Document()
section = doc.sections[0]
sectPr = section._sectPr

# Добавляем цвет фона страницы
sectPr.set(qn('w:pgBorders'), '')

# Или добавить элемент background
from lxml import etree
bg = etree.SubElement(sectPr, qn('w:background'))
bg.set(qn('w:color'), 'FFFF00')

doc.save('colored_bg.docx')

Эти манипуляции требуют знания структуры OOXML.

Создание нумерованного или маркированного списка

from docx import Document
from docx.enum.text import WD_NUMBER_STYLE
from docx.oxml.ns import qn
from docx.oxml import OxmlElement

doc = Document()
# Для списка используем абзацы с отступом и стилем List Number
for i in range(1, 4):
    p = doc.add_paragraph(f'Пункт {i}', style='List Number')
doc.save('numbered_list.docx')

Можно также создавать многоуровневые списки, настраивая numPr через XML.

Результат выполнения кода (пример вывода на консоль)

Некоторые примеры не возвращают результат в консоль, а создают файл. Для демонстрации можно использовать следующий код чтения текста:

from docx import Document
doc = Document('example.docx')
for p in doc.paragraphs:
    print(p.text)

Привет, мир!