wordhelpers 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

wordhelpers/__init__.py

@@ -79,6 +79,45 @@ def replace_placeholder_with_table(
         delete_paragraph(paragraph)
 
 
+def inject_table(
+    doc_obj: _Document,
+    table: dict | WordTableModel,
+    placeholder: str,
+    remove_leading_para: bool = True,
+    remove_placeholder: bool = True,
+) -> 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:
+        raise ValueError(
+            f'WARNING: Could not locate placeholder "{placeholder}"'
+        )
+
+    # Build the word table and add it to the end of the document
+    table = (
+        build_table(
+            doc_obj, table, remove_leading_para=remove_leading_para
+        )
+        if isinstance(table, dict)
+        else build_table(doc_obj, table.model_dump(), remove_leading_para=remove_leading_para)
+    )
+
+    # Move the Word table to a new paragraph immediately after the placeholder paragraph
+    paragraph._p.addnext(table._tbl)
+
+    if remove_placeholder:
+        # Delete the placeholder paragraph
+        delete_paragraph(paragraph)
+
+
 def build_table(
     docx_obj: _Document | Table, table_dict: dict, remove_leading_para: bool = True
 ) -> Table:

wordhelpers/pydantic_models.py

@@ -1,10 +1,12 @@
 # Built-In Imports
+from __future__ import annotations
 import re
 from enum import Enum
 from typing import Optional
+import json
 
 # Third-Party Imports
-from pydantic import BaseModel, field_validator, Field
+from pydantic import BaseModel, field_validator, Field, ConfigDict
 
 
 class AlignmentEnum(str, Enum):
@@ -16,12 +18,14 @@ class AlignmentEnum(str, Enum):
 
 
 class WordParagraphModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
     style: str | None = None
     alignment: AlignmentEnum | None = None
-    text: list[str] = Field(default_factory=list)
+    text: list[str] | str = Field(default_factory=list)
 
 
 class WordCellModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
     width: int | None = None
     background_color: str | None = None
     paragraphs: list[WordParagraphModel] = Field(default_factory=list)
@@ -41,11 +45,13 @@ class WordCellModel(BaseModel):
 
 
 class WordRowModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
     cells: list[WordCellModel | str] = Field(default_factory=list)
 
     @field_validator("cells")
     @classmethod
     def validate_cells(cls, v):
+        # The only valid string value is "merge"
         if isinstance(v, str):
             if not v.strip().lower() == "merge":
                 raise ValueError("If a cell is a string, it must be 'merge'")
@@ -53,5 +59,263 @@ class WordRowModel(BaseModel):
 
 
 class WordTableModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True, frozen=False)
     style: str | None = None
     rows: list[WordRowModel] = Field(default_factory=list)
