wordhelpers 0.1.0__tar.gz

wordhelpers-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.3
+Name: wordhelpers
+Version: 0.1.0
+Summary: Helpers for working with python-docx
+Author: AJ Cruz
+Author-email: 15045766-a-cruz@users.noreply.gitlab.com
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: python-docx (>=1.2.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wordhelpers.svg)](https://img.shields.io/pypi/pyversions/wordhelpers)
+[![PyPI](https://img.shields.io/pypi/v/wordhelpers.svg)](https://pypi.python.org/pypi/wordhelpers)
+[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+
+# wordhelpers
+=============
+Helper functions for [python-docx](https://python-docx.readthedocs.io/en/latest/). I found myself re-learning docx every time I wanted to use it in a project, so this provides and abstraction. You represent Word tables as a properly-formatted Python dictionary and the helper function converts it to a docx table.
+
+# Installation
+wordhelpers can be installed via poetry with: ```poetry add wordhelpers```
+or via pip with: ```pip install wordhelpers```
+
+# Usage
+For detailed documentation of the python-docx library see [python-docx](https://python-docx.readthedocs.io/en/latest/)
+
+1. Import the python-docx library into your script with:
+    ```python
+    from docx import Document
+    ```
+1. Import the helpers from this project with:
+    ```python
+    from wordhelpers import build_table, replace_placeholder_with_table
+    ```
+1. Create the docx Word document object with something like:
+    ```python
+    doc_obj = Document("a_word_template.docx")
+    ```
+1. Manipulate the document object as required (see the next section of this README for info on how to do that)
+1. When all changes to your document object are complete, write them with:
+    ```python
+    doc_obj.save("output_file.docx")
+    ```
+# Manipulating the document object
+wordhelpers provides two main functions available to your scripts:
+1. build_table(<doc_obj>, <table_dict>, <remove_leading_para>)
+1. replace_placeholder_with_table(<doc_obj>, <search_string>, <table_obj>)
+
+### build_table(<doc_obj>, <table_dict>, <remove_leading_para>)
+The purpose of this function is to allow the script author to model Word tables using Python dictionaries. If formatted properly, the module will translate the Python dictionary to the appropriate python-docx syntax and create the Word table object.
+
+The build_table function has the following arguments:
+- **<doc_obj>** - The python-docx Word document object created in step 3 of the "Usage" section above.
+- **<table_dict>** - The Word table model (Python dictionary). The expected Python dictionary format to model a Word table is:
+    ```python
+    {
+        "style": None,
+        "rows": [
+            {
+                "cells": [
+                    {
+                        "width": None,
+                        "background": None,
+                        "paragraphs": [{"style":None,"alignment": "center", "text":"Some Text"}],
+                        "table": {optional child table}
+                    },
+                    {
+                        "merge": None
+                    },
+                ]
+            }
+        ]
+    }
+    ```
+    The cell **background** attribute is optional. If supplied with a hexidecimal color code, the cell will be shaded that color.
+    
+    The cell **width** attribute is optional. If supplied with a decimal number (inches), it will hard-code that column's width to the supplied value.
+
+    The cell **table** attribute is optional. It can be used to nest tables within table cells. If "table" is provided, no other keys are required (background, paragraphs, etc).
+
+    The paragraph **style** attribute is optional. If set to anything besides None it will use the Word style referenced. The style must already exist in the source/template Word document.
+
+    The paragraph **alignment** attribute is optional. If set to ```"center"``` it will center-align the text within a cell, if set to ```"right"``` it will right-align the text within a cell
+
+    The **merge** key is optional. If used the cell will be merged with the cell above (from a dictionary view, to the left from a table view). Multiple merges can be used in a row to merge multiple cells.
+
+    By default a paragraph's **text** property will create a single-line (but wrapped) entry in the cell if the value is a string. If you would like to create a multi-line cell entry, supply the value as a list instead of a string. This will instruct the module to add a line break after each list item.
+- **<remove_leading_para>** - This is an optional argument. If not set it will default to True. MS Word tables when created automatically have an empty paragraph at the top/beginning of the table cell. This can create unwanted spacing at the top of the table. By default (value set to "True") the paragraph will be deleted. If you want to keep the paragraph (to add text to it), set this to "False".
+
+**IMPORTANT NOTE:** This adds the table object to very end of your Word file. If you want to relocate it, use the provided `replace_placeholder_with_table()` function (see below). 
+
+### replace_placeholder_with_table(<doc_obj>, <search_string>, <table_obj>)
+The purpose of this function is to search a Word file for a given string (the placeholder) and replace the string with a Word table object.
+
+The replace_placeholder_with_table function has the following arguments:
+- **<doc_obj>** - The python-docx Word document object created in step 2 of the "USING PYTHON-DOCX LIBRARY" section above.
+- **<search_string>** - The string to search for in the document object (doc_obj)
+- **<table_obj>** - The python-docx Word Table object that will replace the <search_string> in the document object (odc_obj)
+
+It will relocate the table to the placeholder and remove the placeholder.-
+
+### EXAMPLE
+We start with a Microsoft Word template named "source-template.docx" that looks like this:
+
+![Word Template](artwork/word_template.jpg)
+
+Our sample Python script looks like this:
+```python
+from docx import Document
+from dcnet_msofficetools.docx_extensions import build_table, replace_placeholder_with_table
+
+doc_obj = Document("source-template.docx")
+
+my_dictionary = {
+    "style": None,
+    "rows": [
+        {
+            "cells": [
+                {
+                    "paragraphs": [],
+                    "table": {
+                        "style": "plain",
+                        "rows": [
+                            {
+                                "cells": [
+                                    {
+                                        "background": "#506279",
+                                        "paragraphs":[{"style": "regularbold", "text": "Header 1:"}]
+                                    },
+                                    {
+                                        "background": "#506279",
+                                        "paragraphs":[{"style": "regularbold", "text": "Header 2:"}]
+                                    },
+                                    {
+                                        "background": "#506279",
+                                        "paragraphs":[{"style": "regularbold", "text": "Header 3:"}]
+                                    }
+                                ]
+                            },
+                            {
+                                "cells": [
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 1 Data 1:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 1 Data 2:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 1 Data 3:"}]
+                                    }
+                                ]
+                            },
+                            {
+                                "cells": [
+                                    {
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 2 Data 1:"}]
+                                    },
+                                    {
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 2 Data 2:"}]
+                                    },
+                                    {
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 2 Data 3:"}]
+                                    }
+                                ]
+                            },
+                            {
+                                "cells": [
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 3 Data 1:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 3 Data 2:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 3 Data 3:"}]
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+    ]
+}
+
+my_table = build_table(doc_obj, my_dictionary)
+
+replace_placeholder_with_table(doc_obj, '\[py_placeholder1\]', my_table)
+
+doc_obj.save("output_word_doc.docx")
+```
+
+We run the Python script and it produces a new Word document named "output_word_doc.docx" that looks like this:
+
+![Word Template](artwork/word_output.jpg)
+
+
+The project provides some additional docx functions that may be useful to your project:
+- ```get_para_by_string(doc_obj: _Document, search: str)```: Searches for a keyword in the docx object and returns there paragraph where the keyword is found
+- ```insert_paragraph_after(paragraph: Paragraph, text: str = None, style: str = None)```: Searches for a keyword in the docx object and inserts a new paragraph immediately after it with the supplied text
+- ```delete_paragraph(paragraph: Paragraph)```: Deletes a given paragraph (after you've inserted text after it for example)
+
+As well as the following helper functions for the dictionary table models:
+- ```insert_text_into_row(cell_text: list)```: Builds a row (dictionary) from a list of text where each list item is a column in the row. Supports "merge"
+-```insert_text_by_table_coords(table: dict, row: int, col: int, text: str)```: Inserts text into a table dictionary given the row & column numbers.
+- ```generate_table(num_rows: int, num_cols: int, header_row: list, style: str = None)```: Generates a basic table dictionary and populates the headers from a list of text (strings).

wordhelpers-0.1.0/README.md

@@ -0,0 +1,202 @@
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wordhelpers.svg)](https://img.shields.io/pypi/pyversions/wordhelpers)
+[![PyPI](https://img.shields.io/pypi/v/wordhelpers.svg)](https://pypi.python.org/pypi/wordhelpers)
+[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+
+# wordhelpers
+=============
+Helper functions for [python-docx](https://python-docx.readthedocs.io/en/latest/). I found myself re-learning docx every time I wanted to use it in a project, so this provides and abstraction. You represent Word tables as a properly-formatted Python dictionary and the helper function converts it to a docx table.
+
+# Installation
+wordhelpers can be installed via poetry with: ```poetry add wordhelpers```
+or via pip with: ```pip install wordhelpers```
+
+# Usage
+For detailed documentation of the python-docx library see [python-docx](https://python-docx.readthedocs.io/en/latest/)
+
+1. Import the python-docx library into your script with:
+    ```python
+    from docx import Document
+    ```
+1. Import the helpers from this project with:
+    ```python
+    from wordhelpers import build_table, replace_placeholder_with_table
+    ```
+1. Create the docx Word document object with something like:
+    ```python
+    doc_obj = Document("a_word_template.docx")
+    ```
+1. Manipulate the document object as required (see the next section of this README for info on how to do that)
+1. When all changes to your document object are complete, write them with:
+    ```python
+    doc_obj.save("output_file.docx")
+    ```
+# Manipulating the document object
+wordhelpers provides two main functions available to your scripts:
+1. build_table(<doc_obj>, <table_dict>, <remove_leading_para>)
+1. replace_placeholder_with_table(<doc_obj>, <search_string>, <table_obj>)
+
+### build_table(<doc_obj>, <table_dict>, <remove_leading_para>)
+The purpose of this function is to allow the script author to model Word tables using Python dictionaries. If formatted properly, the module will translate the Python dictionary to the appropriate python-docx syntax and create the Word table object.
+
+The build_table function has the following arguments:
+- **<doc_obj>** - The python-docx Word document object created in step 3 of the "Usage" section above.
+- **<table_dict>** - The Word table model (Python dictionary). The expected Python dictionary format to model a Word table is:
+    ```python
+    {
+        "style": None,
+        "rows": [
+            {
+                "cells": [
+                    {
+                        "width": None,
+                        "background": None,
+                        "paragraphs": [{"style":None,"alignment": "center", "text":"Some Text"}],
+                        "table": {optional child table}
+                    },
+                    {
+                        "merge": None
+                    },
+                ]
+            }
+        ]
+    }
+    ```
+    The cell **background** attribute is optional. If supplied with a hexidecimal color code, the cell will be shaded that color.
+    
+    The cell **width** attribute is optional. If supplied with a decimal number (inches), it will hard-code that column's width to the supplied value.
+
+    The cell **table** attribute is optional. It can be used to nest tables within table cells. If "table" is provided, no other keys are required (background, paragraphs, etc).
+
+    The paragraph **style** attribute is optional. If set to anything besides None it will use the Word style referenced. The style must already exist in the source/template Word document.
+
+    The paragraph **alignment** attribute is optional. If set to ```"center"``` it will center-align the text within a cell, if set to ```"right"``` it will right-align the text within a cell
+
+    The **merge** key is optional. If used the cell will be merged with the cell above (from a dictionary view, to the left from a table view). Multiple merges can be used in a row to merge multiple cells.
+
+    By default a paragraph's **text** property will create a single-line (but wrapped) entry in the cell if the value is a string. If you would like to create a multi-line cell entry, supply the value as a list instead of a string. This will instruct the module to add a line break after each list item.
+- **<remove_leading_para>** - This is an optional argument. If not set it will default to True. MS Word tables when created automatically have an empty paragraph at the top/beginning of the table cell. This can create unwanted spacing at the top of the table. By default (value set to "True") the paragraph will be deleted. If you want to keep the paragraph (to add text to it), set this to "False".
+
+**IMPORTANT NOTE:** This adds the table object to very end of your Word file. If you want to relocate it, use the provided `replace_placeholder_with_table()` function (see below). 
+
+### replace_placeholder_with_table(<doc_obj>, <search_string>, <table_obj>)
+The purpose of this function is to search a Word file for a given string (the placeholder) and replace the string with a Word table object.
+
+The replace_placeholder_with_table function has the following arguments:
+- **<doc_obj>** - The python-docx Word document object created in step 2 of the "USING PYTHON-DOCX LIBRARY" section above.
+- **<search_string>** - The string to search for in the document object (doc_obj)
+- **<table_obj>** - The python-docx Word Table object that will replace the <search_string> in the document object (odc_obj)
+
+It will relocate the table to the placeholder and remove the placeholder.-
+
+### EXAMPLE
+We start with a Microsoft Word template named "source-template.docx" that looks like this:
+
+![Word Template](artwork/word_template.jpg)
+
+Our sample Python script looks like this:
+```python
+from docx import Document
+from dcnet_msofficetools.docx_extensions import build_table, replace_placeholder_with_table
+
+doc_obj = Document("source-template.docx")
+
+my_dictionary = {
+    "style": None,
+    "rows": [
+        {
+            "cells": [
+                {
+                    "paragraphs": [],
+                    "table": {
+                        "style": "plain",
+                        "rows": [
+                            {
+                                "cells": [
+                                    {
+                                        "background": "#506279",
+                                        "paragraphs":[{"style": "regularbold", "text": "Header 1:"}]
+                                    },
+                                    {
+                                        "background": "#506279",
+                                        "paragraphs":[{"style": "regularbold", "text": "Header 2:"}]
+                                    },
+                                    {
+                                        "background": "#506279",
+                                        "paragraphs":[{"style": "regularbold", "text": "Header 3:"}]
+                                    }
+                                ]
+                            },
+                            {
+                                "cells": [
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 1 Data 1:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 1 Data 2:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 1 Data 3:"}]
+                                    }
+                                ]
+                            },
+                            {
+                                "cells": [
+                                    {
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 2 Data 1:"}]
+                                    },
+                                    {
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 2 Data 2:"}]
+                                    },
+                                    {
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 2 Data 3:"}]
+                                    }
+                                ]
+                            },
+                            {
+                                "cells": [
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 3 Data 1:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 3 Data 2:"}]
+                                    },
+                                    {
+                                        "background": "#D5DCE4",
+                                        "paragraphs":[{"style": "No Spacing", "text": "Row 3 Data 3:"}]
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+    ]
+}
+
+my_table = build_table(doc_obj, my_dictionary)
+
+replace_placeholder_with_table(doc_obj, '\[py_placeholder1\]', my_table)
+
+doc_obj.save("output_word_doc.docx")
+```
+
+We run the Python script and it produces a new Word document named "output_word_doc.docx" that looks like this:
+
+![Word Template](artwork/word_output.jpg)
+
+
+The project provides some additional docx functions that may be useful to your project:
+- ```get_para_by_string(doc_obj: _Document, search: str)```: Searches for a keyword in the docx object and returns there paragraph where the keyword is found
+- ```insert_paragraph_after(paragraph: Paragraph, text: str = None, style: str = None)```: Searches for a keyword in the docx object and inserts a new paragraph immediately after it with the supplied text
+- ```delete_paragraph(paragraph: Paragraph)```: Deletes a given paragraph (after you've inserted text after it for example)
+
+As well as the following helper functions for the dictionary table models:
+- ```insert_text_into_row(cell_text: list)```: Builds a row (dictionary) from a list of text where each list item is a column in the row. Supports "merge"
+-```insert_text_by_table_coords(table: dict, row: int, col: int, text: str)```: Inserts text into a table dictionary given the row & column numbers.
+- ```generate_table(num_rows: int, num_cols: int, header_row: list, style: str = None)```: Generates a basic table dictionary and populates the headers from a list of text (strings).

wordhelpers-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "wordhelpers"
+version = "0.1.0"
+description = "Helpers for working with python-docx"
+authors = [
+    {name = "AJ Cruz",email = "15045766-a-cruz@users.noreply.gitlab.com"}
+]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "python-docx (>=1.2.0,<2.0.0)",
+    "pydantic (>=2.12.5,<3.0.0)"
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+black = "^26.1.0"
+

wordhelpers-0.1.0/wordhelpers/__init__.py

@@ -0,0 +1,308 @@
+# Built-In imports
+import re
+
+# Third-party imports
+from .pydantic_models import WordTableModel
+from docx import Document
+from docx.document import Document as _Document
+from docx.table import Table, _Cell
+from docx.text.paragraph import Paragraph
+from docx.oxml.ns import nsdecls
+from docx.oxml import parse_xml, OxmlElement
+from docx.shared import Inches, Cm
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+
+
+def cell_shader(cell: _Cell, hex_color: tuple[int, int, int]) -> None:
+    shading_elm = parse_xml(
+        r'<w:shd {} w:fill="{}"/>'.format(nsdecls("w"), hex_color.strip("#").upper())
+    )
+    cell._tc.get_or_add_tcPr().append(shading_elm)
+
+
+def delete_paragraph(paragraph: Paragraph) -> None:
+    """
+    Function to delete a given paragraph in a Word document.
+    Requires as input the doxc paragraph object.
+    """
+    p = paragraph._element
+    p.getparent().remove(p)
+    p._p = p._element = None
+
+
+def set_col_width(table: Table, column: int, width: int | float) -> None:
+    width = Inches(float(width))
+    for row in table.rows:
+        row.cells[column].width = width
+
+
+def find_para_by_string(doc_obj: _Document, search: str) -> int:
+    """
+    Function to find a string in a Word document and return the paragraph
+    number. Receives as input the Word document object (using docx module) and
+    a search string.
+    """
+    for i, p in enumerate(doc_obj.paragraphs):
+        if re.match(search, p.text):
+            return i
+
+
+def get_para_by_string(doc_obj: _Document, search: str) -> Paragraph:
+    """
+    Function to find a string in a Word document and return the paragraph.
+    Receives as input the Word document object (using docx module) and
+    a search string.
+    """
+    for p in doc_obj.paragraphs:
+        if re.match(search, p.text):
+            return p
+
+
+def replace_placeholder_with_table(
+    doc_obj: _Document, placeholder: str, table: Table
+) -> None:
+    """
+    Function to relocate a Word table object to immediately follow a given
+    reference paragraph identified by the placeholder. Receives as input the
+    placeholder string and the Word table object (using docx module).
+    After moving the Word table after the placeholder paragraph, delete the
+    placeholder paragraph.
+    """
+    # Locate the paragraph from the supplied placeholder text
+    paragraph: Paragraph = get_para_by_string(doc_obj, placeholder)
+    if not paragraph:
+        print(f'WARNING: Could not locate placeholder "{placeholder}"')
+    else:
+        # Move the Word table to a new paragraph immediately after the placeholder paragraph
+        paragraph._p.addnext(table._tbl)
+        # Delete the placeholder paragraph
+        delete_paragraph(paragraph)
+
+
+def build_table(
+    docx_obj: _Document | Table, table_dict: dict, remove_leading_para: bool = True
+) -> Table:
+    """
+    Convert a WordTableModel-style dictionary into a Word table object.
+    Supports nested tables and merged cells within a row.
+    Automatically sets nested table widths to fill merged cells.
+    """
+    raw_table = WordTableModel.model_validate(table_dict)
+
+    # Create table if docx_obj is _Document
+    if isinstance(docx_obj, _Document):
+        table = docx_obj.add_table(
+            rows=len(raw_table.rows),
+            cols=len(raw_table.rows[0].cells) if raw_table.rows else 0,
+        )
+    elif isinstance(docx_obj, Table):
+        table = docx_obj
+    else:
+        raise ValueError(f"docx_obj must be _Document or Table, got {type(docx_obj)}")
+
+    # Apply table style
+    if raw_table.style:
+        table.style = raw_table.style
+
+    for i, row in enumerate(raw_table.rows):
+        table_row = table.rows[i]
+        col_idx = 0
+
+        while col_idx < len(row.cells):
+            cell = row.cells[col_idx]
+            table_cell = table_row.cells[col_idx]
+
+            # --- Handle merged cells ---
+            if isinstance(cell, str) and cell.lower() == "merge":
+                left_cell = table_row.cells[col_idx - 1]
+                left_cell.merge(table_cell)
+                col_idx += 1
+                continue
+
+            # --- Regular cell formatting ---
+            if cell.background_color:
+                cell_shader(table_cell, cell.background_color)
+            if cell.width:
+                set_col_width(table, col_idx, cell.width)
+
+            # --- Paragraphs ---
+            for para_idx, para in enumerate(cell.paragraphs):
+                if para_idx >= len(table_cell.paragraphs):
+                    p = table_cell.add_paragraph()
+                else:
+                    p = table_cell.paragraphs[para_idx]
+
+                if isinstance(para.text, str):
+                    p.text = para.text
+                elif isinstance(para.text, list):
+                    # Multi-line text with breaks
+                    p.text = ""
+                    for idx, run_text in enumerate(para.text):
+                        run = p.add_run(run_text)
+                        if idx < len(para.text) - 1:
+                            run.add_break()
+
+                # Paragraph alignment
+                if para.alignment:
+                    alignment_map = {
+                        "left": WD_ALIGN_PARAGRAPH.LEFT,
+                        "center": WD_ALIGN_PARAGRAPH.CENTER,
+                        "right": WD_ALIGN_PARAGRAPH.RIGHT,
+                        "justify": WD_ALIGN_PARAGRAPH.JUSTIFY,
+                        "distribute": WD_ALIGN_PARAGRAPH.DISTRIBUTE,
+                    }
+                    p.alignment = alignment_map.get(para.alignment.value.lower())
+
+                # Paragraph style
+                if para.style:
+                    p.style = para.style
+
+            # --- Nested table ---
+            if cell.table:
+                # Compute width of merged cell
+                merged_cols = 1
+                temp_idx = col_idx + 1
+                while (
+                    temp_idx < len(row.cells)
+                    and isinstance(row.cells[temp_idx], str)
+                    and row.cells[temp_idx].lower() == "merge"
+                ):
+                    merged_cols += 1
+                    temp_idx += 1
+
+                # Sum widths of merged columns, or use default
+                parent_width = sum(
+                    table.columns[col_idx + k].width or Cm(2.5)
+                    for k in range(merged_cols)
+                )
+
+                nested_rows = len(cell.table.rows)
+                nested_cols = len(cell.table.rows[0].cells) if cell.table.rows else 0
+
+                nested_table = table_cell.add_table(rows=nested_rows, cols=nested_cols)
+                nested_table.allow_autofit = False  # We'll set widths manually
+
+                # Assign column widths proportionally
+                nested_col_width = parent_width / nested_cols
+                for col in nested_table.columns:
+                    for nested_cell in col.cells:
+                        nested_cell.width = nested_col_width
+
+                # Recursively build nested table
+                build_table(nested_table, cell.table.model_dump())
+
+                # Remove leading paragraph in merged/nested cell
+                if remove_leading_para and table_cell.paragraphs:
+                    delete_paragraph(table_cell.paragraphs[0])
+
+            col_idx += 1
+
+    # Remove leading empty paragraph in document
+    if isinstance(docx_obj, _Document) and remove_leading_para and docx_obj.paragraphs:
+        if not docx_obj.paragraphs[0].text.strip():
+            delete_paragraph(docx_obj.paragraphs[0])
+
+    return table
+
+
+def insert_paragraph_after(paragraph: Paragraph, text: str = None, style: str = None):
+    """
+    Insert a new paragraph after the given paragraph.
+    """
+
+    # Create a new empty <w:p> element
+    new_p = OxmlElement("w:p")
+
+    # Insert the new <w:p> after the given paragraph’s <w:p>
+    paragraph._p.addnext(new_p)
+
+    # Wrap the XML element as a python-docx Paragraph
+    new_para = Paragraph(new_p, paragraph._parent)
+
+    # Set text and style
+    if text:
+        new_para.add_run(text)
+    if style:
+        new_para.style = style
+
+
+# TABLE (DICTIONARY) SHORTCUTS
+def insert_text_into_row(cell_text: list) -> dict:
+    """
+    Generate a table row dictionary from a list of text strings.
+    Each string in the list becomes a cell in the row.
+    Assumes no styling.
+
+    :param cell_text: A list of text strings for each cell in the row. Use "merge" to indicate merged cells.
+    :type cell_text: list
+    :return: A dictionary representing the table row.
+    :rtype: dict
+    """
+
+    row: dict = {"cells": []}
+    for text in cell_text:
+        if text.lower() == "merge":
+            row["cells"].append("merge")
+            continue
+
+        row["cells"].append(
+            {
+                "paragraphs": [
+                    {
+                        "text": [text],
+                    },
+                ],
+            }
+        )
+
+    return row
+
+
+def insert_text_by_table_coords(table: dict, row: int, col: int, text: str) -> dict:
+    table["rows"][row]["cells"][col]["paragraphs"][0]["text"] = [text]
+    return table
+
+
+def generate_table(
+    num_rows: int, num_cols: int, header_row: list, style: str = None
+) -> dict:
+    """
+    Generate a basic table dictionary with specified number of rows and columns.
+    Each cell contains empty text.
+
+    :param num_rows: Number of rows in the table.
+    :type num_rows: int
+    :param num_cols: Number of columns in the table.
+    :type num_cols: int
+    :param header_row: A list of text strings for the header row.
+    :type header_row: list
+    :param style: The style to apply to the table.
+    :type style: str
+    :return: A dictionary representing the table.
+    :rtype: dict
+    """
+
+    table: dict = {"rows": []}
+
+    if style:
+        table["style"] = style
+
+    for _ in range(num_rows):
+        row: dict = {"cells": []}
+        for _ in range(num_cols):
+            row["cells"].append(
+                {
+                    "paragraphs": [
+                        {
+                            "text": [""],
+                        },
+                    ],
+                }
+            )
+        table["rows"].append(row)
+
+    if header_row:
+        for col_idx, header_text in enumerate(header_row):
+            table["rows"][0]["cells"][col_idx]["paragraphs"][0]["text"] = [header_text]
+
+    return table

wordhelpers-0.1.0/wordhelpers/pydantic_models.py

@@ -0,0 +1,57 @@
+# Built-In Imports
+import re
+from enum import Enum
+from typing import Optional
+
+# Third-Party Imports
+from pydantic import BaseModel, field_validator, Field
+
+
+class AlignmentEnum(str, Enum):
+    left = "left"
+    center = "center"
+    right = "right"
+    justify = "justify"
+    distribute = "distribute"
+
+
+class WordParagraphModel(BaseModel):
+    style: str | None = None
+    alignment: AlignmentEnum | None = None
+    text: list[str] = Field(default_factory=list)
+
+
+class WordCellModel(BaseModel):
+    width: int | None = None
+    background_color: str | None = None
+    paragraphs: list[WordParagraphModel] = Field(default_factory=list)
+    table: Optional["WordTableModel"] | None = None  # forward reference
+
+    @field_validator("background_color")
+    @classmethod
+    def validate_hex_color(cls, v):
+        if v is None:
+            return v  # allow None
+        if not isinstance(v, str):
+            raise ValueError("background_color must be a string")
+        # regex: # followed by 3 or 6 hex digits
+        if not re.fullmatch(r"#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})", v):
+            raise ValueError(f"'{v}' is not a valid hex color")
+        return v
+
+
+class WordRowModel(BaseModel):
+    cells: list[WordCellModel | str] = Field(default_factory=list)
+
+    @field_validator("cells")
+    @classmethod
+    def validate_cells(cls, v):
+        if isinstance(v, str):
+            if not v.strip().lower() == "merge":
+                raise ValueError("If a cell is a string, it must be 'merge'")
+        return v
+
+
+class WordTableModel(BaseModel):
+    style: str | None = None
+    rows: list[WordRowModel] = Field(default_factory=list)