Skip to content

docx_plus.layout.borders

Page borders via <w:pgBorders> with a per-side Border dataclass. Each side carries style (e.g. "single", "double"), thickness in eighths of a point, RGB hex color, and a space gap in points (range 0-31). set_page_borders also takes offset_from ("page" default, matching Word's UI, or "text"). All four sides default to None; passing all-None removes the element rather than emitting an empty container.

Architecture walkthrough: Layout.

docx_plus.layout.borders

Page borders (<w:pgBorders>).

python-docx does not abstract <w:pgBorders> — the section-scoped control for the decorative box around a page that formal documents (certificates, awards, contract title pages) frequently want. This module fills the gap with a single :func:set_page_borders helper over the shared :class:~docx_plus.core.borders.Border dataclass.

:class:Border was defined here in v0.2 and moved to :mod:docx_plus.core.borders in v0.5, when table and cell borders became a second consumer of the identical CT_Border shape. It is re-exported below, so from docx_plus.layout import Border is unchanged.

ECMA-376 §17.6.10: pgBorders is a container element whose four optional children (top, left, bottom, right — in schema order) each declare their style (w:val), thickness in eighths of a point (w:sz), color (w:color), and the gap from the reference edge (w:space, in points). The container also takes an offsetFrom attribute that selects whether w:space is measured from the page edge or the body text.

This module imports only from docx_plus.core (SPEC §9.1).

OffsetFrom module-attribute 

OffsetFrom = Literal['page', 'text']

Border dataclass 

Border(
    style: str = "single", size: int = 4, color: str = "auto", space: int = 24
)

One border edge.

Attributes:

Name Type Description
style str

ECMA-376 17.18.2 border style name. Common values: "single" (default), "double", "thick", "dashed", "dotted", "wave", "none". The full enumeration has 200+ entries — see the spec.
size int

Border thickness in eighths of a point (so 4 is 0.5 pt and 8 is 1 pt). ECMA-376 caps this at 96.
color str

"RRGGBB" hex or "auto" (default) to let Word pick a sensible contrast. Validated at construction against ECMA-376 17.18.79 ST_HexColor — "red", "#FF0000", or a 3-digit shorthand raise :class:ValueError.
space int

Gap between the reference edge and the border, in points. ECMA-376 caps this at 31.

The default 24 — 1/3 inch — is a page-border default: it is what Word's UI emits for "Whole document, Box, Default settings" paired with offset_from="page". Word's UI does not expose the setting for tables at all and always writes w:space="0" there, so :mod:docx_plus.tables ignores this field and writes 0 rather than letting a page default leak onto a table edge.

Raises:

Type Description
ValueError

If color is not "auto" or a six-hex-digit "RRGGBB" string, if size is outside [0, 96], or if style is not a bare identifier.

__post_init__ 

__post_init__() -> None

Validate the fields against their ECMA-376 simple types.

Source code in docx_plus/core/borders.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def __post_init__(self) -> None:
    """Validate the fields against their ECMA-376 simple types."""
    if not _HEX_COLOR_RE.match(self.color):
        raise ValueError(
            "Border.color must be 'auto' or a six-hex-digit 'RRGGBB' string; "
            f"got {self.color!r}"
        )
    if not 0 <= self.size <= _MAX_BORDER_SIZE:
        raise ValueError(
            f"Border.size is in eighths of a point and ECMA-376 caps it at "
            f"{_MAX_BORDER_SIZE}; got {self.size!r}"
        )
    if not _BORDER_STYLE_RE.match(self.style):
        raise ValueError(
            "Border.style must be an ECMA-376 17.18.2 ST_Border name such as "
            f"{'/'.join(sorted(_COMMON_BORDER_STYLES)[:4])}; got {self.style!r}"
        )

set_page_borders 

set_page_borders(
    section: Section,
    *,
    top: Border | None = None,
    bottom: Border | None = None,
    left: Border | None = None,
    right: Border | None = None,
    offset_from: OffsetFrom = "page",
) -> None

Configure the page border for section.

Idempotent: replaces any existing <w:pgBorders>. Passing all four sides as None removes the element instead of writing an empty container. Child sides are written in the schema-required order top → left → bottom → right per ECMA-376 17.6.10.

Parameters:

Name Type Description Default
section Section

A python-docx :class:~docx.section.Section.

 required
top Border | None

Border for the top edge, or None to omit.

 None
bottom Border | None

Border for the bottom edge.

 None
left Border | None

Border for the left edge.

 None
right Border | None

Border for the right edge.

 None
offset_from OffsetFrom

"page" (default) measures Border.space from the page edge — what Word's UI emits and what callers usually want for a decorative frame. "text" measures from the body text edge — the spec's implicit default when the attribute is omitted, producing a tight inner box.

 'page'
Example

from docx import Document from docx_plus.layout import Border, set_page_borders doc = Document() rule = Border(style="single", size=8, color="2F5496") set_page_borders(doc.sections[0], top=rule, bottom=rule, ... left=rule, right=rule)

Source code in docx_plus/layout/borders.py 
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def set_page_borders(
    section: Section,
    *,
    top: Border | None = None,
    bottom: Border | None = None,
    left: Border | None = None,
    right: Border | None = None,
    offset_from: OffsetFrom = "page",
) -> None:
    """Configure the page border for ``section``.

    Idempotent: replaces any existing ``<w:pgBorders>``. Passing all
    four sides as ``None`` removes the element instead of writing an
    empty container. Child sides are written in the schema-required
    order ``top → left → bottom → right`` per ECMA-376 17.6.10.

    Args:
        section: A python-docx :class:`~docx.section.Section`.
        top: Border for the top edge, or ``None`` to omit.
        bottom: Border for the bottom edge.
        left: Border for the left edge.
        right: Border for the right edge.
        offset_from: ``"page"`` (default) measures ``Border.space`` from
            the page edge — what Word's UI emits and what callers
            usually want for a decorative frame. ``"text"`` measures
            from the body text edge — the spec's *implicit* default
            when the attribute is omitted, producing a tight inner box.

    Example:
        >>> from docx import Document
        >>> from docx_plus.layout import Border, set_page_borders
        >>> doc = Document()
        >>> rule = Border(style="single", size=8, color="2F5496")
        >>> set_page_borders(doc.sections[0], top=rule, bottom=rule,
        ...                  left=rule, right=rule)
    """
    sect_pr = section._sectPr
    existing = sect_pr.find(qn("w:pgBorders"))
    if existing is not None:
        remove(existing)

    if top is None and bottom is None and left is None and right is None:
        return

    borders_el = el("w:pgBorders", **{"w:offsetFrom": offset_from})
    # Schema-required order per ECMA-376 17.6.10 CT_PageBorders.
    for tag, border in (
        ("w:top", top),
        ("w:left", left),
        ("w:bottom", bottom),
        ("w:right", right),
    ):
        if border is None:
            continue
        sub(borders_el, tag, **border_attrs(border))

    insert_before_first_anchor(sect_pr, borders_el, _LATER_SIBLINGS)