Initial commit (Clean history)

path/to/venv/lib/python3.12/site-packages/docx/blkcntnr.py

@@ -0,0 +1,101 @@
+# pyright: reportImportCycles=false
+
+"""Block item container, used by body, cell, header, etc.
+
+Block level items are things like paragraph and table, although there are a few other
+specialized ones like structured document tags.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator
+
+from typing_extensions import TypeAlias
+
+from docx.oxml.table import CT_Tbl
+from docx.oxml.text.paragraph import CT_P
+from docx.shared import StoryChild
+from docx.text.paragraph import Paragraph
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.oxml.comments import CT_Comment
+    from docx.oxml.document import CT_Body
+    from docx.oxml.section import CT_HdrFtr
+    from docx.oxml.table import CT_Tc
+    from docx.shared import Length
+    from docx.styles.style import ParagraphStyle
+    from docx.table import Table
+
+BlockItemElement: TypeAlias = "CT_Body | CT_Comment | CT_HdrFtr | CT_Tc"
+
+
+class BlockItemContainer(StoryChild):
+    """Base class for proxy objects that can contain block items.
+
+    These containers include _Body, _Cell, header, footer, footnote, endnote, comment,
+    and text box objects. Provides the shared functionality to add a block item like a
+    paragraph or table.
+    """
+
+    def __init__(self, element: BlockItemElement, parent: t.ProvidesStoryPart):
+        super(BlockItemContainer, self).__init__(parent)
+        self._element = element
+
+    def add_paragraph(self, text: str = "", style: str | ParagraphStyle | None = None) -> Paragraph:
+        """Return paragraph newly added to the end of the content in this container.
+
+        The paragraph has `text` in a single run if present, and is given paragraph
+        style `style`.
+
+        If `style` is |None|, no paragraph style is applied, which has the same effect
+        as applying the 'Normal' style.
+        """
+        paragraph = self._add_paragraph()
+        if text:
+            paragraph.add_run(text)
+        if style is not None:
+            paragraph.style = style
+        return paragraph
+
+    def add_table(self, rows: int, cols: int, width: Length) -> Table:
+        """Return table of `width` having `rows` rows and `cols` columns.
+
+        The table is appended appended at the end of the content in this container.
+
+        `width` is evenly distributed between the table columns.
+        """
+        from docx.table import Table
+
+        tbl = CT_Tbl.new_tbl(rows, cols, width)
+        self._element._insert_tbl(tbl)  # pyright: ignore[reportPrivateUsage]
+        return Table(tbl, self)
+
+    def iter_inner_content(self) -> Iterator[Paragraph | Table]:
+        """Generate each `Paragraph` or `Table` in this container in document order."""
+        from docx.table import Table
+
+        for element in self._element.inner_content_elements:
+            yield (Paragraph(element, self) if isinstance(element, CT_P) else Table(element, self))
+
+    @property
+    def paragraphs(self):
+        """A list containing the paragraphs in this container, in document order.
+
+        Read-only.
+        """
+        return [Paragraph(p, self) for p in self._element.p_lst]
+
+    @property
+    def tables(self):
+        """A list containing the tables in this container, in document order.
+
+        Read-only.
+        """
+        from docx.table import Table
+
+        return [Table(tbl, self) for tbl in self._element.tbl_lst]
+
+    def _add_paragraph(self):
+        """Return paragraph newly added to the end of the content in this container."""
+        return Paragraph(self._element.add_p(), self)