base

base

Base classes and other objects used by enumerations.

BaseEnum

Bases: int, Enum

Base class for Enums that do not map XML attr values.

The enum's value will be an integer, corresponding to the integer assigned the corresponding member in the MS API enum of the same name.

BaseXmlEnum

Bases: int, Enum

Base class for Enums that also map XML attr values.

The enum's value will be an integer, corresponding to the integer assigned the corresponding member in the MS API enum of the same name.

from_xml classmethod

from_xml(xml_value: str | None) -> Self

Enumeration member corresponding to XML attribute value xml_value.

Example:

>>> WD_PARAGRAPH_ALIGNMENT.from_xml("center")
WD_PARAGRAPH_ALIGNMENT.CENTER

Source code in src/docx/enum/base.py

@classmethod
def from_xml(cls, xml_value: str | None) -> Self:
    """Enumeration member corresponding to XML attribute value `xml_value`.

    Example::

        >>> WD_PARAGRAPH_ALIGNMENT.from_xml("center")
        WD_PARAGRAPH_ALIGNMENT.CENTER

    """
    member = next((member for member in cls if member.xml_value == xml_value), None)
    if member is None:
        raise ValueError(f"{cls.__name__} has no XML mapping for '{xml_value}'")
    return member

to_xml classmethod

to_xml(value: int | _T | None) -> str | None

XML value of this enum member, generally an XML attribute value.

Source code in src/docx/enum/base.py

@classmethod
def to_xml(cls: Type[_T], value: int | _T | None) -> str | None:
    """XML value of this enum member, generally an XML attribute value."""
    # -- presence of multi-arg `__new__()` method fools type-checker, but getting a
    # -- member by its value using EnumCls(val) works as usual.
    member = cls(value)
    xml_value = member.xml_value
    if not xml_value:
        raise ValueError(f"{cls.__name__}.{member.name} has no XML representation")
    return xml_value

DocsPageFormatter

DocsPageFormatter(clsname: str, clsdict: Dict[str, Any])

Generate an .rst doc page for an enumeration.

Formats a RestructuredText documention page (string) for the enumeration class parts passed to the constructor. An immutable one-shot service object.

Source code in src/docx/enum/base.py

def __init__(self, clsname: str, clsdict: Dict[str, Any]):
    self._clsname = clsname
    self._clsdict = clsdict

page_str property

page_str

The RestructuredText documentation page for the enumeration.

This is the only API member for the class.