Skip to content

extendedprops

extendedprops

Custom element classes for extended (application) properties XML elements.

CT_ExtendedProperties

Bases: BaseOxmlElement

<ep:Properties> element, the root element of the Extended Properties part.

Stored as /docProps/app.xml. These are the properties Word shows under File > Info > Properties that are not Dublin Core, such as the word count and the application that wrote the file.

CT_Properties is declared xsd:all rather than xsd:sequence, so child order carries no meaning and every element is optional. Word writes them in its own order, which is not the order they appear in the schema. New elements are therefore simply appended, and no successors bookkeeping is needed.

new classmethod 

new() -> CT_ExtendedProperties

Return a new <ep:Properties> element.

Source code in src/docx/oxml/extendedprops.py 
52
53
54
55
@classmethod
def new(cls) -> CT_ExtendedProperties:
    """Return a new `<ep:Properties>` element."""
    return cast(CT_ExtendedProperties, parse_xml(cls._Properties_tmpl))

text_of 

text_of(property_name: str) -> str | None

Text of the child element named property_name.

None when the element is absent, distinguishing "not recorded" from a value that is genuinely the empty string.

Source code in src/docx/oxml/extendedprops.py 
57
58
59
60
61
62
63
64
65
66
def text_of(self, property_name: str) -> str | None:
    """Text of the child element named `property_name`.

    |None| when the element is absent, distinguishing "not recorded" from a value
    that is genuinely the empty string.
    """
    element = getattr(self, property_name)
    if element is None:
        return None
    return element.text or ""

set_text_of 

set_text_of(property_name: str, value: str | None) -> None

Set the text of child element property_name, adding it if necessary.

Assigning None removes the element.

Source code in src/docx/oxml/extendedprops.py 
68
69
70
71
72
73
74
75
76
77
def set_text_of(self, property_name: str, value: str | None) -> None:
    """Set the text of child element `property_name`, adding it if necessary.

    Assigning |None| removes the element.
    """
    if value is None:
        getattr(self, "_remove_%s" % property_name)()
        return
    element = getattr(self, "get_or_add_%s" % property_name)()
    element.text = value

int_of 

int_of(property_name: str) -> int | None

Integer value of child element property_name, or None if absent.

Returns None rather than raising when the recorded text is not a valid integer; these values are written by other applications and a malformed count should not make the whole document unreadable.

Source code in src/docx/oxml/extendedprops.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def int_of(self, property_name: str) -> int | None:
    """Integer value of child element `property_name`, or |None| if absent.

    Returns |None| rather than raising when the recorded text is not a valid
    integer; these values are written by other applications and a malformed count
    should not make the whole document unreadable.
    """
    text = self.text_of(property_name)
    if not text:
        return None
    try:
        return int(text)
    except ValueError:
        return None

bool_of 

bool_of(property_name: str) -> bool | None

Boolean value of child element property_name, or None if absent.

Source code in src/docx/oxml/extendedprops.py 
 97
 98
 99
100
101
102
def bool_of(self, property_name: str) -> bool | None:
    """Boolean value of child element `property_name`, or |None| if absent."""
    text = self.text_of(property_name)
    if not text:
        return None
    return text.strip().lower() in ("true", "1")