Trying to merge cells with python-docx

Question

I'm trying to merge a bunch of cells for a docx document like so:

from docx import Document
from docx.shared import Inches

document = Document()

document.add_heading('Document Title', 0)

records = (
    (3, '101', 'Spam'),
    (7, '422', 'Eggs'),
    (4, '631', 'Spam, spam, eggs, and spam')
)

table = document.add_table(rows=3, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Qty'
hdr_cells[1].text = 'Id'
hdr_cells[2].text = 'Desc'
for qty, id, desc in records:
    row_cells = table.add_row().cells
    row_cells[0].text = str(qty)
    row_cells[1].text = id
    row_cells[2].text = desc

a = table.cell(0, 0)
b = table.cell(1, 1)
c = table.cell(2, 1)
d = table.cell(1, 2)

A = a.merge(b)
B = A.merge(c)
C = B.merge(d)

document.save('demo.docx')

But I get:

Traceback (most recent call last):
  File "pdocx_error.py", line 32, in <module>
    C = B.merge(d)
  File "/home/martin/myvenv/lib/python3.8/site-packages/docx/table.py", line 232, in merge
    merged_tc = tc.merge(tc_2)
  File "/home/martin/myvenv/lib/python3.8/site-packages/docx/oxml/table.py", line 443, in merge
    top, left, height, width = self._span_dimensions(other_tc)
  File "/home/martin/myvenv/lib/python3.8/site-packages/docx/oxml/table.py", line 639, in _span_dimensions
    raise_on_tee_shaped(self, other_tc)
  File "/home/martin/myvenv/lib/python3.8/site-packages/docx/oxml/table.py", line 632, in raise_on_tee_shaped
    raise InvalidSpanError('requested span not rectangular')
docx.exceptions.InvalidSpanError: requested span not rectangular

What's going wrong here ?

Answer 1

Let's back up a bit. Here is the table with no merges:

And here is the 1,2 cell that has to be merged:

And then executing the first 2 merges:

So then one can clearly see the requested merge would produce something that is not rectangular. A merge with the one below, however, is possible since it will produce a rect, e.g.:

a = table.cell(0, 0)
b = table.cell(1, 1)
c = table.cell(2, 1)
d = table.cell(2, 2)

A = a.merge(b)
B = A.merge(c)
C = B.merge(d)

Then the first 3 rows x 3 columns will be merged into one.