+
+    def add_row(
+        self,
+        width: int,
+        text: list[str] = [],
+        merge_cols: list[int] = [],
+        background_color: str | None = None,
+        style: str | None = None,
+        alignment: AlignmentEnum | None = None,
+    ) -> None:
+
+        # Make sure width is same as existing rows if any
+        if self.rows:
+            existing_width = len(self.rows[0].cells)
+            if width != existing_width:
+                raise ValueError(
+                    f"New row width {width} does not match existing row width {existing_width}"
+                )
+
+        # Make sure text length is less than the row width minus merged columns
+        num_merge_cols = len(merge_cols)
+        if len(text) > width - num_merge_cols:
+            raise ValueError(
+                f"Text length {len(text)} exceeded expected length {width - num_merge_cols} based on width and merge_cols"
+            )
+
+        # Make sure merge_cols are valid
+        for col in merge_cols:
+            if not isinstance(col, int):
+                raise ValueError(f"merge_cols must contain integers, got: {type(col)}")
+            if col < 0 or col >= width:
+                raise ValueError(f"merge_cols contains invalid column index: {col}")
+
+        # Build the cells
+        cells: list = []
+        for i in range(width):
+            if i in merge_cols:
+                # Insert a merge placeholder
+                cells.append("merge")
+            else:
+                # Build a normal cell
+                paragraphs: list = []
+                if text:
+                    paragraphs = [
+                        WordParagraphModel(
+                            style=style, alignment=alignment, text=[text.pop(0)]
+                        )
+                    ]
+                cells.append(
+                    WordCellModel(
+                        background_color=background_color, paragraphs=paragraphs
+                    )
+                )
+        # Re-build the rows
+        rows: list = self.rows.copy()
+        rows.append(WordRowModel(cells=cells))
+        self.rows = rows
+
+    def add_text_to_row(
+        self,
+        row_index: int,
+        text: list[str],
+        style: str | None = None,
+        alignment: AlignmentEnum | None = None,
+    ) -> None:
+        # Validate row_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+
+        # Make sure text length is less than the row width minus merged columns
+        num_merge_cols = len(
+            [
+                cell
+                for cell in self.rows[row_index].cells
+                if isinstance(cell, str) and cell == "merge"
+            ]
+        )
+        width = len(self.rows[row_index].cells)
+        if len(text) > width - num_merge_cols:
+            raise ValueError(
+                f"Text length {len(text)} exceeded expected length {width - num_merge_cols} based on width and merge_cols"
+            )
+
+        rows = self.rows.copy()
+        row = rows[row_index]
+        for cell in row.cells:
+            if isinstance(cell, str) and cell == "merge":
+                continue  # Skip merge cells
+            if text:
+                cell.paragraphs.append(
+                    WordParagraphModel(
+                        style=style, alignment=alignment, text=[text.pop(0)]
+                    )
+                )
+
+        self.rows = rows
+
+    def add_text_to_cell(
+        self,
+        row_index: int,
+        col_index: int,
+        text: str,
+        style: str | None = None,
+        alignment: AlignmentEnum | None = None,
+    ) -> None:
+        # Validate row_index and col_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+        rows = self.rows.copy()
+        row = rows[row_index]
+        if col_index < 0 or col_index >= len(row.cells):
+            raise IndexError(f"Column index {col_index} out of range")
+
+        cell = row.cells[col_index]
+        if isinstance(cell, str) and cell == "merge":
+            raise ValueError("Cannot add text to a merged cell")
+
+        cell.paragraphs.append(
+            WordParagraphModel(style=style, alignment=alignment, text=[text])
+        )
+
+        self.rows = rows
+
+    def style_row(self, row_index: int, text_style: str) -> None:
+        # Validate row_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+
+        rows = self.rows.copy()
+        row = rows[row_index]
+
+        for cell in row.cells:
+            if isinstance(cell, str) and cell == "merge":
+                continue  # Skip merge cells
+            for paragraph in cell.paragraphs:
+                paragraph.style = text_style
+
+        self.rows = rows
+
+    def style_cell(self, row_index: int, col_index: int, text_style: str) -> None:
+        # Validate row_index and col_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+        rows = self.rows.copy()
+        row = rows[row_index]
+        if col_index < 0 or col_index >= len(row.cells):
+            raise IndexError(f"Column index {col_index} out of range")
+
+        cell = row.cells[col_index]
+        if isinstance(cell, str) and cell == "merge":
+            raise ValueError("Cannot style a merged cell")
+
+        for paragraph in cell.paragraphs:
+            paragraph.style = text_style
+
+        self.rows = rows
+
+    def color_row(self, row_index: int, background_color: str) -> None:
+        # Validate row_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+
+        rows = self.rows.copy()
+        row = rows[row_index]
+
+        for cell in row.cells:
+            if isinstance(cell, str) and cell == "merge":
+                continue  # Skip merge cells
+            cell.background_color = background_color
+
+        self.rows = rows
+
+    def color_cell(self, row_index: int, col_index: int, background_color: str) -> None:
+        # Validate row_index and col_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+        rows = self.rows.copy()
+        row = rows[row_index]
+        if col_index < 0 or col_index >= len(row.cells):
+            raise IndexError(f"Column index {col_index} out of range")
+
+        cell = row.cells[col_index]
+        if isinstance(cell, str) and cell == "merge":
+            raise ValueError("Cannot color a merged cell")
+
+        cell.background_color = background_color
+
+        self.rows = rows
+
+    def align_row(self, row_index: int, alignment: AlignmentEnum) -> None:
+        # Validate row_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+
+        rows = self.rows.copy()
+        row = rows[row_index]
+
+        for cell in row.cells:
+            if isinstance(cell, str) and cell == "merge":
+                continue  # Skip merge cells
+            for paragraph in cell.paragraphs:
+                paragraph.alignment = alignment
+
+        self.rows = rows
+
+    def align_cell(
+        self, row_index: int, col_index: int, alignment: AlignmentEnum
+    ) -> None:
+        # Validate row_index and col_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+        rows = self.rows.copy()
+        row = rows[row_index]
+        if col_index < 0 or col_index >= len(row.cells):
+            raise IndexError(f"Column index {col_index} out of range")
+
+        cell = row.cells[col_index]
+        if isinstance(cell, str) and cell == "merge":
+            raise ValueError("Cannot align a merged cell")
+
+        for paragraph in cell.paragraphs:
+            paragraph.alignment = alignment
+
+        self.rows = rows
+
+    def add_table_to_cell(
+        self, row_index: int, col_index: int, table: WordTableModel
+    ) -> None:
+        # Validate row_index and col_index
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+        rows = self.rows.copy()
+        row = rows[row_index]
+        if col_index < 0 or col_index >= len(row.cells):
+            raise IndexError(f"Column index {col_index} out of range")
+        cell = row.cells[col_index]
+
+        if isinstance(cell, str) and cell == "merge":
+            raise ValueError("Cannot add table to a merged cell")
+
+        cell.table = table
+
+        self.rows = rows
+
+    def delete_row(self, row_index: int) -> None:
+        if row_index < 0 or row_index >= len(self.rows):
+            raise IndexError(f"Row index {row_index} out of range")
+        rows = self.rows.copy()
+        del rows[row_index]
+        self.rows = rows
+
+    def pretty_print(self) -> None:
+        print(json.dumps(self.model_dump(), indent=4))
+
+    def write(self, filepath: str) -> None:
+        with open(filepath, "w") as f:
+            json.dump(self.model_dump(), f, indent=4)

