Merge pull request #4 from MHoroszowski/feature/table-cell-borders

feature: add per-edge border styling for table cells

Author: MHoroszowski

src/pptx/oxml/__init__.py

@@ -385,6 +385,10 @@ def register_element_cls(nsptagname: str, cls: Type[BaseOxmlElement]):
 register_element_cls("a:ext", CT_PositiveSize2D)
 register_element_cls("a:headEnd", CT_LineEndProperties)
 register_element_cls("a:ln", CT_LineProperties)
+register_element_cls("a:lnB", CT_LineProperties)
+register_element_cls("a:lnL", CT_LineProperties)
+register_element_cls("a:lnR", CT_LineProperties)
+register_element_cls("a:lnT", CT_LineProperties)
 register_element_cls("a:off", CT_Point2D)
 register_element_cls("a:tailEnd", CT_LineEndProperties)
 register_element_cls("a:xfrm", CT_Transform2D)

src/pptx/oxml/table.py

@@ -363,6 +363,32 @@ def _set_marX(self, marX: str, value: Length | None) -> None:
 class CT_TableCellProperties(BaseOxmlElement):
     """`a:tcPr` custom element class"""
 
+    get_or_add_lnL: Callable[..., BaseOxmlElement]
+    get_or_add_lnR: Callable[..., BaseOxmlElement]
+    get_or_add_lnT: Callable[..., BaseOxmlElement]
+    get_or_add_lnB: Callable[..., BaseOxmlElement]
+
+    _tag_seq = (
+        "a:lnL",
+        "a:lnR",
+        "a:lnT",
+        "a:lnB",
+        "a:lnTlToBr",
+        "a:lnBlToTr",
+        "a:cell3D",
+        "a:noFill",
+        "a:solidFill",
+        "a:gradFill",
+        "a:blipFill",
+        "a:pattFill",
+        "a:grpFill",
+        "a:headers",
+        "a:extLst",
+    )
+    lnL = ZeroOrOne("a:lnL", successors=_tag_seq[1:])
+    lnR = ZeroOrOne("a:lnR", successors=_tag_seq[2:])
+    lnT = ZeroOrOne("a:lnT", successors=_tag_seq[3:])
+    lnB = ZeroOrOne("a:lnB", successors=_tag_seq[4:])
     eg_fillProperties = ZeroOrOneChoice(
         (
             Choice("a:noFill"),
@@ -372,8 +398,9 @@ class CT_TableCellProperties(BaseOxmlElement):
             Choice("a:pattFill"),
             Choice("a:grpFill"),
         ),
-        successors=("a:headers", "a:extLst"),
+        successors=_tag_seq[13:],
     )
+    del _tag_seq
     anchor: MSO_VERTICAL_ANCHOR | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "anchor", MSO_VERTICAL_ANCHOR
     )

src/pptx/table.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING, Iterator
 
 from pptx.dml.fill import FillFormat
+from pptx.dml.line import LineFormat
 from pptx.oxml.table import TcRange
 from pptx.shapes import Subshape
 from pptx.text.text import TextFrame
@@ -165,6 +166,62 @@ def vert_banding(self, value: bool):
         self._tbl.bandCol = value
 
 
+class _BorderEdge:
+    """Adapter providing a `LineFormat`-compatible interface for one edge of a cell border.
+
+    `LineFormat` requires a parent with `.ln` and `.get_or_add_ln()`. This adapter delegates those
+    to the appropriate border element (`a:lnL`, `a:lnR`, `a:lnT`, `a:lnB`) on `a:tcPr`.
+    """
+
+    def __init__(self, tc: CT_TableCell, edge_attr: str):
+        self._tc = tc
+        self._edge_attr = edge_attr  # e.g. "lnL", "lnR", "lnT", "lnB"
+
+    @property
+    def ln(self):
+        """Return the `a:lnX` element or None."""
+        tcPr = self._tc.tcPr
+        if tcPr is None:
+            return None
+        return getattr(tcPr, self._edge_attr)
+
+    def get_or_add_ln(self):
+        """Return the `a:lnX` element, creating `a:tcPr` and the element if not present."""
+        tcPr = self._tc.get_or_add_tcPr()
+        return getattr(tcPr, f"get_or_add_{self._edge_attr}")()
+
+
+class _CellBorders:
+    """Provides access to border line formatting for each edge of a table cell.
+
+    Accessed via `cell.borders`. Each edge (`.left`, `.right`, `.top`, `.bottom`) returns a
+    |LineFormat| object that controls the border's color, width, and dash style.
+    """
+
+    def __init__(self, tc: CT_TableCell):
+        self._tc = tc
+
+    @lazyproperty
+    def bottom(self) -> LineFormat:
+        """|LineFormat| for the bottom border of this cell."""
+        return LineFormat(_BorderEdge(self._tc, "lnB"))
+
+    @lazyproperty
+    def left(self) -> LineFormat:
+        """|LineFormat| for the left border of this cell."""
+        return LineFormat(_BorderEdge(self._tc, "lnL"))
+
+    @lazyproperty
+    def right(self) -> LineFormat:
+        """|LineFormat| for the right border of this cell."""
+        return LineFormat(_BorderEdge(self._tc, "lnR"))
+
+    @lazyproperty
+    def top(self) -> LineFormat:
+        """|LineFormat| for the top border of this cell."""
+        return LineFormat(_BorderEdge(self._tc, "lnT"))
+
+
 class _Cell(Subshape):
     """Table cell"""
 
