object

object ¶

Custom element classes for embedded OLE objects — w:object.

Word can embed a whole file inside a document — a spreadsheet, a PDF, another document — displayed as an icon or a preview image that opens the original application on double-click. The markup is a w:object in a run, holding a VML v:shape for the visual and an o:OLEObject naming the relationship to the embedded part under word/embeddings/.

The visual is VML, not DrawingML, so none of the Run.add_picture() machinery applies. VML attribute names are not namespace-qualified the way the w: ones are, and their case is inconsistent — ProgID, ShapeID, DrawAspect — so they are taken from ref/xsd/vml-officeDrawing.xsd rather than from a sample document.

CT_OLEObject ¶

Bases: BaseOxmlElement

o:OLEObject, the element identifying the embedded file and its application.

CT_Object ¶

Bases: BaseOxmlElement

w:object, the run-level container for an embedded or linked OLE object.

oleObject `property` ¶

oleObject: CT_OLEObject | None

The o:OLEObject child, or None for a w:object that has none.

Reached by find rather than a declared child because w:object admits any v: or o: element in any order, so there is no schema sequence to place a ZeroOrOne against.

shape `property` ¶

shape: BaseOxmlElement | None

The v:shape holding the object's visual, or None when there is none.

image_rId `property` ¶

image_rId: str | None

The relationship id of the icon or preview image, or None.

The image is a v:imagedata inside the shape, related in its own right — an embedded object is at minimum two relationships plus the run XML.

iter_objects ¶

iter_objects(element: BaseOxmlElement) -> List[CT_Object]

The w:object elements under element, in document order.

Source code in src/docx/oxml/object.py

def iter_objects(element: BaseOxmlElement) -> List[CT_Object]:
    """The `w:object` elements under `element`, in document order."""
    return element.xpath(".//w:object")