wordhelpers-0.1.4.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: wordhelpers
+Version: 0.1.4
+Summary: Helpers for working with python-docx
+Author: AJ Cruz
+Author-email: 15045766-a-cruz@users.noreply.gitlab.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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 or with the provided WordTableModel class 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 WordTableModel, inject_table
+    ```
+1. Create the docx Word document object with something like:
+    ```python
+    doc_obj = Document("a_word_template.docx")
+    ```
+1. Add tables to 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 the docx `save()` method:
+    ```python
+    doc_obj.save("output_file.docx")
+    ```
+# Adding tables to the document object
+There are two methods available for creating tables for addition to a word document:
+1. The provided `WordTablesModel` class
+1. A properly-formatted python dictionary
+
+The WordTablesModel class has a number of methods available to help you build the table:
+- ```add_row(width: int, text: list[str] = [], merge_cols: list[int] = [], background_color: str | None = None, style: str | None = None, alignment: AlignmentEnum | None = None)```
+- ```add_text_to_row(row_index: int, text: list[str], style: str | None = None, alignment: AlignmentEnum | None = None)```
+- ```add_text_to_cell(row_index: int, col_index: int, text: str, style: str | None = None, alignment: AlignmentEnum | None = None)```
+- ```style_row(row_index: int, text_style: str)```
+- ```style_cell(row_index: int, col_index: int, text_style: str)```
+- ```color_row(row_index: int, background_color: str)```
+- ```color_cell(row_index: int, col_index: int, background_color: str)```
+- ```align_row(row_index: int, alignment: AlignmentEnum)```
+- ```align_cell(row_index: int, col_index: int, alignment: AlignmentEnum)```
+- ```add_table_to_cell(row_index: int, col_index: int, table: WordTableModel)```
+- ```delete_row(row_index: int)```
+- ```model_dump()```
+- ```pretty_print()```
+- ```write()```
+
+If you prefer to create the tables manually via Python dictionary, the dictionary must follow a strict schema that looks something like this:
+```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.
+
+Schema enforcement of the dictionary is done through Pydantic v2 validations.
+
+Injection of the table model (either via the class or a raw dictionary) is done via the provided ```inject_table()``` function.  
+The function has the following parameters:
+- doc_obj: _Document
+- table: dict
+- placeholder: str
+- remove_leading_para: bool = True
+- remove_placeholder: bool = True
+
+Notice the table parameter must be a python dictionary. So if you've created the table via the provided ```WordTableModel``` class you pass it to ```inject_table()``` with: ```my_table.model_dump()```
+
+- **<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".
+- **<remove_placeholder>** - This is an optional argument. You can leave the placeholder (```remove_placeholder=False```) if you need to keep injecting tables below the placeholder before final deletion
+
+### 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 wordhelpers import inject_table
+
+doc_obj = Document("source-template.docx")
+
+my_dictionary = {
+    "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:"}]
+                }
+            ]
+        }
+    ]                
+}
+
+inject_table(doc_obj, my_dictionary, "\[py_placeholder1\]")
+doc_obj.save("output_word_doc.docx")
+```
+
+Using the provided ```WordTableModel``` class instead of the raw dictionary, the python code would look like this:
+```python
+from docx import Document
+from wordhelpers import WordTableModel, inject_table
+
+doc_obj = Document("source-template.docx")
+
+my_table = WordTableModel()
+my_table.style = "plain"
+my_table.add_row(
+    3,
+    text=[
+        "Header 1:",
+        "Header 2:",
+        "Header 3:",
+    ],
+    background_color="#506279",
+    style="regularbold",
+)
+my_table.add_row(
+    3,
+    text=[
+        "Row 1 Data 1:",
+        "Row 1 Data 2:",
+        "Row 1 Data 3:",
+    ],
+    background_color="#D5DCE4",
+    style="No Spacing",
+)
+my_table.add_row(
+    3,
+    text=[
+        "Row 2 Data 1:",
+        "Row 2 Data 2:",
+        "Row 2 Data 3:",
+    ],
+    style="No Spacing",
+)
+my_table.add_row(
+    3,
+    text=[
+        "Row 3 Data 1:",
+        "Row 3 Data 2:",
+        "Row 3 Data 3:",
+    ],
+    background_color="#D5DCE4",
+    style="No Spacing",
+)
+
+inject_table(doc_obj, my_table.model_dump(), "\[py_placeholder1\]")
+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 building raw 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.4.dist-info/RECORD

