borders

borders

The border-edge proxy objects shared by tables, cells, paragraphs and pages.

Four containers in WordprocessingML carry a set of border edges — w:tblBorders, w:tcBorders, w:pBdr and w:pgBorders — and they differ only in which edges they admit and where the element lives. The mapping proxy and the per-edge proxy are defined here once so all four spell the same; each container supplies its own small subclass naming its edges and saying how to reach its element.

_Border

_Border(borders: _Borders, edge: str)

One border edge of a table, cell, paragraph or page, e.g. table.borders["top"].

A border edge that is not set has None for every property, meaning the effective appearance of that edge is inherited from the style hierarchy. Assigning to any property other than line on an edge that is not set creates it with a line style of WD_LINE_STYLE.SINGLE, because a border with no line style is not valid XML. Assigning None to line removes the edge entirely.

Source code in src/docx/borders.py

def __init__(self, borders: _Borders, edge: str):
    self._borders = borders
    self._edge = edge

color property writable

color: RGBColor | None

RGBColor of this border edge, or None when it has no explicit color.

As for ColorFormat, a border whose color is the automatic color reads as None; Word chooses that color at render time, so there is no RGB value to report.

line property writable

line: WD_LINE_STYLE | None

Member of WdLineStyle, or None when this edge is not set.

size property writable

size: Length | None

Width of this border line, or None when it has no explicit width.

The underlying w:sz attribute counts eighths of a point, so an assigned value is rounded to the nearest eighth of a point.

space property writable

space: Length | None

Offset of this border from the content it surrounds, or None when not set.

The underlying w:space attribute counts whole points, so an assigned value is rounded to the nearest point.

_Borders

_Borders(edges: tuple[str, ...])

Bases: Mapping[str, _Border]

The border edges of a table, cell, paragraph or page, keyed by edge name.

A read-only mapping in the sense that the set of keys is fixed; the _Border object each key maps to is what you assign through:

table.borders["top"].line = WD_LINE_STYLE.SINGLE

Every edge admitted by the schema is always a key, whether or not it is set, so iterating yields edges with a _Border.line of None as well.

Edge names are the local names used in the XML. A table admits top, start, left, bottom, end, right, insideH and insideV; a cell adds tl2br and tr2bl; a paragraph has top, left, bottom, right, between and bar; a page has the plain four. Word writes left and right for a left-to-right table and start and end for a right-to-left one.

Source code in src/docx/borders.py

def __init__(self, edges: tuple[str, ...]):
    self._edges = edges

clear abstractmethod

clear() -> None

Remove every border edge, restoring inheritance from the style hierarchy.

Source code in src/docx/borders.py

@abstractmethod
def clear(self) -> None:
    """Remove every border edge, restoring inheritance from the style hierarchy."""