wordhelpers 0.1.3__tar.gz → 0.1.5__tar.gz

{wordhelpers-0.1.3 → wordhelpers-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: wordhelpers
-Version: 0.1.3
+Version: 0.1.5
 Summary: Helpers for working with python-docx
 Author: AJ Cruz
 Author-email: 15045766-a-cruz@users.noreply.gitlab.com
@@ -9,6 +9,7 @@ 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
@@ -64,6 +65,7 @@ The WordTablesModel class has a number of methods available to help you build th
 - ```model_dump()```
 - ```pretty_print()```
 - ```write()```
+- ```sort_rows_by_columns(primary_col: int, secondary_col: int | None = None, *, ascending: bool = True,)```
 
 If you prefer to create the tables manually via Python dictionary, the dictionary must follow a strict schema that looks something like this:
 ```python

{wordhelpers-0.1.3 → wordhelpers-0.1.5}/README.md

@@ -49,6 +49,7 @@ The WordTablesModel class has a number of methods available to help you build th
 - ```model_dump()```
 - ```pretty_print()```
 - ```write()```
+- ```sort_rows_by_columns(primary_col: int, secondary_col: int | None = None, *, ascending: bool = True,)```
 
 If you prefer to create the tables manually via Python dictionary, the dictionary must follow a strict schema that looks something like this:
 ```python

{wordhelpers-0.1.3 → wordhelpers-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wordhelpers"
-version = "0.1.3"
+version = "0.1.5"
 description = "Helpers for working with python-docx"
 authors = [
     {name = "AJ Cruz",email = "15045766-a-cruz@users.noreply.gitlab.com"}

{wordhelpers-0.1.3 → wordhelpers-0.1.5}/wordhelpers/__init__.py

@@ -81,7 +81,7 @@ def replace_placeholder_with_table(
 
 def inject_table(
     doc_obj: _Document,
-    table: dict,
+    table: dict | WordTableModel,
     placeholder: str,
     remove_leading_para: bool = True,
     remove_placeholder: bool = True,
@@ -93,21 +93,27 @@ def inject_table(
     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: Table = build_table(doc_obj, table, remove_leading_para=remove_leading_para)
+    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
+        )
+    )
 
-    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)
+    # 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)
+    if remove_placeholder:
+        # Delete the placeholder paragraph
+        delete_paragraph(paragraph)
 
 
 def build_table(

{wordhelpers-0.1.3 → wordhelpers-0.1.5}/wordhelpers/pydantic_models.py

@@ -63,34 +63,38 @@ class WordTableModel(BaseModel):
     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:
 
-    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}")
-            
+                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")
-    
+            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):
@@ -101,37 +105,68 @@ class WordTableModel(BaseModel):
                 # 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))
+                    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:
+    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"])
+        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")
-        
+            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)]))
+                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:
+    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")
@@ -139,21 +174,22 @@ class WordTableModel(BaseModel):
         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
+        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]
 
@@ -165,7 +201,6 @@ class WordTableModel(BaseModel):
 
         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):
@@ -174,22 +209,21 @@ class WordTableModel(BaseModel):
         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]
 
@@ -200,7 +234,6 @@ class WordTableModel(BaseModel):
 
         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):
@@ -209,21 +242,20 @@ class WordTableModel(BaseModel):
         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]
 
@@ -235,8 +267,9 @@ class WordTableModel(BaseModel):
 
         self.rows = rows
 
-    
-    def align_cell(self, row_index: int, col_index: int, alignment: AlignmentEnum) -> None:
+    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")
@@ -244,22 +277,19 @@ class WordTableModel(BaseModel):
         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:
+    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")
@@ -271,12 +301,11 @@ class WordTableModel(BaseModel):
 
         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")
@@ -284,12 +313,62 @@ class WordTableModel(BaseModel):
         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:
+        with open(filepath, "w") as f:
             json.dump(self.model_dump(), f, indent=4)
 
+    def _row_text_at(self, row: WordRowModel, col_index: int) -> str:
+        if col_index >= len(row.cells):
+            return ""
+
+        cell = row.cells[col_index]
+
+        if isinstance(cell, str):  # "merge"
+            return ""
+
+        if not cell.paragraphs:
+            return ""
+
+        paragraph = cell.paragraphs[0]
+        text = paragraph.text
+
+        if isinstance(text, list) and text:
+            return text[0].lower()
+
+        if isinstance(text, str):
+            return text.lower()
+
+        return ""
+
+    def sort_rows_by_columns(
+        self,
+        primary_col: int,
+        secondary_col: int | None = None,
+        *,
+        ascending: bool = True,
+    ) -> None:
+        if len(self.rows) <= 1:
+            return
+
+        header = self.rows[0]
+        body = self.rows[1:]
+
+        def sort_key(row: WordRowModel):
+            primary = self._row_text_at(row, primary_col)
+            secondary = (
+                self._row_text_at(row, secondary_col)
+                if secondary_col is not None
+                else ""
+            )
+            return (primary, secondary)
+
+        body_sorted = sorted(
+            body,
+            key=sort_key,
+            reverse=not ascending,
+        )
+
+        self.rows = [header] + body_sorted