@@ -0,0 +1,5 @@
+wordhelpers/__init__.py,sha256=9gR-TRwfToOc3MtkV7gbubbbZs79H6LBJQ-pgdpKV_w,11648
+wordhelpers/pydantic_models.py,sha256=tg2PXpbVWlym3XmF0KGM1LZDxO-oItzhkTTXEQ11x2g,11211
+wordhelpers-0.1.4.dist-info/METADATA,sha256=si1K6RFlC7G4KypZkyVo0KqrWY8NnendWw3cvXIJGl4,11529
+wordhelpers-0.1.4.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+wordhelpers-0.1.4.dist-info/RECORD,,

{wordhelpers-0.1.2.dist-info → wordhelpers-0.1.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.3.0
 Root-Is-Purelib: true
 Tag: py3-none-any

wordhelpers-0.1.2.dist-info/METADATA

@@ -1,217 +0,0 @@
-Metadata-Version: 2.3
-Name: wordhelpers
-Version: 0.1.2
-Summary: Helpers for working with python-docx
-Author: AJ Cruz
-Author-email: 15045766-a-cruz@users.noreply.gitlab.com
-Requires-Python: >=3.11
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-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.2.dist-info/RECORD

@@ -1,5 +0,0 @@
-wordhelpers/__init__.py,sha256=CDZRBn1H42Aqjs638FyEYxj-6Jbwk6dGihA8mA2Ij98,10314
-wordhelpers/pydantic_models.py,sha256=pb7J6x3p-AmPN1nt7qONArNQztxbfxuUC1dC0DhZ2j0,1643
-wordhelpers-0.1.2.dist-info/METADATA,sha256=ZmfUx6jT5OsLN1w6qB-Fl-w3tbQcdKW6lvIF4PHJAJA,11566
-wordhelpers-0.1.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-wordhelpers-0.1.2.dist-info/RECORD,,