Skip to content

customprops

customprops

Provides CustomProperties, the arbitrary named values a document can carry.

These are the properties stored in /docProps/custom.xml, the third document-properties part alongside the Dublin-Core properties in core.xml and the application properties in app.xml. Word shows them under File > Info > Properties > Advanced, and a DOCPROPERTY field in the document body refers to one by name.

CustomProperties 

CustomProperties(element: CT_CustomProperties)

Bases: MutableMapping[str, 'str | int | float | bool | dt.datetime | None']

A mapping of custom document property name to value.

Behaves as a dict of str to value:

document.custom_properties["Matter number"] = 4242
document.custom_properties["Reviewed"] = True
del document.custom_properties["Draft"]

A value may be a str, int, float, bool or datetime, which cover the variant types Word writes and read back as the same Python type. Assigning any other type raises ValueError rather than writing a file Word would refuse to open.

A property whose value uses a variant this library does not model — a vector, array or blob — reads as the raw text of its element, so a document that carries one can still be read and re-saved without losing it.

Property names are case-sensitive and must be unique; assigning to an existing name replaces its value and leaves its property id alone.

Source code in src/docx/opc/customprops.py 
41
42
def __init__(self, element: CT_CustomProperties):
    self._element = element

lookup_by_pid 

lookup_by_pid(
    pid: int,
) -> str | int | float | bool | datetime | None

The value of the property having property id pid.

Raises KeyError when no property has that id. Property ids matter only for documents that reference a property by id rather than name; the mapping interface is the ordinary way in.

Source code in src/docx/opc/customprops.py 
77
78
79
80
81
82
83
84
85
86
87
def lookup_by_pid(self, pid: int) -> str | int | float | bool | dt.datetime | None:
    """The value of the property having property id `pid`.

    Raises |KeyError| when no property has that id. Property ids matter only for
    documents that reference a property by id rather than name; the mapping
    interface is the ordinary way in.
    """
    for property in self._element.property_lst:
        if property.pid == pid:
            return property.value
    raise KeyError(pid)