The Complete Production SOP: How to Deploy and Run python-docx Custom Table Styler in Autonomous AI Agents

---
name: "python-docx-table-styler"
description: "Design polished, borderless, and shaded data tables in Microsoft Word using Python."
metadata:
  author: "python-openxml"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "style docx table python"
  - "set cell background color python-docx"
  - "set table column widths docx"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# python-docx Custom Table Styler

Applies custom XML formatting to python-docx tables: cell shading (w:shd), custom cell borders (w:tcBorders), vertical alignment, and cell margins.

## When to Invoke
Invoke this skill whenever you need to:
- style docx table python
- set cell background color python-docx
- set table column widths docx

## Execution SOP & Rules
1. Set column widths explicitly on every cell within the column to avoid Word width auto-reset.
2. Apply background color shading using parse_xml(r'<w:shd {} w:fill="HEX_CODE"/>'.format(nsdecls('w'))).
3. Configure cell vertical alignment with cell.vertical_alignment = WD_ALIGN_VERTICAL.CENTER.
4. Enable table.rows[0].cantSplit = True and trPr.append(parse_xml(r'<w:tblHeader {}/>'.format(nsdecls('w')))) for repeat headers.

## Verification Checklist
- Ensure `docx.oxml.ns.nsdecls` and `docx.oxml.parse_xml` are explicitly imported.
- Validate that no code calls `cell.color` or `cell.background`.
- Run local python syntax and docx serialization tests.

import docx
from docx.oxml import parse_xml
from docx.oxml.ns import nsdecls

test_elem = parse_xml(r'<w:shd {} w:fill="F2F2F2"/>'.format(nsdecls('w')))
assert test_elem.tag.endswith('shd')
print('python-docx OOXML engine verified successfully.')

from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.table import WD_ALIGN_VERTICAL
from docx.oxml import parse_xml
from docx.oxml.ns import nsdecls

def style_executive_table(table, col_widths, header_bg="1F4E79", alt_bg="F9FAFB"):
    """Applies deterministic styling conforming to python-docx-table-styler SOP."""
    # 1. Enforce column widths per cell across all rows
    for row in table.rows:
        for idx, width in enumerate(col_widths):
            row.cells[idx].width = width
            row.cells[idx].vertical_alignment = WD_ALIGN_VERTICAL.CENTER
    
    # 2. Style Header Row (CantSplit + TblHeader + Fill)
    hdr = table.rows[0]
    hdr.cantSplit = True
    hdr._tr.get_or_add_trPr().append(parse_xml(r'<w:tblHeader {}/>'.format(nsdecls('w'))))
    for cell in hdr.cells:
        shd = parse_xml(r'<w:shd {} w:fill="{}"/>'.format(nsdecls('w'), header_bg))
        cell._tc.get_or_add_tcPr().append(shd)
        for p in cell.paragraphs:
            for run in p.runs:
                run.font.bold = True
                run.font.color.rgb = RGBColor(255, 255, 255)

    # 3. Zebra striping for data rows
    for r_idx, row in enumerate(table.rows[1:], start=1):
        row.cantSplit = True
        if r_idx % 2 == 0:
            for cell in row.cells:
                shd = parse_xml(r'<w:shd {} w:fill="{}"/>'.format(nsdecls('w'), alt_bg))
                cell._tc.get_or_add_tcPr().append(shd)

import pytest
from docx import Document
from docx.shared import Inches
from table_formatter import style_executive_table

def test_table_styling_xml():
    doc = Document()
    table = doc.add_table(rows=3, cols=2)
    widths = [Inches(2.0), Inches(4.0)]
    style_executive_table(table, widths)
    
    # Assert XML elements exist
    for row in table.rows:
        for idx, cell in enumerate(row.cells):
            assert cell.width == widths[idx]
            tcPr = cell._tc.get_or_add_tcPr()
            assert tcPr is not None
            
    hdr_tcPr = table.rows[0].cells[0]._tc.get_or_add_tcPr()
    assert any(elem.tag.endswith('shd') for elem in hdr_tcPr)
    doc.save("test_output.docx")