Skip to content

docx_plus.layout.settings

Doc-level <w:evenAndOddHeaders/> switch in settings.xml. This flag is constantly confused with the per-section titlePg that python-docx already exposes via Section.different_first_page_header_footer. The flag here is different: it tells Word that even-numbered pages may have a different header/footer from odd-numbered pages, across every section.

Schema-strict insertion via core.insert_before_first_anchor. Both toggle functions are idempotent.

docx_plus.layout.settings

Doc-level <w:evenAndOddHeaders> switch in settings.xml.

This flag is constantly confused with <w:titlePg> (per-section, controls whether first-page differs) and Section.different_first_page_header_footer (the python-docx wrapper around that). The doc-level flag here is different: it tells Word that even-numbered pages may have a different header/footer from odd-numbered pages, across every section. python-docx exposes no setter for it, so this module writes the element directly into settings.xml using the same schema-strict insertion pattern as :func:docx_plus.fields.mark_fields_dirty.

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

enable_distinct_even_odd_headers 

enable_distinct_even_odd_headers(doc: Document) -> None

Enable distinct even-page vs odd-page headers and footers.

Writes <w:evenAndOddHeaders/> into settings.xml if absent. Idempotent: a second call does not stack elements, and any duplicate copies left by another tool are collapsed to one (CT_Settings permits at most one). Word will read even-page header/footer references from each section's <w:headerReference w:type="even"> / <w:footerReference w:type="even"> children when this flag is set.

Parameters:

Name Type Description Default
doc Document

The python-docx :class:~docx.document.Document whose settings part should carry the flag.

 required
Example

from docx import Document from docx_plus.layout import enable_distinct_even_odd_headers doc = Document() enable_distinct_even_odd_headers(doc)

Source code in docx_plus/layout/settings.py 
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
def enable_distinct_even_odd_headers(doc: DocxDocument) -> None:
    """Enable distinct even-page vs odd-page headers and footers.

    Writes ``<w:evenAndOddHeaders/>`` into ``settings.xml`` if absent.
    Idempotent: a second call does not stack elements, and any duplicate
    copies left by another tool are collapsed to one (``CT_Settings``
    permits at most one). Word will read even-page header/footer references
    from each section's ``<w:headerReference w:type="even">`` /
    ``<w:footerReference w:type="even">`` children when this flag is set.

    Args:
        doc: The python-docx :class:`~docx.document.Document` whose
            settings part should carry the flag.

    Example:
        >>> from docx import Document
        >>> from docx_plus.layout import enable_distinct_even_odd_headers
        >>> doc = Document()
        >>> enable_distinct_even_odd_headers(doc)
    """
    settings = doc.settings.element
    existing = settings.findall(qn("w:evenAndOddHeaders"))
    if existing:
        for extra in existing[1:]:
            remove(extra)
        return
    new = el("w:evenAndOddHeaders")
    insert_before_first_anchor(settings, new, _EVEN_AND_ODD_HEADERS_LATER_SIBLINGS)

disable_distinct_even_odd_headers 

disable_distinct_even_odd_headers(doc: Document) -> None

Remove <w:evenAndOddHeaders/> from settings.xml if present.

Idempotent: removing the flag when it is already absent is a no-op. Removes every copy, so a malformed file with duplicates is fully cleared rather than leaving a stale second element behind.

Parameters:

Name Type Description Default
doc Document

The python-docx :class:~docx.document.Document to mutate.

 required
Source code in docx_plus/layout/settings.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def disable_distinct_even_odd_headers(doc: DocxDocument) -> None:
    """Remove ``<w:evenAndOddHeaders/>`` from ``settings.xml`` if present.

    Idempotent: removing the flag when it is already absent is a no-op.
    Removes *every* copy, so a malformed file with duplicates is fully
    cleared rather than leaving a stale second element behind.

    Args:
        doc: The python-docx :class:`~docx.document.Document` to mutate.
    """
    settings = doc.settings.element
    for existing in settings.findall(qn("w:evenAndOddHeaders")):
        remove(existing)