shape

shape

Objects related to shapes.

A shape is a visual object that appears on the drawing layer of a document.

_PictureShape

The picture-extraction half of an inline or floating shape.

Both wp:inline and wp:anchor wrap the same a:graphic subtree, so finding the image behind them is one implementation rather than two.

image property

image: Image | None

The Image this shape displays, or None when there is no image to return.

This is the counterpart of Run.add_picture — extracting the pictures from a document without walking the relationships by hand:

for shape in document.inline_shapes:
    if shape.image is not None:
        Path(f"{shape.image.sha1}.{shape.image.ext}").write_bytes(
            shape.image.blob
        )

None in three cases, each of which is a real document rather than an error:

• the shape is not a picture at all — a chart, a SmartArt diagram or an embedded object;
• the picture is linked rather than embedded, so the bytes are not in the package and there is nothing to hand back;
• the shape was constructed without a parent, so there is no part to resolve the relationship against.

For an SVG picture this returns the raster fallback, which is what every consumer can decode; svg_image returns the vector source.

Several shapes can share one image part, so the Image returned for two shapes may be the same object.

svg_image property

svg_image: Image | None

The SVG source of this picture, or None when it has none.

Word records an SVG picture as an asvg:svgBlip extension alongside a raster rendering of it, rather than in place of one. image returns the raster fallback; this returns the vector original.

InlineShapes

InlineShapes(body_elm: CT_Body, parent: StoryPart)

Bases: Parented

Sequence of InlineShape instances, supporting len(), iteration, and indexed access.

Source code in src/docx/shape.py

def __init__(self, body_elm: CT_Body, parent: StoryPart):
    super(InlineShapes, self).__init__(parent)
    self._body = body_elm

FloatingShapes

FloatingShapes(body_elm: CT_Body, parent: StoryPart)

Bases: Parented

Sequence of FloatingShape instances, supporting len(), iteration and indexing.

A floating shape is anchored rather than inline: it is positioned against the page, the margin, the column or the paragraph, and text wraps around it. These are a distinct collection from InlineShapes rather than part of it, because almost nothing that is true of an inline shape's position is true of a floating one's, and silently mixing the two is how code that walks inline_shapes starts reporting nonsense positions.

Source code in src/docx/shape.py

def __init__(self, body_elm: CT_Body, parent: StoryPart):
    super().__init__(parent)
    self._body = body_elm

FloatingShape

FloatingShape(
    anchor: CT_Anchor,
    parent: ProvidesStoryPart | None = None,
)

Bases: _PictureShape

Proxy for a <wp:anchor> element, a shape that text flows around.

Reached through Document.floating_shapes or returned by Run.add_float_picture.

Source code in src/docx/shape.py

def __init__(self, anchor: CT_Anchor, parent: t.ProvidesStoryPart | None = None):
    self._anchor = anchor
    self._parent = parent

allow_overlap property writable

allow_overlap: bool

Whether this shape may overlap another floating shape. Read/write.

behind_text property writable

behind_text: bool

Whether this shape is drawn behind the document text rather than over it.

Read/write. This is what "put the watermark behind the text" means; it takes effect only with wrap_type of WD_WRAP_TYPE.NONE, since any other wrap setting keeps text out of the shape's way in the first place.

description property writable

description: str | None

The alternative text of this shape, None if not set. Read/write.

height property writable

height: Length

The display height of this shape as an Emu instance. Read/write.

horizontal_align property writable

horizontal_align: WD_ANCHOR_ALIGN_H | None

Named horizontal alignment of this shape, None when an offset is used.

Read/write. Assigning an alignment replaces any left offset, and vice versa: the schema allows only one of the two, and Word ignores a shape that has both. Assigning None leaves the shape with neither, which Word treats as an offset of zero.

left property writable

left: Length | None

Horizontal offset from relative_from_h, None when aligned instead.

Read/write. See horizontal_align for how the two interact.

relative_from_h property writable

relative_from_h: WD_ANCHOR_RELATIVE_FROM_H

What left and horizontal_align are measured from. Read/write.

relative_from_v property writable

relative_from_v: WD_ANCHOR_RELATIVE_FROM_V

What top and vertical_align are measured from. Read/write.

title property writable

title: str | None

The title of this shape, None if not set. Read/write.

top property writable

top: Length | None

Vertical offset from relative_from_v, None when aligned instead.

Read/write.

vertical_align property writable

vertical_align: WD_ANCHOR_ALIGN_V | None

Named vertical alignment of this shape, None when an offset is used.

Read/write. See horizontal_align.

width property writable

width: Length

The display width of this shape as an Emu instance. Read/write.

wrap_distance property

wrap_distance: tuple[Length, Length, Length, Length]

Space held clear of this shape as (top, right, bottom, left). Read-only.

Set the individual distances with set_wrap_distance.

wrap_type property writable

wrap_type: WD_WRAP_TYPE

Member of WdWrapType describing how text wraps around this shape.

Read/write.

z_order property writable

z_order: int

Position of this shape in the stack of floating shapes. Read/write.

A higher value is drawn on top of a lower one. Independent of behind_text, which decides whether the whole floating layer this shape is in sits in front of the text or behind it.

set_wrap_distance

set_wrap_distance(
    top: Length | int | None = None,
    right: Length | int | None = None,
    bottom: Length | int | None = None,
    left: Length | int | None = None,
) -> None

Set the space held clear of this shape when text wraps around it.

Each argument left as None is unchanged. Word's own default is no clearance above and below and 0.13cm to each side, which is what a new floating picture gets here.

Source code in src/docx/shape.py

def set_wrap_distance(
    self,
    top: Length | int | None = None,
    right: Length | int | None = None,
    bottom: Length | int | None = None,
    left: Length | int | None = None,
) -> None:
    """Set the space held clear of this shape when text wraps around it.

    Each argument left as |None| is unchanged. Word's own default is no clearance
    above and below and 0.13cm to each side, which is what a new floating picture
    gets here.
    """
    anchor = self._anchor
    if top is not None:
        anchor.distT = int(top)
    if right is not None:
        anchor.distR = int(right)
    if bottom is not None:
        anchor.distB = int(bottom)
    if left is not None:
        anchor.distL = int(left)

InlineShape

InlineShape(
    inline: CT_Inline,
    parent: ProvidesStoryPart | None = None,
)

Bases: _PictureShape

Proxy for an <wp:inline> element, representing the container for an inline graphical object.

Source code in src/docx/shape.py

def __init__(self, inline: CT_Inline, parent: t.ProvidesStoryPart | None = None):
    super(InlineShape, self).__init__()
    self._inline = inline
    self._parent = parent

description property writable

description: str | None

Read/write.

The alternative text of this shape, None if not set.

This is what a screen reader announces in place of the picture, and what an automated accessibility check looks for. Word's "Alt Text" pane writes this field. Assigning None removes it.

height property writable

height: Length

Read/write.

The display height of this inline shape as an Emu instance.

type property

type

The type of this inline shape as a member of docx.enum.shape.WD_INLINE_SHAPE, e.g. LINKED_PICTURE.

Read-only.

title property writable

title: str | None

Read/write.

The title of this shape, None if not set.

Word presents this separately from the alternative text and screen readers do not generally announce it; .description is the one accessibility depends on. Assigning None removes it.

width property writable

width

Read/write.

The display width of this inline shape as an Emu instance.