@@ -187,6 +244,21 @@ def __ne__(self, other: object) -> bool:
             return True
         return self._tc is not other._tc
 
+    @lazyproperty
+    def borders(self) -> _CellBorders:
+        """|_CellBorders| instance for this cell.
+
+        Provides access to the line formatting for each border edge. Each edge (`.left`, `.right`,
+        `.top`, `.bottom`) is a |LineFormat| object.
+
+        Example::
+
+            cell.borders.top.width = Pt(2)
+            cell.borders.top.color.rgb = RGBColor(0xFF, 0x00, 0x00)
+            cell.borders.bottom.dash_style = MSO_LINE.DASH
+        """
+        return _CellBorders(self._tc)
+
     @lazyproperty
     def fill(self) -> FillFormat:
         """|FillFormat| instance for this cell.

tests/test_table.py

@@ -7,13 +7,15 @@
 import pytest
 
 from pptx.dml.fill import FillFormat
+from pptx.dml.line import LineFormat
 from pptx.enum.text import MSO_ANCHOR
 from pptx.oxml.ns import qn
 from pptx.oxml.table import CT_Table, CT_TableCell, TcRange
 from pptx.shapes.graphfrm import GraphicFrame
 from pptx.table import (
     Table,
     _Cell,
+    _CellBorders,
     _CellCollection,
     _Column,
     _ColumnCollection,
@@ -207,6 +209,38 @@ def it_is_equal_to_other_instance_having_same_tc(self):
         assert cell == cell_with_same_tc
         assert cell != cell_with_other_tc
 
+    def it_provides_access_to_its_borders(self):
+        tc = element("a:tc/a:tcPr")
+        cell = _Cell(tc, None)
+        borders = cell.borders
+        assert isinstance(borders, _CellBorders)
+        assert isinstance(borders.left, LineFormat)
+        assert isinstance(borders.right, LineFormat)
+        assert isinstance(borders.top, LineFormat)
+        assert isinstance(borders.bottom, LineFormat)
+
+    @pytest.mark.parametrize(
+        ("tc_cxml", "edge", "expected_width"),
+        [
+            ("a:tc/a:tcPr", "left", 0),
+            ("a:tc/a:tcPr/a:lnL{w=25400}", "left", 25400),
+            ("a:tc/a:tcPr/a:lnR{w=12700}", "right", 12700),
+            ("a:tc/a:tcPr/a:lnT{w=38100}", "top", 38100),
+            ("a:tc/a:tcPr/a:lnB{w=6350}", "bottom", 6350),
+        ],
+    )
+    def it_can_read_border_width(self, tc_cxml: str, edge: str, expected_width: int):
+        cell = _Cell(element(tc_cxml), None)
+        border_line = getattr(cell.borders, edge)
+        assert border_line.width == expected_width
+
+    def it_can_set_a_border_width(self):
+        tc = element("a:tc/a:tcPr")
+        cell = _Cell(tc, None)
+        cell.borders.top.width = Pt(2)
+        assert cell._tc.tcPr.lnT is not None
+        assert cell._tc.tcPr.lnT.w == Pt(2)
+
     def it_has_a_fill(self, fill_fixture):
         cell = fill_fixture
         assert isinstance(cell.fill, FillFormat)